NavigationState (Oracle Commerce Assembler Navigation 11.1.0 API)

```
public interface NavigationState
```
The NavigationState interface represents a request state that consists of a FilterState and a collection of URL parameters.
The interface provides methods for the following operations
- creating a new NavigationState with an updated FilterState from an existing NavigationState
- creating a new NavigationState with updated URL parameters from an existing NavigationState
- selecting a single record to obtain a RecordState
- informing the NavigationState with meta-data from the presentation API
Before selecting or removing a navigation filter and augmenting navigation state, it is important to call one of the inform methods with a Presentation API object.

Method Summary

Methods
Modifier and Type	Method and Description
`NavigationState`	`augment(FilterState filterState)` Note: This method modifies the `getUrlFilterState()` copy.
`NavigationState`	`clearFilterState()` Note: This method modifies the `getUrlFilterState()` copy.
`NavigationState`	`clearGeoFilter()` Note: This method modifies the `getUrlFilterState()` copy.
`NavigationState`	`clearNavigationFilters()` Note: This method modifies the `getUrlFilterState()` copy.
`NavigationState`	`clearParameters()` Create a new `NavigationState` relative to this one, clearing the parameters map.
`NavigationState`	`clearRangeFilters()` Note: This method modifies the `getUrlFilterState()` copy.
`NavigationState`	`clearRecordFilters()` Note: This method modifies the `getUrlFilterState()` copy.
`NavigationState`	`clearSearchFilters()` Note: This method modifies the `getUrlFilterState()` copy.
`String`	`getCanonicalLink()` Retrieves the canonical link relative to this `RecordState`.
`com.endeca.navigation.DimLocation`	`getDimLocation(String dvalId)` This method is for internal Oracle use only and should never be called. Returns the meta-information pertaining to the given dimension value ID.
`String`	`getEncoding()` Returns the character encoding that is used when marshaling parameters and strings contained within this UrlState.
`FilterState`	`getFilterState()` The FilterState object that is returned from this method is immutable, and never `null`.
`String`	`getParameter(String name)` Returns the value of the parameter with the given name, or `null`.
`FilterState`	`getUrlFilterState()` This method returns a URL `FilterState`.
`void`	`inform(com.endeca.navigation.DimLocation dimLocation)` This method is for internal Oracle use only and should never be called. Informs this class of important meta-information.
`void`	`inform(com.endeca.navigation.DimLocationList dimLocations)` This method is for internal Oracle use only and should never be called. Informs this class of important meta-information.
`void`	`inform(com.endeca.navigation.ENEQueryResults results)` This method is for internal Oracle use only and should never be called. Informs this class of important meta-information.
`NavigationState`	`putAllParameters(Map<String,String> parameters)` Create a new `NavigationState` relative to this one, updating all of the specified parameters.
`NavigationState`	`putParameter(String name, String value)` Create a new `NavigationState` relative to this one, updating the specified parameter.
`NavigationState`	`removeNavigationFilter(String dvalId)` Note: This method modifies the `getUrlFilterState()` copy.
`NavigationState`	`removeParameter(String name)` Create a new `NavigationState` relative to this one, removing the specified parameter.
`NavigationState`	`selectNavigationFilter(String dvalId)` Note: This method modifies the `getUrlFilterState()` copy.
`RecordState`	`selectRecord(String recordSpec, boolean isAggregateRecord)` Create a new `RecordState` from the given record spec.
`NavigationState`	`updateFilterState(FilterState filterState)` Note: This method modifies the `getUrlFilterState()` copy.
`NavigationState`	`updateGeoFilter(GeoFilter geoFilter)` Note: This method modifies the `getUrlFilterState()` copy.
`NavigationState`	`updateParameters(Map<String,String> parameters)` Create a new `NavigationState` relative to this one, replacing the entire existing parameter map with the given one.
`NavigationState`	`updateRangeFilters(List<RangeFilter> rangeFilters)` Note: This method modifies the `getUrlFilterState()` copy.
`NavigationState`	`updateRecordFilters(List<String> recordFilters)` Note: This method modifies the `getUrlFilterState()` copy.
`NavigationState`	`updateSearchFilters(List<SearchFilter> searchFilters)` Note: This method modifies the `getUrlFilterState()` copy.

- Method Detail
  - updateParameters
```
NavigationState updateParameters(Map<String,String> parameters)
```
    Create a new NavigationState relative to this one, replacing the entire existing parameter map with the given one.
    
    Parameters:
    parameters - the new parameter map
    
    Returns:
    the new NavigationState
  - removeParameter
```
NavigationState removeParameter(String name)
```
    Create a new NavigationState relative to this one, removing the specified parameter.
    
    Parameters:
    name - the name of the parameter to remove
    
    Returns:
    the new NavigationState
  - putParameter
```
NavigationState putParameter(String name,
                           String value)
```
    Create a new NavigationState relative to this one, updating the specified parameter.
    
    Parameters:
    name - the name of the parameter to update
    value - the value to update the parameter to
    
    Returns:
    the new NavigationState
  - putAllParameters
```
NavigationState putAllParameters(Map<String,String> parameters)
```
    Create a new NavigationState relative to this one, updating all of the specified parameters.
    This method is needed when adding more than one "remove always" parameter. Since such parameters have been configured to be removed whenever a new NavigationState is constructed from an existing one, they must be added all at once rather than one at a time. Otherwise, for example, the first would be removed when the second was added.
    
    Parameters:
    parameters - a map containing entries where the key corresponds to the name of the parameter to update and the value corresponds to the value to update it to
    
    Returns:
    the new NavigationState
  - clearParameters
```
NavigationState clearParameters()
```
    Create a new NavigationState relative to this one, clearing the parameters map.
    
    Returns:
    the new NavigationState
  - getFilterState
```
FilterState getFilterState()
```
    The FilterState object that is returned from this method is immutable, and never null.
    You should NOT make any updates to this FilterState instance. Even if you make any updates to this FilterState, when you access this method again, your changes will not be there.
    
    Returns:
    the FilterState object.
  - getUrlFilterState
```
FilterState getUrlFilterState()
```
    This method returns a URL FilterState. This FilterState is used to generate action links. Also this FilterState contains the filters that are passed in from the url.
    You should NOT make any updates to this filter state object directly. Instead of changing this FilterState, you should use the utility methods such as updateFilterState(FilterState), updateRecordFilters(List), clearGeoFilter()
    
    Returns:
    the FilterState object. This object is immutable, and never null.
  - updateFilterState
```
NavigationState updateFilterState(FilterState filterState)
```
    Note: This method modifies the getUrlFilterState() copy.
    Create a new NavigationState relative to this one, replacing the existing getUrlFilterState() object with the given one.
    
    Parameters:
    filterState - the new FilterState object
    
    Returns:
    the new NavigationState
  - clearFilterState
```
NavigationState clearFilterState()
```
    Note: This method modifies the getUrlFilterState() copy.
    Create a new NavigationState relative to this one, clearing the getUrlFilterState() object of the following:
  - FilterState.getSearchFilters() - clears to an empty list
  - FilterState.getNavigationFilters() - clears to an empty list
  - FilterState.getRangeFilters() - clears to an empty list
  - FilterState.getRecordFilters() - clears to an empty list
  - FilterState.getFeaturedRecords() - clears to an empty list
  - FilterState.getGeoFilter() - clears to null

Returns:: the new NavigationState

augment
```
NavigationState augment(FilterState filterState)
```
Note: This method modifies the getUrlFilterState() copy.
Create a new NavigationState relative to this one, augmented with the specified getFilterState().
The difference between the getFilterState() and filterState is added to the getUrlFilterState().
If the auxiliary filter state includes a dimensional refinement, then any refinements of the same dimension in this NavigationState are excluded from the result, except in the case of a multi-select dimension, in which case they are merged into the result.

Parameters:
filterState - A set of filter terms that supplement and/or replace those of this NavigationState

Returns:
the new NavigationState

selectNavigationFilter
```
NavigationState selectNavigationFilter(String dvalId)
```
Note: This method modifies the getUrlFilterState() copy.
Create a new NavigationState relative to this one, selecting the specified navigation filter from the getUrlFilterState(). Other navigation filters from the same dimension will be removed, except if the dimension is enabled for multi-select, in which case the siblings of the specified navigation filter will be retained.
This method can be used to select both refinements and ancestors.

Parameters:
dvalId - the navigation filter (i.e. dimension value ID)

Returns:
the new NavigationState

removeNavigationFilter
```
NavigationState removeNavigationFilter(String dvalId)
```
Note: This method modifies the getUrlFilterState() copy.
Create a new NavigationState relative to this one, removing the specified navigation filter from the getUrlFilterState(). Other navigation filters that are descendants of the specified navigation filter will be removed.
This method can be used to remove a single descriptor. It can also be used to remove all navigation filters from a single dimension by supplying the root navigation filter (i.e. dimension ID).

Parameters:
dvalId - - the navigation filter (i.e. dimension value ID)

Returns:
the new NavigationState

clearNavigationFilters
```
NavigationState clearNavigationFilters()
```
Note: This method modifies the getUrlFilterState() copy.
Create a new NavigationState relative to this one, clearing the navigation filters from the getUrlFilterState().

Returns:
the new NavigationState
See Also:
FilterState.getNavigationFilters()

clearSearchFilters
```
NavigationState clearSearchFilters()
```
Note: This method modifies the getUrlFilterState() copy.
Create a new NavigationState relative to this one, removing the searches from the getUrlFilterState().

Returns:
the new NavigationState
See Also:
FilterState.getSearchFilters()

clearRangeFilters
```
NavigationState clearRangeFilters()
```
Note: This method modifies the getUrlFilterState() copy.
Create a new NavigationState relative to this one, removing the range filters from the getUrlFilterState().

Returns:
the new NavigationState
See Also:
FilterState.getRangeFilters()

clearGeoFilter
```
NavigationState clearGeoFilter()
```
Note: This method modifies the getUrlFilterState() copy.
Create a new NavigationState relative to this one, removing the geo filter from the getUrlFilterState().

Returns:
the new NavigationState
See Also:
FilterState.getGeoFilter()

clearRecordFilters
```
NavigationState clearRecordFilters()
```
Note: This method modifies the getUrlFilterState() copy.
Create a new NavigationState relative to this one, removing the record filters from the getUrlFilterState().

Returns:
the new NavigationState
See Also:
FilterState.getRecordFilters()

updateSearchFilters
```
NavigationState updateSearchFilters(List<SearchFilter> searchFilters)
```
Note: This method modifies the getUrlFilterState() copy.
Create a new NavigationState relative to this one, with any existing search filters replaced by those in the given list.

Parameters:
searchFilters - the new searches

Returns:
the new NavigationState
See Also:
FilterState.getSearchFilters()

updateRangeFilters
```
NavigationState updateRangeFilters(List<RangeFilter> rangeFilters)
```
Note: This method modifies the getUrlFilterState() copy.
Create a new NavigationState relative to this one, with any existing range filters replaced by those in the given list.

Parameters:
rangeFilters - the new range filters

Returns:
the new NavigationState
See Also:
FilterState.getRangeFilters()

updateGeoFilter
```
NavigationState updateGeoFilter(GeoFilter geoFilter)
```
Note: This method modifies the getUrlFilterState() copy.
Create a new NavigationState relative to this one, with the existing GeoFilter (if any) replaced by the given one.

Parameters:
geoFilter - the new GeoFilter

Returns:
the new NavigationState
See Also:
FilterState.getGeoFilter()

updateRecordFilters
```
NavigationState updateRecordFilters(List<String> recordFilters)
```
Note: This method modifies the getUrlFilterState() copy.
Create a new NavigationState relative to this one, with any existing record filters replaced by those in the given list.

Parameters:
recordFilters - the new record filters

Returns:
the new NavigationState
See Also:
FilterState.getRecordFilters()

selectRecord
```
RecordState selectRecord(String recordSpec,
                       boolean isAggregateRecord)
```
Create a new RecordState from the given record spec.

Parameters:
recordSpec - the record spec
isAggregateRecord - whether the spec represents an aggregate record

Returns:
the new RecordState

inform
```
void inform(com.endeca.navigation.ENEQueryResults results)
```
This method is for internal Oracle use only and should never be called.

Informs this class of important meta-information.

Parameters:
results - a Presentation API ENEQueryResults object containing the meta-information

inform
```
void inform(com.endeca.navigation.DimLocation dimLocation)
```
This method is for internal Oracle use only and should never be called.

Informs this class of important meta-information.

Parameters:
dimLocation - a Presentation API DimLocation object containing the meta-information

inform
```
void inform(com.endeca.navigation.DimLocationList dimLocations)
```
This method is for internal Oracle use only and should never be called.

Informs this class of important meta-information.

Parameters:
dimLocations - a Presentation API DimLocationList object containing the meta-information

getDimLocation
```
com.endeca.navigation.DimLocation getDimLocation(String dvalId)
```
This method is for internal Oracle use only and should never be called.

Returns the meta-information pertaining to the given dimension value ID.

Parameters:
dvalId - The dimension value ID

Returns:
The meta-information for the given dimension value if the navigation state already contains it, null otherwise.

getCanonicalLink
```
String getCanonicalLink()
```
Retrieves the canonical link relative to this RecordState. This should make a best attempt in the implementation of returning a canonical representation of the state.

Returns:
A canonical link representation of the record state.

getParameter
```
String getParameter(String name)
```
Returns the value of the parameter with the given name, or null.

getEncoding
```
String getEncoding()
```
Returns the character encoding that is used when marshaling parameters and strings contained within this UrlState.

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

Interface NavigationState

Method Summary

Method Detail

updateParameters

removeParameter

putParameter

putAllParameters

clearParameters

getFilterState

getUrlFilterState

updateFilterState

clearFilterState

augment

selectNavigationFilter

removeNavigationFilter

clearNavigationFilters

clearSearchFilters

clearRangeFilters

clearGeoFilter

clearRecordFilters

updateSearchFilters

updateRangeFilters

updateGeoFilter

updateRecordFilters

selectRecord

inform

inform

inform

getDimLocation

getCanonicalLink

getParameter

getEncoding