= search service =

Service performs searches for various information in ADEI and source databases. ADEI has a modular [wiki:adeiSEARCH SEARCH SubSystem]. The search capabilities are provided by the search engines which providing one-or-more search modules. The understanding of the subsystem is mandatory to use the service.

== Mandatory Properties ==
 * [wiki:adeiParam_search search] - A search string, could include the list of search modules along with parameters (check [wiki:adeiSEARCH/String format description])

== Optional Properties ==
 * [wiki:adeiParam_search_modules search_modules] - A list of search modules to perform search along with parameters. If modules are specified in the ''search'' property as well, the modules which are specified in ''search'' will take precedence. If the search modules are neither specified in the ''search_modules'' nor in the ''search'' string, the search string would be analyzed. Analysis routine is guessing the type of search and executes a default set of modules for this type.

== Additional Properties ==
All standard data source / time interval properties can be taken into the account by search modules. For example, they can sort the found result putting the results from currently selected data source first. The searching only within the currently selected group is another possible example.
 * [wiki:adeiParam_db_server db_server ] - Data source / system
 * [wiki:adeiParam_db_name db_name ] - Database name
 * [wiki:adeiParam_db_group db_group ] - Log Group
 * [wiki:adeiParam_control_group control_group ] - Control Group
 * [wiki:adeiParam_experiment experiment ] - The current experiment/run duration
 * [wiki:adeiParam_window window] - Data Interval (everything by default)
 ...

== Returned Result ==
The XML document with results found by all used modules. If certain module have produced no results it is not included in the output. The following format is used:
{{{
<result>
  <module name="item" title="Items">
     ... module results, see the description below ...
  </module>
  <module name="groups" title="Log Groups">
     ... module results, see the description below ...
  </module>
  ...
</result>
}}}
The empty result is returned if nothing is found:
{{{
<result/>
}}}
In the case of error, the error message in the following format is returned:
{{{
<result>
 <Error>Unknown control_group (0) is specified</Error>
</result>
}}}

The module results are returned by modules in two different forms: standard and custom.

== Standard/XML Results ==
The most modules are returning the results in the XML format. Each result is returned in ''Value'' XML node and all ''Value'' nodes are enclosed in the ''result'' node. The ''Value'' node includes several attributes:
 * ''title'' - describing the result
 * ''props'' - URL encoded string with parameters to adjust in the ADEI system, if this result is selected
 * ''certain'' - This optional property is indicating what the ADEI is certain about this result

The response to following search request:
{{{
 http://adei_server.net/adei/services/search.php?search_module=item&search=temperature
}}}
returns all items which names are started with "temperature":
{{{
<result>
  <module name="item" title="Items">
     <results>
        <Value  title="412-RTP-5-0011" props="db_server=katrin&amp;db_name=detector&amp;db_group=0&amp;db_mask=72"/>
        <Value  title="412-RTP-5-0012" props="db_server=katrin&amp;db_name=detector&amp;db_group=0&amp;db_mask=75/">
        ...
     </result>
  </module>
</result>
}}}
The '''props''' property in this case defines ''db_server'', ''db_name'', ''db_group'', and ''db_mask'' properties which are fully describing the result. If these properties are passed to the ADEI system, the found item will be displayed.

Another example uses the ''interval'' search module to find the UNIX timestamps of the entered textual date
{{{
http://adei_server.net/adei/services/search.php?search=January 2005
}}}
The '''props''' in this case contains ''window'' property which should be passed to ADEI system to limit the data to a single month in the year 2005.
{{{
<result>
  <module name="interval" title="Dates">
     <results>
        <Value  title="Jan 1, 2009 00:00:00 - Feb 1, 2009 00:00:00" props="window=1230768000-1233446400" certain="1"/>
     </result>
  </module>
</result>
}}}


== Custom/XHTML Results ==
Some search engines may provide non-standard set of results which can't be represented using default XML scheme. In this case the arbitrary XHTML content is returned within the ''Content'' tag inside a module results.
Example:
<result>
  <module name="proxy">
     <Content> 
         ... arbitrary XHTML content is here ...
     </Content>
  </module>
</result>

The best example here is ''proxy'' search module which downloads XML document from the specified location and applying XSLT stylesheet to convert it into the XHTML. For example, the following request:
{{{
ipepdvadei.ka.fzk.de/adei/services/search.php?search={proxy(xml=katrin.php?target=runs;xslt=katrinsearch;noprops)}%20interval:1218431322-1253472677
}}}
obtains the data from ''katrin.php'' service, applies the ''katrinsearch'' stylesheet to it and returns the resulting HTML. 

The parameters of proxy module specifies:
 * ''xml'' - the service to obtain XML document from
 * ''xslt'' - the stylesheet to apply to XML, could be omitted if the service returns XHTML directly
 * ''noprops'' - instructs ADEI to not add current properties when calling the service, otherwise the passsed ''db_server'', ''db_name'', and other properties would be added in the end of service request.

The two properties are passed to the ''katrin.php'' service:
 * ''target'' - it is specified directly within proxy module options (target=runs)
 * ''window'' - it is specified in search limits at the end of search string (interval:1218431322-1253472677)

The example of HTML returned:
{{{
<result>
  <module name="proxy">
     <Content> 
        <div>
          <h4>Found runs:</h4>
           <p>
             <a href="javascript:katrin.SetCustomProperties('run=kps00000464')">Run kps00000464</a><br/>
             2008-09-10 11:49:50 - 2008-09-10 11:52:52<br/>
             <a href="javascript:katrin.SetCustomProperties('run=kps00000464.00001')">Subrun kps00000464.00001</a><br/>
             ...
     </Content>
  </module>
</result>
}}}