State elements

Every request must contain at least one state, each one defining a navigation state for associated ContentElementConfigs.

The format of the State type is:

<State>
   <Name>?</Name>
   <CollectionName>?</CollectionName>
   <SelectedRefinementFilter Name="?" Spec="?" Id="?">
      <Source FilterId="?">
         <StateName>?</StateName>
      </Source>
   </SelectedRefinementFilter>
   <TextSearchFilter Key="?" RelevanceRankingStrategy="?" Mode="?" 
      EnableSnippeting="?" SnippetLength="?" Language="?">?</TextSearchFilter>
   <RecordKind>?</RecordKind>
   <DataSourceFilter Id="?">
      <filterAST>
         <typ:filter/>
      </filterAST>
      <filterString>?</filterString>
      <Source FilterId="?">
         <StateName>?</StateName>
      </Source>
   </DataSourceFilter>
   <SelectionFilter Id="?">
      <filterAST>
         <typ:filter/>
      </filterAST>
      <filterString>?</filterString>
      <Source FilterId="?">
         <StateName>?</StateName>
      </Source>
   </SelectionFilter>
</State>

The meanings of the major elements are:

Element	Min/Max Occurrences	Description
Name	min=0 max=1	The name of a State. In a request with multiple states, each state must use the Name element and each name must be distinct from other state names in that request. In a request with only one state, it is optional for the state to be named.
CollectionName	min=0 max=1	The name of an existing collection to operate on. Note that collection names are case sensitive.
SelectedRefinementFilter	min=0 max=unbounded	Creates a refinement navigation query from a specific refinement. For details, see SelectedRefinementFilter.
TextSearchFilter	min=0 max=unbounded	Performs a keyword search against specific attribute values assigned to records. For details on its format, see Record search filter.
DataSourceFilter	min=0 max=unbounded	Uses EQL syntax to filter the corpus of records before any other processing is done. For details, see EQL Record Filters.
SelectionFilter	min=0 max=unbounded	Uses EQL syntax to provide selection criteria for the final record result set. Typically used in conjunction with DataSourceFilter. For details, see EQL Record Filters.

Rules for State usage

The rules for states in a request are:

A state in a request is defined by the State type.
Every request must have at least one state (i.e., one State type).
A request can have more than one state. If multiple states are included, each state must have a unique name.
If only one state is in the request, the state can be unnamed (i.e., the Name element is not used in the State definition). If the state is unnamed, then there can be one (and only one) state in the request.
If the request contains only one unnamed state, the state can be empty (that is, <State/>). By definition, an empty state is an unnamed state.
A state can have multiple filters that use the Id element to provide an identifier (such as SelectionFilter Id="SalesSearch"). In this case, each filter identifier must be unique within the state. If they are not unique, Endeca Server throws an exception.

In addition, if a request has multiple states, then each config must reference one (and only one) state. If the request has only one named state, then it is optional as to whether the config references that state (as the state will be used in any event in the config).

Example of a multi-state request

This simple example shows a request with two named states (FlavorSearch and WineSearch), each of which is performing a record search on a different attribute. The results are summarized by two RecordCountConfig types, each of which uses the StateName element to associate it with one of the named states:

<Request xmlns="http://www.endeca.com/MDEX/conversation/3/0">
   <State>
      <Name>FlavorSearch</Name>
      <TextSearchFilter Key="Flavors" Mode="AllPartial" Language="en">oak</TextSearchFilter>
   </State>
   <State> 
      <Name>WineSearch</Name>
      <TextSearchFilter Key="Wine" Mode="AllPartial" Language="en">merlot</TextSearchFilter>
   </State>
   <RecordCountConfig Id="FlavorRecs"> 
     <StateName>FlavorSearch</StateName>StateName>          
   </RecordCountConfig>
   <RecordCountConfig Id="WineRecs"> 
     <StateName>WineSearch</StateName>StateName>          
   </RecordCountConfig>
</Request>

The results of the search look like this example:

<cs:Results xmlns:cs="http://www.endeca.com/MDEX/conversation/3/0" 
         xmlns:mdex="http://www.endeca.com/MDEX/XQuery/2009/09">
   <State xmlns="http://www.endeca.com/MDEX/conversation/3/0" 
         xmlns:ns2="http://www.endeca.com/MDEX/eql_parser/types" 
         xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
      <Name>FlavorSearch</Name>
      <TextSearchFilter Key="Flavors" Mode="AllPartial" Language="en">oak</TextSearchFilter>
   </State>
   <State xmlns="http://www.endeca.com/MDEX/conversation/3/0" 
         xmlns:ns2="http://www.endeca.com/MDEX/eql_parser/types" 
         xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
      <Name>WineSearch</Name>
      <TextSearchFilter Key="Wine" Mode="AllPartial" Language="en">merlot</TextSearchFilter>
   </State>
   <cs:RecordCount Id="FlavorRecs">
      <cs:NumRecords>6381</cs:NumRecords>
   </cs:RecordCount>
   <cs:RecordCount Id="WineRecs">
      <cs:NumRecords>3073</cs:NumRecords>
   </cs:RecordCount>
</cs:Results>

As the results show, the record search from the FlavorSearch state returns 6381 records, while the record search from the WineSearch state returns 3073 records.