Exploring Navigational state SPI websphere portal8

Navigational State :- Is nothing but storing the state of the current users navigation in url. By clicking back button user can navigate to his previous state.

Navigational SPI provides two services :-

• Portal state manager is used to create navigation urls in themes and skins
• Portlet state manager is used to create navigation urls in portlets

Main package :-  com.ibm.portal.state

Main object model used in Navigational state api :- 

                           Navigate state object is modeled as document model structure. It has models and controllers which will give control of state. Using this we can create urls with full navigation state.

The Navigational state is modeled via the following interfaces:

• com.ibm.portal.state.StateHolder{getModel(),newState()}
• com.ibm.portal.state.StateHolderController{getController()}
• com.ibm.portal.state.dom.DocumentModel
• com.ibm.portal.state.dom.DocumentController {allows to modify nav structure}

Engine URLs more abstract layer of above classes:- 

URLs are modeled via the com.ibm.portal.state.EngineURL interface. An EngineURL represents a URL that contains navigational state. The initial StateHolderan EngineURL refers to is specified when requesting a new EngineURL instance from the appropriate URL factory; 

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 EngineURLobject 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. 

Accessor SPI:-  Its high level abstraction for Object model

The Accessor SPI is an abstract layer surrounding the access to particular nodes in the hierarchical document model; see Object Model for additional information about the hierarchical document model. For each state aspect such as, but not limited to, page selection, expansion states, and portlet states, the SPI offers an accessor factory that provides read-only and read-write accessor controls that are designed for the particular state aspect they refer to. The accessors read from or write to the respective positions in the state document model and perform required type conversions.

The navigational state information is located in the state document model and is available when the accessor factory is used. After the node is located, the accessor factory passes a node reference to the accessor or accessor controller during. The accessor and accessor controller are independent from the state document model structure; you can reuse accessors even if the information is moved to another node in the state document.

For example, the SelectionAccessorFactory offers the following interfaces:

SelectionAccessor getSelectionAccessor(StateHolder)

This method returns a SelectionAccessor interface that allows for reading page selection information from the given StateHolder.

SelectionAccessorController getSelectionAccessorController(StateHolderController)

This method returns a SelectionAccessorController interface that allows programmers to modify page selection information. The controller uses theStateHolderController interface to modify the navigational state accordingly.

The flyweight pattern – the StateHolder or StateHolderController is used as an argument – is commonly used in the accessor factory interfaces. The navigational state the accessor operates on may not be the base state retrieved from the request URL; typically, it is the state clone created for a particular EngineURL. CallgetState() on the EngineURL object to obtain the URL-specific state holder. The following example shows how to let a created EngineURL point to a certain portal page (for example, the “Stock Market” page) using the SelectionAccessorController:

final EngineURL url = ...;

final SelectionAccessorFactory selectionFct = ...;

final SelectionAccessorController selectionCtrl = 

    selectionFct.getSelectionAccessorController(url.getState());

try {

    selectionCtrl.setSelection(“wps.StockMarket”);

} catch (StateException e) {

    // include error handling here

} finally {

    selectionCtrl.dispose();

}

Using the SelectionAccessorController to create a page link

The base Accessor interface is derived from the com.ibm.portal.Disposable interface. Invoke the dispose() method to indicate when the accessor is no longer required. Using the dispose() method allows the accessor factory to store the accessors and accessor controllers in object pools to achieve better performance (due to less initialization and garbage collection overhead).

The Navigational State SPI offers the following accessor factories, each covering a certain state aspect:

SelectionAccessorFactory

The SelectionAccessorFactory provides accessors to read and write portal page selection information. To create a URL that points to another page, theSelectionAccessorController needs to be requested from the factory in order to include the new selection into the state the created EngineURL is associated with

PortletAccessorFactory

The PortletAccessorFactory provides accessors to read and write portlet-related navigational state information, which includes portlet mode, window state, and render parameters. In particular the PortletAccessorController can be used to change the navigational state of a given portlet (for example, the portlet mode).

PortletTargetAccessorFactory

The PortletTargetAccessorFactory provides accessors to read and write portlet action-related information. In particular the PortletAccessorControllercan be used to declare a portlet as the target of an action. This allows the programmer to create URLs that trigger portlet actions.

SoloAccessorFactory

The SoloAccessorFactory provides accessors to read and write the so-called Solo state. If the portal is in Solo state, it renders only one particular portlet of the current portal page; all navigation controls and tool bars are hidden. The SoloAccessorController can be used to create URLs that activate/deactivate the Solo state for a particular portlet.

ThemeTemplateAccessorFactory

The ThemeTemplateAccessorFactory supports reading and writing theme template information. In particular the ThemeTemplateAccessorController can be used to create URLs that switch to a certain theme template.

LocaleAccessorFactory

The LocaleAccessorFactory provides accessors to read and write locale information. The LocaleAccessorController can be used to set a special locale into the navigational state and thus into a URL.
Note: A locale retrieved from such a URL takes precedence over user preferred locales or locales defined on the user’s browser.

ExpansionStatesAccessorFactory

The ExpansionStatesAccessorFactory provides accessors to read and write expansion states information; for example, to determine whether a given navigation node in a navigation tree control is expanded or collapsed. The ExpansionStatesAccessorController is typically used to generate URLs that toggle the expansion state of a navigation node.

ShowToolsAccessorFactory

The ShowToolsAccessorFactory provides accessors to read and write tool-related information. The ShowToolsAccessorController is typically used to create a URL that blends in the tool icons for portlet windows offering function such as moving/deleting the respective portlet.

StatePartitionAccessorFactory

The StatePartitionAccessorFactory provides accessors to read and write state partition identifiers. The StatePartitionAccessorController can be used to include a state partition identifier into the navigational state. A new state partition identifier should be included into URLs that open new browser windows or iFrames.

EngineActionAccessorFactory

The EngineActionAccessorFactory provides controllers that should be used to create engine action URLs. The EngineActionAccessorController, in particular, allows you to set action parameters.

After studying about Navigation state, Portlet/Portlal state manager, Object model, Accessor api, Engine url, SelectionAcessContoller. Everyone confused even i am when i am first time exploring it. Please have a look at next blog post for examples to get full understanding.