|
Java URL Optimization API (Core API) 2.1.0 | |||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |
UrlState
class and its related UrlFormatter
and
QueryBuilder
interfaces.
See:
Description
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 . |
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.
This overview contains the following sections:
At a high-level, the URL Optimization API consists of three primary objects and interfaces:
UrlState
- the primary object for managing Endeca URL state. This class includes functions
for selecting navigation refinements, removing descriptors, selecting ancestors,
and adding/removing other query parameters.
UrlFormatter
- responsible for transforming UrlState
objects to and from URL
strings.
parseRequest(HttpServletRequest)
- transforms the specified request object into an UrlState
object.
formatUrl(UrlState)
- transforms the specified UrlState
object into an URL string.
QueryBuilder
- responsible for marshaling UrlState
objects into MDEX
Engine queries.
buildQuery(UrlState)
- marshals the specified UrlState
object into an ENEQuery
.
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).
BasicQueryBuilder
- a QueryBuilder
implementation for creating ENEQuery
objects.
BasicUrlFormatter
- an UrlFormatter
implementation for managing traditional (query-string) URLs.
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); }
BasicQueryBuilder
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);
UrlFormatter.parseRequest(HttpServletRequest)
QueryBuilder.buildQuery(UrlState)
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();
UrlState.UrlState(UrlFormatter, java.lang.String)
UrlState.clone()
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. informedUrlState.inform(eneQueryResults); // Remove unwanted parameters. informedUrlState.removeParam("sid");
UrlState.inform(ENEQueryResults)
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(); } }
UrlState.selectRefinement(com.endeca.navigation.DimLocation pRefinement, boolean pClone)
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:
http://localhost:8080/urlformatter_jspref/controller/Wine-Red-Zinfandel/Napa/_/N-8028+4294967160?Ne=8The 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(); }
UrlState.removeDescriptor(com.endeca.navigation.DimVal pDescriptor, boolean pClone)
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(); }
UrlState.selectAncestor(com.endeca.navigation.DimVal pAncestor, com.endeca.navigation.DimVal pDescriptor, boolean pClone)
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()); dsrUrlState.setNavState(dimLocations); // Generate the dim search result URL string. String dsrUrl = dsrUrlState.toString(); } }
UrlState.setNavState(com.endeca.navigation.DimLocationList pDimLocationList)
|
Java URL Optimization API (Core API) 2.1.0 | |||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |
@VERSION PRODUCT: Java URL Optimization API (Core API) (urlFormatterCore) VERSION: 2.1.0 BUILD: 12010DEV ARCH_OS: n/a DATE: 2010-06-29T04:02:40-0400