Java URL Optimization API (Core API) 2.1.1

Package com.endeca.soleng.urlformatter

The core of the URL Optimization API containing the fundamental components required for URL manipulation and generation - including the primary UrlState class and its related UrlFormatter and QueryBuilder interfaces.


Interface Summary
AggrERecUrlParam An interface used internally by an UrlState to store an AggrERec for aggregate record detail page links.
ERecUrlParam An interface used internally by an UrlState to store an ERec for record detail page links.
NavStateUrlParam An interface used internally by an UrlState to manage state for navigation pages.
QueryBuilder An interface that is responsible for marshaling UrlState objects into ENEQuery objects.
UrlFormatter An interface that is responsible for formatting UrlState objects into URL strings.
UrlParam An interface used internally by an UrlState to store a single URL parameter.

Class Summary
UrlState An object that represents URL state for a web application request - a central component for this API.

Exception Summary
QueryBuildException Indicates that an error occurred while marshaling an UrlState into an ENEQuery object.
UrlFormatException Indicates that an error occurred while formatting an UrlState object into an URL string - or while parsing a request into an UrlState.

Package com.endeca.soleng.urlformatter Description

The core of the URL Optimization API containing the fundamental components required for URL manipulation and generation - including the primary UrlState class and its related UrlFormatter and QueryBuilder interfaces.

API Overview and Usage Guide


This overview contains the following sections:

See Also:
URL Optimization API Overview

URL Optimization API Overview

At a high-level, the URL Optimization API consists of three primary objects and interfaces:

Note that the following examples reference the urlformatter_jspref application. For instructions on how to install this application, see the URL Optimization for Java Developer's Guide (available for download from EDeN).

See Also:
BasicQueryBuilder - a QueryBuilder implementation for creating ENEQuery objects.
BasicUrlFormatter - an UrlFormatter implementation for managing traditional (query-string) URLs.

Creating an UrlFormatter and QueryBuilder

An object that implements the UrlFormatter interface should be instantiated to enable the creation of optimized URLs. We refer to this as an UrlFormatter object. The UrlFormatter object should be global, and will store application level URL format settings, such as default encoding and path separator tokens. Typically, the global UrlFormatter object is used as a parameter for the UrlState constructor calls. The urlformatter_jspref reference application uses the SeoUrlFormatter class, a subclass of UrlFormatter.

Before instantiating an UrlFormatter object, you should first check whether a UrlFormatter has already been created for the application. If not, instantiate the UrlFormatter and store it as an attribute in the ServletContext as is shown below.

 // Create a globally scoped UrlFormatter.
 UrlFormatter urlFormatter = (UrlFormatter)application.getAttribute("urlFormatter");
 if(null == urlFormatter) {
   urlFormatter = new SeoUrlFormatter();
   // Configure the UrlFormatter here.
   application.setAttribute("urlFormatter", urlFormatter);

Similarly, you should instantiate a QueryBuilder object and store this at the application scope. This QueryBuilder object will be used to marshal UrlState objects into ENEQuery objects.

 // Create a globally scoped QueryBuilder.
 QueryBuilder queryBuilder = (QueryBuilder)application.getAttribute("queryBuilder");
 if(null == queryBuilder) {
   queryBuilder = new BasicQueryBuilder();
   // Configure the QueryBuilder here.
   application.setAttribute("queryBuilder", queryBuilder);
See Also:

Parsing the Incoming Request and Querying an MDEX Engine

Since the URLs may not contain querystring parameters (these parameters might be stored in the path), it is no longer possible to use the UrlENEQuery class to create an ENEQuery. Instead, the buildQuery method of the queryBuilder class should be used to create the ENEQuery. The buildQuery method takes one argument: the UrlState object that represents the current request. This method returns the ENEQuery.

 // Parse the incoming request and build an ENEQuery.
 UrlState requestUrlState = urlFormatter.parseRequest(request);
 ENEQuery eneQuery = queryBuilder.buildQuery(requestUrlState);

 // Execute the query.
 HttpENEConnection conn = new HttpENEConnection(mdexHost, mdexPort);
 ENEQueryResults eneQueryResults = conn.query(eneQuery);
See Also:

Creating an Empty URL State

It is possible to create an empty UrlState object by using the UrlState constructor. The constructor takes two arguments: an UrlFormatter object, and encoding for the UrlState.

 UrlState emptyUrlState = new UrlState(urlFormatter, request.getCharacterEncoding());

A UrlState may be cloned to create another UrlState, as shown in the following sample.

 // Clone the UrlState generated from the incoming request.
 UrlState informedUrlState = (UrlState)emptyUrlState.clone();
See Also:
UrlState.UrlState(UrlFormatter, java.lang.String)

Creating an Informed URL State

To be usable to create ancestor or refinement links, a UrlState must first be "informed" by the results of an Endeca query. The following sample shows how a UrlState may become informed.

 // Clone the UrlState generated from the incoming request.
 UrlState informedUrlState = (UrlState)requestUrlState.clone();

 // Inform the baseUrlState of data contained within the ENEQueryResults.

 // Remove unwanted parameters.
See Also:

Selecting Navigation Refinements

At any specific navigation state, it may be possible to refine the set of result records by specific dimension values. For example, in the urlformatter_jspref reference application, while viewing all wines from Napa (Napa dimension value of Region dimension has been selected), it is possible to refine the result set by Winery, Price Range, Review Score, and a number of other dimensions. Each of these dimensions may have a number of possible refinement values.

The following code displays how to loop through multiple dimensions and dimension values, to achieve this functionality.

 // Iterate over the refinement dimensions.
 DimensionList refDims = navigation.getRefinementDimensions();
 for(int i = 0; i < refDims.size(); i++) {
   Dimension refDim = (Dimension)refDims.get(i);

   // Iterate over the refinement dimvals.
   DimValList refDimVals = refDim.getRefinements();
   for(int j = 0; j < refDimVals.size(); j++) {
     DimVal refDimVal = (DimVal)refDimVals.get(j);

     // Select the refinement.
     UrlState refinedUrlState =
         informedUrlState.selectRefinement(refDim, refDimVal, true);

     // Generate the refinement URL string.
     String refinedUrl = refinedUrlState.toString();
See Also:
UrlState.selectRefinement(com.endeca.navigation.DimLocation pRefinement, boolean pClone)

Removing Descriptor Dimensions

Once the user has selected dimension values, additional queries can be generated for removing a selection. A descriptor is a specific type of selected dimension value. The descriptor is the hierarchically lowest selected dimension value for a dimension. For example, the user might select dimension values Red, Zinfandel and Napa in the urlformatter_jspref reference application. Following is an example URL:

The user may wish to remove a descriptor such as Napa from the URL.

In order to remove descriptor dimensions from the URL, the following code could be used:

 // Iterate over the descriptor dimensions.
 DimensionList descDims = navigation.getDescriptorDimensions();
 for(int i = 0; i < descDims.size(); i++) {
   Dimension descDim = (Dimension)descDims.get(i);
   DimVal descDimVal = descDim.getDescriptor();

   // Remove the descriptor.
   UrlState expandedUrlState =
       informedUrlState.removeDescriptor(descDimVal, true);

   // Generate the expanded URL string.
   String expandedUrl = expandedUrlState.toString();
See Also:
UrlState.removeDescriptor(com.endeca.navigation.DimVal pDescriptor, boolean pClone)

Selecting Ancestor Dimensions

When viewing record details either on the record detail page, or in the record list, such as a search results page, the user may be presented with a request link to select an ancestor of a dimension tagged to the specific record. For example, while viewing details for the Merlot Carneros Sangiacomo Vineyard wine in the urlformatter_jspref reference application, the user can select to view all Red wines. In this case, Red Wine dimension is an ancestor of Merlot.

The following code displays how to loop through the ancestor values across a particular dimension.

 // Iterate over the ancestor dimvals.
 DimVal descDimVal = descDim.getDescriptor();
 DimValList ancestors = descDim.getAncestors();
 for(int i = 0; i < ancestors.size(); i++) {
   DimVal ancestor = (DimVal)ancestors.get(i);

   // Select the ancestor.
   UrlState ancestorUrlState =
       informedUrlState.selectAncestor(ancestor, descDimVal, true);

   // Generate the ancestor URL string.
   String ancestorUrl = ancestorUrlState.toString();
See Also:
UrlState.selectAncestor(com.endeca.navigation.DimVal pAncestor, com.endeca.navigation.DimVal pDescriptor, boolean pClone)

Handling Dimension Search Results

When query results contain dimension search results, the application may display these results along with the associated request links. For example, when the user searches for "cherry" in the urlformatter_jspref reference application, the search returns a number of dimension values that matched the query, such as "Cherry Hill winery", and "Cherry flavor".

The following code displays how to create links for the Dimension Search Results:

 // Iterate over the dimension search result groups.
 DimensionSearchResult dimSearchResult = results.getDimensionSearch();
 DimensionSearchResultGroupList groups = dimSearchResult.getResults();
 for(int i = 0; i < groups.size(); i++) {
   DimensionSearchResultGroup group = (DimensionSearchResultGroup)groups.get(i);

   // Iterate over each resulting DimLocationList.
   long max = Math.min(3, group.getTotalNumResults());
   for(int j = 0; j < max; j++) {
     DimLocationList dimLocations = (DimLocationList)group.get(j);

     // Construct an UrlState for the search result.
     UrlState dsrUrlState = new UrlState(urlFormatter, request.getCharacterEncoding());

     // Generate the dim search result URL string.
     String dsrUrl = dsrUrlState.toString();
See Also:
UrlState.setNavState(com.endeca.navigation.DimLocationList pDimLocationList)

Java URL Optimization API (Core API) 2.1.1

Copyright © 2012 Endeca Technologies, Inc. All Rights Reserved.
PRODUCT: Java URL Optimization API (Core API) (urlFormatterCore)
VERSION: 2.1.1
BUILD:   12083DEV
ARCH_OS: n/a
DATE:    2012-02-16T20:40:08-0500