package gw.solr.mapper

uses gw.xsd.config.solr_search_config.DataProperty

uses java.util.Collection


/**
 * This interface is used to access the individual criteria for a Solr query
 */
@ReadOnly
interface IDataHolder {

  /**
   * Finds the value in this dataholder for the field described by the specified
   * DataProperty.
   * 
   * @param dp the DataProperty for the field being requested
   * @param T the type of data being requested.  If type is not specified,
   *   Object will be used.
   * @return The data for this DataProperty or null if not present or the
   *   wrong type.
   */
  reified function lookup<T>( dp : DataProperty ) : T
  
  /**
   * Finds the value in this dataholder for the field described by the specified
   * DataProperty or the default value in case the expected data is not present.
   * Null is returned if the data is not the expected type.
   * 
   * @param dp the DataProperty for the field being requested
   * @param defaultValue the value to return if this value is not found or
   *   of the wrong type.
   * @param T the type of data being requested.  If type is not specified,
   *   Object will be used.
   * @return The data for this DataProperty or the default value if not found.
   *   Null is returned if the data is not the expected type.
   */
  reified function lookup<T>( dp : DataProperty, defaultValue : T ) : T

  /**
   * Creates a key from the specified DataProperty in a format suitable
   * for use in a URN.  In general, paths are assembed into a single token
   * with a lower case first letter and same case as path for the remainder.
   * Name-Property pairs are similarly combined except any dotted prefix
   * of the name will be stripped in case name is a qualified type name.
   * <br/><br/>
   * For example, both 
   * <br/><br/>
   *   &lt;DataProperty path="/Contact/PublicID"/&gt; and
   *   &lt;DataProperty name="entity.Contact" property="PublicID"/&gt;
   * <br/><br/>
   * will be converted to the key "contactPublicID".
   * 
   * @param dp the DataProperty for the field being requested
   * @return the key that describes this field
   */
  function lookupKey( dp : DataProperty ) : String

  /**
   * Checks to see if the data referred to by this DataProperty is present
   * in the graph and if it or any parent is new or changed.
   * <br/><br/>
   * Only applies to data elements that are keyable entity beans.
   * 
   * @param dp the DataProperty for the field being requested
   * @return true if this data element or any of its parents are New or in
   *   the ChangeField list of the respective parent bean.
   */
  function isChanged( dp : DataProperty ) : boolean
  
  /**
   * Adds bean passed in to the reference list if references are being collected.
   * <br/><br/>
   * Use this method to add a reference to an entity bean involved in the generation
   * of Solr index data, but which cannot be inferred by the system.  The
   * bean id and version information, if available, will be checked when the
   * message is sent to be sure the message does not contain outdated information.
   * 
   * @param bean the bean being referenced
   */
  function addReference( bean : KeyableBean )
  
  /**
   * Adds beans passed in to the reference list if references are being collected.
   * <br/><br/>
   * Use this method to add references for a collection of entity beans involved
   * in the generation of Solr index data, but which cannot be inferred by the
   * system.  The bean ids and version information, if available, will be checked
   * when the message is sent to be sure the message does not contain outdated information.
   * 
   * @param bean the bean being referenced
   */
  function addReferences( beans : Collection<KeyableBean> )
  
}