Learn about the main object models used in
the navigational state SPI.
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 which can be 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 you 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 that contains
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)
- Specifies whether the URL should point to the public or protected
area.
- void setSecure(Boolean flag)
- Specifies 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 that the EngineURL object
is no longer needed. The EngineURL object
must not be accessed again after invoking this method. Alternatively,
you 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.
Note: 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.