NavigationState (Oracle Commerce Assembler 11.0.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)` Create a new `NavigationState` relative to this one, augmented with the specified `FilterState` object.
`NavigationState`	`clearFilterState()` Create a new `NavigationState` relative to this one, clearing the `FilterState` 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
`NavigationState`	`clearGeoFilter()` Create a new `NavigationState` relative to this one, removing the geo filter.
`NavigationState`	`clearNavigationFilters()` Create a new `NavigationState` relative to this one, clearing the navigation filters.
`NavigationState`	`clearParameters()` Create a new `NavigationState` relative to this one, clearing the parameters map.
`NavigationState`	`clearRangeFilters()` Create a new `NavigationState` relative to this one, removing the range filters.
`NavigationState`	`clearRecordFilters()` Create a new `NavigationState` relative to this one, removing the record filters.
`NavigationState`	`clearSearchFilters()` Create a new `NavigationState` relative to this one, removing the searches.
`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()`
`String`	`getParameter(String name)` Returns the value of the parameter with the given name, or `null`.
`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)` Create a new `NavigationState` relative to this one, removing the specified navigation filter.
`NavigationState`	`removeParameter(String name)` Create a new `NavigationState` relative to this one, removing the specified parameter.
`NavigationState`	`selectNavigationFilter(String dvalId)` Create a new `NavigationState` relative to this one, selecting the specified navigation filter.
`RecordState`	`selectRecord(String recordSpec, boolean isAggregateRecord)` Create a new `RecordState` from the given record spec.
`NavigationState`	`updateFilterState(FilterState filterState)` Create a new `NavigationState` relative to this one, replacing the existing `FilterState` object with the given one.
`NavigationState`	`updateGeoFilter(GeoFilter geoFilter)` Create a new `NavigationState` relative to this one, with the existing `GeoFilter` (if any) replaced by the given one.
`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)` Create a new `NavigationState` relative to this one, with any existing range filters replaced by those in the given list.
`NavigationState`	`updateRecordFilters(List<String> recordFilters)` Create a new `NavigationState` relative to this one, with any existing record filters replaced by those in the given list.
`NavigationState`	`updateSearchFilters(List<SearchFilter> searchFilters)` Create a new `NavigationState` relative to this one, with any existing search filters replaced by those in the given list.

- 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()
```
    Returns:
    the FilterState object. This object is immutable, and never null.
  - updateFilterState
```
NavigationState updateFilterState(FilterState filterState)
```
    Create a new NavigationState relative to this one, replacing the existing FilterState object with the given one.
    
    Parameters:
    filterState - the new FilterState object
    
    Returns:
    the new NavigationState
  - clearFilterState
```
NavigationState clearFilterState()
```
    Create a new NavigationState relative to this one, clearing the FilterState 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)
```
Create a new NavigationState relative to this one, augmented with the specified FilterState object.
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)
```
Create a new NavigationState relative to this one, selecting the specified navigation filter. 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)
```
Create a new NavigationState relative to this one, removing the specified navigation filter. 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()
```
Create a new NavigationState relative to this one, clearing the navigation filters.

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

clearSearchFilters
```
NavigationState clearSearchFilters()
```
Create a new NavigationState relative to this one, removing the searches.

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

clearRangeFilters
```
NavigationState clearRangeFilters()
```
Create a new NavigationState relative to this one, removing the range filters.

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

clearGeoFilter
```
NavigationState clearGeoFilter()
```
Create a new NavigationState relative to this one, removing the geo filter.

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

clearRecordFilters
```
NavigationState clearRecordFilters()
```
Create a new NavigationState relative to this one, removing the record filters.

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

updateSearchFilters
```
NavigationState updateSearchFilters(List<SearchFilter> searchFilters)
```
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)
```
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)
```
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)
```
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

updateFilterState

clearFilterState

augment

selectNavigationFilter

removeNavigationFilter

clearNavigationFilters

clearSearchFilters

clearRangeFilters

clearGeoFilter

clearRecordFilters

updateSearchFilters

updateRangeFilters

updateGeoFilter

updateRecordFilters

selectRecord

inform

inform

inform

getDimLocation

getCanonicalLink

getParameter

getEncoding