Show TOC

Background documentationNavigation Cache Locate this document in the navigation structure

 

The portal provides a mechanism for caching navigation nodes, which improves performance.

For example, the first time a user assigned to the User Administration role enters the portal, the navigation service retrieves the navigation nodes from the roles connector. The next time any user with the role enters the portal, the nodes are retrieved from the cache.

You can control if and how the portal caches the navigation nodes created by your custom navigation connectors. This section describes steps for enabling caching of navigation nodes from your connector. For more information about navigation connectors, see Creating Navigation Connectors.

You can also access and manage the navigation cache programmatically. For more information, see Managing the Navigation Cache.

Administrators can manage caching, for example, by disabling caching or clearing the cache of nodes from specific connectors. For more information, see Caching Navigation Nodes.

Note Note

The navigation cache feature may not work properly if a custom PCD filter is deployed, and the filter returns different nodes for different situations. In such cases, an administrator can turn off the cache.

End of the note.
Entry Points and Nodes

The navigation cache stores nodes separately for each connector. For each connector, there are two node collections:

  • Entry Points: The nodes returned by getInitialNodes(). Entry points are cached with a unique key, or discriminator. For example, for the roles connector, each set of entry points of a role might be cached with the name of the role as the key.

    For each entry point, the cache contains the node name, its hashed value, and its children.

  • Navigation Nodes: The children of the entry points, and their children.

    For each node, the cache contains the key properties of the node, its hashed value, and its children.

Runtime Flow

In order to enable caching, each connector that you register with the navigation service is automatically wrapped inside another connector - a caching connector - that adds caching capabilities. This object provides for the following runtime flow:

  1. When a request is made for the connector's initial nodes with a call to getInitialNodes(), the wrapper calls the connector's getCacheDiscriminators() method for a list of cache discriminators. In the call, the wrapper passes the environment variables it received in the getInitialNodes() method.

  2. The connector returns a list of cache discriminators.

  3. For each discriminator, the wrapper checks if navigation nodes are cached for that key.

    • If nodes are cached (and the cache is valid), the wrapper takes the nodes from the cache.

    • If no nodes are cached, the following occurs:

      1. The wrapper calls the connector's getInitialNodes() method to get the nodes, passing the discriminator in the environment parameter with the key INavigationConstants.CACHE_DISCRIMINATOR_PARAM_NAME.

      2. The connector returns the nodes for the specific discriminator.

      3. The wrapper caches the nodes, using the discriminator as a key.

  4. The wrapper collects all the nodes, and returns them as the initial nodes.

Runtime Flow (Single Node)

A navigation connector can also provide a discriminator for a single node, in order to provide different versions of the same node.

  1. When a request is made for a specific node, the wrapper calls to getNodeDiscriminator() method for the cache discriminator key that was used for saving node in the cache. By default, the node discriminator is the connector node name parameter of the getNode() method.

  2. The wrapper checks if a node is cached for the key.

    • If a node is cached (and the cache is valid), the wrapper takes the node from the cache.

    • If no node is cached, the wrapper calls the connector's getNode() method and caches it using the discriminator key.

Procedure

To implement caching for your connector, implement the following methods in the navigation connector (the class that extends AbstractNavigationConnector):

  1. Implement getCacheDiscriminators(), and return a list of keys that will be used to cache the navigation nodes.

    For example, the Roles connector can return the names of all the entry points (top-level nodes).

  2. When implementing getInitialNodes(), return different navigation nodes based on the discriminator passed into the method.

    For example, the Roles connector would return the System Administration entry point node if the discriminator were System Administration.

    The discriminator is passed in the environment variables with the key INavigationConstants.CACHE_DISCRIMINATOR_PARAM_NAME. A discriminator is only passed into the method if caching is enabled.

    Note Note

    Make sure to match the getCacheDiscriminators() and getInitialNodes() methods, so that each responds to the environment variables in the same way. If getCacheDiscriminators() returns different discriminators based on the user, then getInitialNodes() must also return different nodes based on the user.

    In addition, getInitialNodes() must return different nodes for each discriminator returned by getCacheDiscriminators().

    End of the note.

  3. Implement getNodeDiscriminator(), and return a discriminator for the specified node. The method is called when a node is requested with a call to getNode().

    This method is optional. Implement this method if you want different versions of some or all nodes to be cached separately.

    By default, the node discriminator is the connector node name as provided in the parameter of the getNode() method.

  4. Implement getConnectorProfile(), and return a NavigationConnectorProfile object. Before returning the object, call methods on the object to set the caching properties for your connector.

    An NavigationConnectorProfile also lets you specify additional properties to be loaded into cache for each node.

Performance

Implement getCacheDiscriminators() and getNodeDiscriminator() as efficiently as possible, as these methods are called every time the initial nodes or a specific node are needed, even if caching is enabled.