com.endeca.soleng.urlformatter
Class UrlState

java.lang.Object
  com.endeca.soleng.urlformatter.UrlState

All Implemented Interfaces:

java.lang.Cloneable

public class UrlState
extends java.lang.Object
implements java.lang.Cloneable

An object that represents URL state for a web application request - a central component for this API. This object is transformed into URL strings via UrlFormatter objects and marshaled into ENEQuery objects via QueryBuilder objects.

See Also:

UrlFormatter, QueryBuilder

Constructor Summary

UrlState(UrlFormatter pUrlFormatter, java.lang.String pEncoding)
Constructs an empty UrlState object.

Method Summary

void	clearNavState() Clears any existing navigation state from this UrlState.
java.lang.Object	clone() Returns a cloned instance of this UrlState object.
boolean	containsAggrERec() Returns true if this UrlState contains an AggrERec parameter.
boolean	containsERec() Returns true if this UrlState contains an ERec parameter.
boolean	containsNavState() Returns true if this UrlState contains a navigation state parameter.
com.endeca.navigation.AggrERec	getAggrERec() Returns the associated AggrERec for this UrlState.
java.lang.String	getEncoding() Returns the character encoding that is used when marshaling parameters and strings contained within this UrlState.
com.endeca.navigation.ERec	getERec() Returns the associated ERec for this UrlState.
com.endeca.navigation.DimLocationList	getNavState() Returns the navigation state for this UrlState or null if there is no navigation state.
java.lang.String	getParam(java.lang.String pKey) Returns the value associated with the specified key in the underlying parameter map.
java.util.Collection	getParameters() Returns a collection of all UrlParam mappings contained within this UrlState.
UrlParam	getUrlParam(java.lang.String pKey) Returns the full UrlParam value associated with the specified key in the underlying parameter map.
void	inform(com.endeca.navigation.ENEQueryResults pENEQueryResults) Initializes this UrlState using state from the specified ENEQueryResults.
UrlState	removeDescriptor(com.endeca.navigation.DimVal pDescriptor, boolean pClone) Removes the specifed descriptor DimVal from the current navigation state.
void	removeNavState() Fully removes any navigation state from this UrlState.
java.lang.String	removeParam(java.lang.String pKey) Removes any value associated with the specified key from the underlying parameter map.
UrlState	selectAncestor(com.endeca.navigation.DimVal pAncestor, com.endeca.navigation.DimVal pDescriptor, boolean pClone) Selects an ancestor DimVal for the specified descriptor DimVal.
UrlState	selectRefinement(com.endeca.navigation.Dimension pRefinementDimension, com.endeca.navigation.DimVal pRefinement, boolean pClone) Selects a navigation refinement DimVal from the specified refinement Dimension.
UrlState	selectRefinement(com.endeca.navigation.DimLocation pRefinement, boolean pClone) Selects a navigation refinement using a DimLocation object.
void	setAggrERec(com.endeca.navigation.AggrERec pAggrERec) Sets the associated AggrERec for this UrlState.
void	setERec(com.endeca.navigation.ERec pERec) Sets the associated ERec for this UrlState.
void	setNavState(com.endeca.navigation.DimensionList pDescriptorDimensionList) Sets the navigation state for this UrlState using a DimensionList.
void	setNavState(com.endeca.navigation.DimLocationList pDimLocationList) Sets the navigation state for this UrlState using a DimLocationList.
void	setNavState(com.endeca.navigation.ERec pERec, com.endeca.navigation.DimValList pDimValList) Sets the navigation state for this UrlState using an ERec and a DimValList.
java.lang.String	setParam(java.lang.String pKey, java.lang.String pValue) Associates the specified value with the specified key in the underlying parameter map.
java.lang.String	toString() Returns an encoded string representation of this UrlState.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

UrlState

public UrlState(UrlFormatter pUrlFormatter,
                java.lang.String pEncoding)

Constructs an empty UrlState object.

Parameters:

pUrlFormatter - the UrlFormatter to associate with the UrlState

pEncoding - the character encoding that should be used when performing various string transformations. If not null, this value overrides the default encoding for the specified UrlFormatter.

See Also:

UrlFormatter.getDefaultEncoding()

Method Detail

getEncoding

public java.lang.String getEncoding()

Returns the character encoding that is used when marshaling parameters and strings contained within this UrlState.

Returns:

The character encoding that is used for parameter and string marshaling.

toString

public java.lang.String toString()

Returns an encoded string representation of this UrlState. This method utilizes UrlFormatter.formatUrl(UrlState) to construct the string.

Overrides:

toString in class java.lang.Object

Returns:

A string representation of this UrlState.

setParam

public java.lang.String setParam(java.lang.String pKey,
                                 java.lang.String pValue)

Associates the specified value with the specified key in the underlying parameter map. If the map previously contained a mapping for this key, the old value is replaced.

Parameters:

pKey - the parameter key

pValue - the parameter value

Returns:

The previous value for the specified key, or null if there was no previously associated parameter value.

Throws:

java.lang.IllegalArgumentException - if the specified key is null.

getParam

public java.lang.String getParam(java.lang.String pKey)

Returns the value associated with the specified key in the underlying parameter map. Returns null if there is no value for the specified key.

Parameters:

pKey - the parameter key

Returns:

The value associated with the specified key, or null if there is no associated parameter value.

Throws:

java.lang.IllegalArgumentException - if the specified key is null.

getUrlParam

public UrlParam getUrlParam(java.lang.String pKey)

Returns the full UrlParam value associated with the specified key in the underlying parameter map. Returns null if there is no value for the specified key.

Parameters:

pKey - the parameter key

Returns:

The UrlParam value associated with the specified key, or null if there is no associated parameter value.

Throws:

java.lang.IllegalArgumentException - if the specified key is null.

removeParam

public java.lang.String removeParam(java.lang.String pKey)

Removes any value associated with the specified key from the underlying parameter map.

Parameters:

pKey - the parameter key

Returns:

The previous value for the specified key, or null if there was no previously associated parameter value.

Throws:

java.lang.IllegalArgumentException - if the specified key is null.

getParameters

public java.util.Collection getParameters()

Returns a collection of all UrlParam mappings contained within this UrlState.

Returns:

A collection of UrlParam parameters.

inform

public void inform(com.endeca.navigation.ENEQueryResults pENEQueryResults)

Initializes this UrlState using state from the specified ENEQueryResults. This method is typically used to construct fully "informed" UrlState objects that can be used to create ancestor or refinemement links.

Parameters:

pENEQueryResults - the query results

containsERec

public boolean containsERec()

Returns true if this UrlState contains an ERec parameter.

Returns:

true if this UrlState contains an ERec parameter

See Also:

UrlFormatter.getERecParamKey()

setERec

public void setERec(com.endeca.navigation.ERec pERec)

Sets the associated ERec for this UrlState.

Parameters:

pERec - the ERec to associate with this UrlState; can be null to clear any previously associated ERec

getERec

public com.endeca.navigation.ERec getERec()

Returns the associated ERec for this UrlState.

Returns:

the ERec that is associated with this UrlState; or null if no ERec is associated with this UrlState.

containsAggrERec

public boolean containsAggrERec()

Returns true if this UrlState contains an AggrERec parameter.

Returns:

true if this UrlState contains an AggrERec parameter

See Also:

UrlFormatter.getAggrERecParamKey()

setAggrERec

public void setAggrERec(com.endeca.navigation.AggrERec pAggrERec)

Sets the associated AggrERec for this UrlState.

Parameters:

pAggrERec - the AggrERec to associate with this UrlState; can be null to clear any previously associated AggrERec

getAggrERec

public com.endeca.navigation.AggrERec getAggrERec()

Returns the associated AggrERec for this UrlState.

Returns:

the AggrERec that is associated with this UrlState; or null if no AggrERec is associated with this UrlState.

containsNavState

public boolean containsNavState()

Returns true if this UrlState contains a navigation state parameter.

Returns:

true if this UrlState contains a navigation state

See Also:

UrlFormatter.getNavStateParamKey()

setNavState

public void setNavState(com.endeca.navigation.DimLocationList pDimLocationList)

Sets the navigation state for this UrlState using a DimLocationList. This method is typically used to set navigation state from dimension search results.

Parameters:

pDimLocationList - the DimLocationList to associate with this UrlState.

See Also:

clearNavState(), removeNavState()

setNavState

public void setNavState(com.endeca.navigation.DimensionList pDescriptorDimensionList)

Sets the navigation state for this UrlState using a DimensionList. This method is typically used to set navigation state from Navigation.getDescriptorDimensions() from a current ENEQueryResults object.

Parameters:

pDescriptorDimensionList - the Dimension list to associate with this UrlState.

See Also:

clearNavState(), removeNavState()

setNavState

public void setNavState(com.endeca.navigation.ERec pERec,
                        com.endeca.navigation.DimValList pDimValList)

Sets the navigation state for this UrlState using an ERec and a DimValList. The ERec is used to reconstruct full a DimLocationList for the specified DimValList. If the record does not contain enough information to reconstruct a particular DimLocation, a degenerate DimLocation is created and added to the list instead. A degenerate DimLocation contains the DimVal and an empty ancestor list.

Parameters:

pERec - the source ERec used to reconstruct a full DimLocationList object.

pDimValList - the descriptor DimVal objects that represent the desired navigation state.

See Also:

clearNavState(), removeNavState()

getNavState

public com.endeca.navigation.DimLocationList getNavState()

Returns the navigation state for this UrlState or null if there is no navigation state.

Returns:

the navigation state or null.

Throws:

java.lang.IllegalStateException - if the navigation state wasn't explicitly or implicitly set on this UrlState.

See Also:

inform(ENEQueryResults), setNavState(DimLocationList), setNavState(DimensionList), setNavState(ERec,DimValList), clearNavState()

clearNavState

public void clearNavState()

Clears any existing navigation state from this UrlState. This method is the functional equivalent of setting "N=0".

This method will implicitly create an empty navigation state if one doesn't already exist on this UrlState.

removeNavState

public void removeNavState()

Fully removes any navigation state from this UrlState.

selectRefinement

public UrlState selectRefinement(com.endeca.navigation.Dimension pRefinementDimension,
                                 com.endeca.navigation.DimVal pRefinement,
                                 boolean pClone)

Selects a navigation refinement DimVal from the specified refinement Dimension. This method is typically used to select navigation refinements from Navigation.getRefinements().

This method is functionally similar to ENEQueryToolkit.selectRefinement(...).

This method will implicitly create an empty navigation state if one doesn't already exist on this UrlState. This is done before selecting the specified refinement.

Parameters:

pRefinementDimension - a Dimension object from Navigation.getRefinementDimensions().

pRefinement - a valid refinement DimVal from pRefinementDimension.getRefinements().

pClone - specifies whether this operation should modify a cloned instance of this UrlState.

Returns:

the UrlState object that was modified, i.e. a cloned UrlState if pClone is true or this if pClone is false.

Throws:

java.lang.IllegalStateException - if the navigation state wasn't explicitly or implicitly set on this UrlState.

See Also:

inform(ENEQueryResults), setNavState(DimLocationList), setNavState(DimensionList), setNavState(ERec,DimValList), clearNavState()

selectRefinement

public UrlState selectRefinement(com.endeca.navigation.DimLocation pRefinement,
                                 boolean pClone)

Selects a navigation refinement using a DimLocation object. This method is typically used to select navigation refinements from ERec.getDimValues().

This method is functionally similar to ENEQueryToolkit.selectRefinement(...).

This method will implicitly create an empty navigation state if one doesn't already exist on this UrlState. This is done before selecting the specified refinement.

Parameters:

pRefinement - the DimLocation to select

pClone - specifies whether this operation should modify a cloned instance of this UrlState.

Returns:

the UrlState object that was modified, i.e. a cloned UrlState if pClone is true or this if pClone is false.

Throws:

java.lang.IllegalStateException - if the navigation state wasn't explicitly set on this UrlState.

See Also:

inform(ENEQueryResults), setNavState(DimLocationList), setNavState(DimensionList), setNavState(ERec,DimValList), clearNavState()

selectAncestor

public UrlState selectAncestor(com.endeca.navigation.DimVal pAncestor,
                               com.endeca.navigation.DimVal pDescriptor,
                               boolean pClone)

Selects an ancestor DimVal for the specified descriptor DimVal.

This method is functionally similar to ENEQueryToolkit.selectAncestor(...).

This method will implicitly create an empty navigation state if one doesn't already exist on this UrlState.

Parameters:

pAncestor - the ancestor DimVal to select.

pDescriptor - the descriptor DimVal related to the specifed ancestor.

pClone - specifies whether this operation should modify a cloned instance of this UrlState.

Returns:

the UrlState object that was modified (i.e. a cloned UrlState if pClone is true or this if pClone is false.

Throws:

java.lang.IllegalStateException - if the navigation state wasn't explicitly set on this UrlState.

See Also:

inform(ENEQueryResults), setNavState(DimLocationList), setNavState(DimensionList), setNavState(ERec,DimValList)

removeDescriptor

public UrlState removeDescriptor(com.endeca.navigation.DimVal pDescriptor,
                                 boolean pClone)

Removes the specifed descriptor DimVal from the current navigation state.

This method is functionally similar to ENEQueryToolkit.removeDescriptor(...).

This method will implicitly create an empty navigation state if one doesn't already exist on this UrlState.

Parameters:

pDescriptor - the DimVal to remove

pClone - specifies whether this operation should modify a cloned instance of this UrlState.

Returns:

the UrlState object that was modified, i.e. a cloned UrlState if pClone is true or this if pClone is false.

Throws:

java.lang.IllegalStateException - if the navigation state wasn't explicitly set on this UrlState.

See Also:

inform(ENEQueryResults), setNavState(DimLocationList), setNavState(DimensionList), setNavState(ERec,DimValList)

clone

public java.lang.Object clone()

Returns a cloned instance of this UrlState object.

Overrides:

clone in class java.lang.Object

Returns:

the cloned instance.