Class next.wo.Context

CLASS DESCRIPTION

Extends:
next.util.NextObject

A Context object lets you access objects and information that define the context of a transaction. In a typical request-response loop (a transaction), several objects have a hand in what is going on: the WebApplication and WebSession objects, the page involved in the request or response (a Component object), the page's subcomponents (also Components), plus the dynamic elements on the page. The Context object passed as argument in the takeValuesFromRequest, invokeAction, and appendToResponse messages allows access to these objects. A context is identified by its own unique, randomly generated context ID, which appears in the URL after the session ID and page name.

Context objects provide other information and services related to the current transaction. From them you can get the entire URL currently in effect as well as portions of that URL, such as the element ID, the context ID, and the URL up to and including the session ID. (See "Element IDs," below, for a description of what element IDs are and how and why you manipulate them.)

Contexts also allow you to affect load balancing with the setDistributionEnabled method; if the flag set by this method is false (the default), transactions of the session are restricted to a single application instance. If this the case, the application instance number as well as the application host name are appended to the URL.

The following graphic shows a complete URL: the parts after the application name are added by a WebObjects application:

Diagram depicting parts of URL
Figure 1: Parts of a URL

A Context object plays a further role behind the scenes. For the benefit of a page's dynamic elements, it keeps track of the current component, that is, the Component associated with the current element in the request-handling cycle. The current component can be the Component that represents one of the page's subcomponents or the page itself. By reference to the current component (accessed through Context's component method), a dynamic element can exchange values associatively between itself and the Component that contains it.

Element IDs

The Context class includes several methods for constructing element IDs, which are used to identify dynamic and static elements on a page. As the graph of objects on the page's dynamic template is traversed, the element ID is incremented and decremented to identify, like a "cursor," nodes in the object graph. A dynamic element creates and assigns element IDs for its "child" elements in the appendToResponse method when the page on which it appears is first accessed. A dynamic element re-creates the same element IDs in the takeValuesFromRequest phase and then uses them to extract form values for input. Finally, in the invokeAction phase, a dynamic element can determine if it is the originator of an action by comparing the reconstructed element ID to the sender ID carried in the URL; if they are the same ID, it then triggers the action method.
Note: See the class description of DynamicElement for an overview of dynamic-element creation and for more on how element-ID manipulation figures into this activity.

Element IDs are composed according to a dot-separated number scheme that structurally reflects the object graph of HTML elements on a page. An example will help clarify this scheme. Suppose you have a dynamic element made from a form with two input fields. Above this dynamic element in the object graph is the <BODY> HTML element, from which also descends a level-2 heading. Above the <BODY> element is the <HTML> element, the root element in the object graph. The following graphic illustrates these relationships and shows the assigned element IDs.

Diagram of correspondence between element IDs and object-graph position
Figure 2: Element ID and position in the object graph

As you can see, there is a level/position correspondence between an object in the graph and its representation in the element ID. To identify its child elements, the dynamic element would send the following sequence of messages to the Context object:

    // .. first element: input field 1
    aContext.appendZeroElementIDComponent(); // 0.1.0 --> 0.1.0.0
    // ...next element: input field 2
    aContext.incrementLastElementIDComponent(); // 0.1.0.1 
    // ...done, returning to parent, so delete last digit
    aContext.deleteLastElementIDComponent(); // 0.1.0
 
(Note that the Submit button is not assigned an element ID. In this case, the form itself (<FORM>), which is identified with the dynamic element, is responsible for triggering the action method.)

Note that you don't necessarily have to use digits as components of an element ID. With appendElementIDComponent you can append strings as components (for example, "0.1.0.UserField"). Regardless of how you implement the scheme, you must be consistent in applying that scheme in the takeValuesFromRequest and appendToResponse methods.


CONSTRUCTORS

Context

public Context()

Returns a Context instance initialized with a unique context ID. The isDistributionEnabled flag is set to false, meaning that each transaction will be assigned to an application instance specified in a configuration file for load balancing.


METHODS

appendElementIDComponent

public void appendElementIDComponent(java.lang.String aString)

Appends a string to the current element ID to create an identifier of an HTML element. For example, if the current element ID is "0.1.1" and you send this message with an argument of "NameField," the element ID for that field becomes "0.1.1.NameField".

See Also: deleteAllElementIDComponents, deleteLastElementIDComponent, incrementLastElementIDComponent


appendZeroElementIDComponent

public void appendZeroElementIDComponent()

Appends a ".0" to the current element ID to create an identifier of the first "child" HTML element. For example, if the current element ID is "0.1.1", after you send this message the element ID becomes "0.1.1.0".

See Also: deleteAllElementIDComponents, deleteLastElementIDComponent, incrementLastElementIDComponent


application

public next.wo.WebApplication application()

Returns the WebApplication object that manages the application.

See Also: component, page, request, response, session


component

public next.wo.Component component()

Returns the component that dynamic elements are currently using to push and pull values associatively. This component could represent the current request or response page or a subcomponent of that page.

See Also: application, Component class, page, request, response, session


contextID

public java.lang.String contextID()

Returns the context ID of the receiver.


deleteAllElementIDComponents

public void deleteAllElementIDComponents()

Deletes all components of the current element ID.

See Also: appendElementIDComponent, appendZeroElementIDComponent, incrementLastElementIDComponent


deleteLastElementIDComponent

public void deleteLastElementIDComponent()

Deletes the last digit (or name) of the current element ID, along with its dot separator. Thus, after sending this message, "0.0.1.1" becomes "0.0.1".

See Also: appendElementIDComponent, appendZeroElementIDComponent, incrementLastElementIDComponent


elementID

public java.lang.String elementID()

Returns the element ID identifying the current Element.


incrementLastElementIDComponent

public void incrementLastElementIDComponent()

Increments the last digit of the current element ID. For example, after this message is sent, "0.0.1.2" becomes "0.0.1.3".

See Also: appendElementIDComponent, appendZeroElementIDComponent, deleteAllElementIDComponents, deleteLastElementIDComponent


isDistributionEnabled

public boolean isDistributionEnabled()

Returns whether state distribution among multiple application instances is enabled. Returns false by default since the default SessionStore (state in the server) does not allow distribution. If this flag is disabled, a specific application instance (whose identifying number is embedded in the URL) is assigned to the session.

See Also: setDistributionEnabled


page

public next.wo.Component page()

Returns the Component object that represents the request or response page.

See Also: application, component, request, response, session


request

public next.wo.Request request()

Returns the transaction's Request object.

See Also: application, component, page, response, session


response

public next.wo.Response response()

Returns the transaction's Response object.

See Also: application, component, page, request, session


session

public next.wo.WebSession session()

Returns the object representing the transaction's session.

See Also: application, component, page, request, response, WebSession class


setDistributionEnabled

public void setDistributionEnabled(boolean flag)

Enables or disables the distribution mechanism that effects load balancing among multiple application instances. When disabled (the default), generated URLs include the application instance number; the adaptor uses this number to route the request to the specific application instance based on information in the configuration file. When this flag is enabled, generated URLs do not contain the application instance number, and thus transactions of a session are handled by whatever application instance is available.

See Also: isDistributionEnabled


url

public java.lang.String url()

Returns the current URL, including page name, context ID, current element ID, and application name and host.

See Also: urlSessionPrefix


urlSessionPrefix

public java.lang.String urlSessionPrefix()

Returns the prefix of the URL that remains constant throughout the session. The following is an example:

    http://dude/cgi-bin/WebObjects/MyApp.woa/182294512835004837261898238455

The long number concluding the URL is the session ID.

See Also: url