Object Model
Navigational state
The Navigational state object model is a hierarchy of state information, which is modeled as a DOM-like document containing untyped state information represented as strings because a typical page contains many URLs that require the navigational state to be serialized multiple times per request. The string-based memory allows for efficiently serializing navigational states into URLs, because it avoids processing time and CPU consuming object to string conversions during the serialization process.
The Navigational state is modeled via the following interfaces:
- com.ibm.portal.state.StateHolder
- com.ibm.portal.state.StateHolderController
- com.ibm.portal.state.dom.DocumentModel
- com.ibm.portal.state.dom.DocumentController
The StateHolder interface provides read access to the navigational state information by exposing a getModel() method that returns an interface to the untyped document model, namely the DocumentModel interface. The DocumentModel interface provides a set of methods to inspect both the hierarchical structure of the state document as well as single nodes being part of that document.
In addition, the StateHolder interface offers a newState() method used to create a clone of that particular StateHolder instance. This is an important method because, typically, the current navigational state has to be cloned before modifying it according to the specific semantics of the generated URL. For example if the programmer wants to create a URL that points to a particular portal page, the page selection information in the state document model has to be changed; however, this modification must not take effect on all URLs of a page.
Beyond that, the StateHolderController interface also allows us to modify state information by offering a getController() method that delivers a controller interface to the untyped state document called DocumentController. The DocumentController interface provides a means to modify the hierarchical structure of the state document, which includes creating document nodes, inserting them into the node hierarchy, and removing nodes.
Engine URLs
URLs are modeled via the com.ibm.portal.state.EngineURL interface. An EngineURL represents a URL containing navigational state. The initial StateHolder an EngineURL refers to is specified when requesting a new EngineURL instance from the appropriate URL factory; see URL generation services for additional information. Typically it is a copy of the request-specific base state.
The EngineURL interface provides the following methods:
- StateHolderController getState()
- Returns a read-write interface to the navigational state carried by the URL.
- void setProtected(Boolean flag)
- Whether the URL should point to the public or protected area.
- void setSecure(Boolean flag)
- Whether a secure https connection is required.
- Writer writeCopy(Writer out)
- Streams the URL to the given writer. Maintains the state of the URL. For example this method can be used to write the URL multiple times.
- Writer writeDispose(Writer out)
- Streams the URL to the given writer and finally releases the state of the URL. The EngineURL object must not be accessed again after invoking this method.
- void dispose()
- The dispose() method is inherited from the Disposable interface. It must be invoked to indicate the EngineURL object is no longer needed. The EngineURL object must not be accessed again after invoking this method. Alternatively, we can invoke the writeDispose() method, which calls dispose().
The crucial method is the getState() method, which returns the state holder object this particular EngineURL instance refers to.
The method returns a controller interface (StateHolderController) that allows the programmer to modify the state of this EngineURL. See Accessor SPI for additional information about modifying the state.
Resource URLs
URLs that address generic resources such as, but not limited to, files, icons, and voice grammars cannot contain navigational states and are therefore modeled using a separate interface called com.ibm.portal.state.DisposableURL. The DisposableURL interface almost offers the same methods as EngineURL but does not provide a getState() method.
Resource URLs can also be created using the URL generation Services that are offered along with the Navigational State SPI. See URL generation services for additional information.