Package com.documentum.xml.xquery

# Interface IDfXQuery

public interface IDfXQuery
This interface provides functionality for running XQueries against a repository, returning the results as a XML DOM or byte stream.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static enum`
  `IDfXQuery.FtQueryDebugOptions`
  `static enum`
  `IDfXQuery.FtQueryOptions`
  These options are used when executing the xquery against a target of IDfXQueryTargets.DF_FULLTEXT.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addStore(String store_name)`
  Specifies a storage area to query against.
  `void`
  `close(IDfSession session)`
  Closes the XQuery results stream.
  `void`
  `execute(IDfSession session)`
  Executes the XQuery.
  `void`
  `execute(IDfSession session, com.documentum.xml.xquery.IDfXQueryTargets target)`
  Executes the XQuery on targets passed in as the parameter.
  `String`
  `getCutoffMessage()`
  Retrieve the cutoff messages from ESS after the query is executed.
  `String`
  `getDebugInfo(IDfSession session, IDfXQuery.FtQueryDebugOptions debugOption)`
  Retrieve debugging information associated with this query
  `String`
  `getExecutionPlan(IDfSession session)`
  Retrieve the xquery execution plan from ESS after the query is executed.
  `InputStream`
  `getInputStream(IDfSession session)`
  Return an InputStream object that applications can use it to retrieve the xquery results.
  `String`
  `getOption(IDfXQuery.FtQueryOptions option)`
  To get the value of the option that was set.
  `void`
  `getXMLFile(String filename)`
  Writes the XQuery results to a file.
  `void`
  `getXMLOutputStream(OutputStream outputStream)`
  Writes the XQuery results to an OutputStream object.
  `String`
  `getXMLString()`
  Returns the XQuery results as a Java String object.
  `int`
  `readResults(byte[] buffer)`
  Fills the given buffer with the next set of XQuery results.
  `int`
  `readResults(byte[] buffer, IDfSession session)`
  Fills the given buffer with the next set of XQuery results.
  `void`
  `setBooleanOption(IDfXQuery.FtQueryOptions option, boolean value)`
  Set an FtQueryOption to apply to the xquery.
  `void`
  `setIntegerOption(IDfXQuery.FtQueryOptions option, int value)`
  Set an FtQueryOption to apply to the xquery.
  `void`
  `setMapOption(IDfXQuery.FtQueryOptions option, Map<String,String> value)`
  Set an FtQueryOption to apply to the xquery.
  `void`
  `setStringOption(IDfXQuery.FtQueryOptions option, String value)`
  Set an FtQueryOption to apply to the xquery.
  `void`
  `setXQueryString(String xqueryString)`
  Assigns a XQuery statement to a query.

- ## Method Details

  - ### setXQueryString

    void setXQueryString(String xqueryString)
    Assigns a XQuery statement to a query.

    Queries are written with the XQuery Language. This API must be called before executing the query.

    Parameters:
      `xqueryString` - the XQuery statement

  - ### addStore

    void addStore(String store_name)
    Specifies a storage area to query against.

    Used for xqueries directed toward xml store only. This method can be called multiple times to query against multiple storage areas. If no storage areas are specified, the query is executed against all XML storage areas. Call this method before executing the query.

    Parameters:
      `store_name` - the name of the storage area

  - ### execute

    void execute(IDfSession session) throws DfException
    Executes the XQuery.

    Parameters:
      `session` - DFC session identifier that has to be established (connected) before "execute" is called.
    Throws:
      `DfException` - exception

  - ### execute

    void execute(IDfSession session, com.documentum.xml.xquery.IDfXQueryTargets target) throws DfException
    Executes the XQuery on targets passed in as the parameter.
    Parameters:
      `session` - DFC session identifier that has to be established (connected)
      `target` - DfStoreXQueryTargets or DfFullTextXQueryTargets
    Throws:
      `DfException` - exception

  - ### readResults

    int readResults(byte[] buffer) throws DfException
    Fills the given buffer with the next set of XQuery results. This method may be called repeatedly until results are exhausted.
    Parameters:
      `buffer` - The buffer in which XQuery results are written to
    Returns:
      the amount of bytes read into the buffer (-1 indicates end of results)
    Throws:
      `DfException` - exception

  - ### readResults

    int readResults(byte[] buffer, IDfSession session) throws DfException
    Fills the given buffer with the next set of XQuery results. This method may be called repeatedly until results are exhausted.
    Parameters:
      `buffer` - The buffer in which XQuery results are written to
      `session` - The DFC session identifier that has to be established (connected).
    Returns:
      the amount of bytes read into the buffer (-1 indicates end of results)
    Throws:
      `DfException` - exception

  - ### close

    void close(IDfSession session) throws DfException
    Closes the XQuery results stream. Only use this method after calling readResults.
    Parameters:
      `session` - DFC session identifier that has to be established (connected)
    Throws:
      `DfException` - exception

  - ### getXMLFile

    void getXMLFile(String filename) throws DfException
    Writes the XQuery results to a file.

    Parameters:
      `filename` - The path to the file where the results are written
    Throws:
      `DfException` - exception

  - ### getXMLOutputStream

    void getXMLOutputStream(OutputStream outputStream) throws DfException
    Writes the XQuery results to an OutputStream object.

    The method will flush the outputstream after the results are written. The outputstream is not closed by this method.

    Parameters:
      `outputStream` - The output stream in which the results are written
    Throws:
      `DfException` - exception

  - ### getXMLString

    String getXMLString() throws DfException
    Returns the XQuery results as a Java String object.

    Returns:
      The result in a Java String
    Throws:
      `DfException` - exception

  - ### setBooleanOption

    void setBooleanOption(IDfXQuery.FtQueryOptions option, boolean value) throws DfException
    Set an FtQueryOption to apply to the xquery. These options are only considered when executing the xquery against a target of IDfXQueryTargets.DF_FULLTEXT.

    Parameters:
      `option` - FtQueryOptions option
      `value` - true/false
    Throws:
      `DfException` - exception

  - ### setIntegerOption

    void setIntegerOption(IDfXQuery.FtQueryOptions option, int value) throws DfException
    Set an FtQueryOption to apply to the xquery. These options are only considered when executing the xquery against a target of IDfXQueryTargets.DF_FULLTEXT.

    Parameters:
      `option` - FtQueryOptions option
      `value` - integer value
    Throws:
      `DfException` - exception

  - ### setMapOption

    void setMapOption(IDfXQuery.FtQueryOptions option, Map<String,String> value) throws DfException
    Set an FtQueryOption to apply to the xquery. These options are only considered when executing the xquery against a target of IDfXQueryTargets.DF_FULLTEXT.

    Parameters:
      `option` - FtQueryOptions option
      `value` - Map value
    Throws:
      `DfException` - exception

  - ### setStringOption

    void setStringOption(IDfXQuery.FtQueryOptions option, String value) throws DfException
    Set an FtQueryOption to apply to the xquery. These options are only considered when executing the xquery against a target of IDfXQueryTargets.DF_FULLTEXT.

    Parameters:
      `option` - FtQueryOptions option
      `value` - String value
    Throws:
      `DfException` - exception

  - ### getOption

    String getOption(IDfXQuery.FtQueryOptions option) throws DfException
    To get the value of the option that was set. For non-string options, returns the string equivalent value. Returns null if the option was not set.

    Parameters:
      `option` - FtQueryOptions option
    Returns:
      The value that was set by setOption API or null if not set
    Throws:
      `DfException` - exception

  - ### getExecutionPlan

    String getExecutionPlan(IDfSession session) throws DfException
    Retrieve the xquery execution plan from ESS after the query is executed. If the SAVE_EXECUTION_PLAN option is not set to true, an exception is thrown.
    Parameters:
      `session` - - DFC session identifier that has to be established (connected).
    Returns:
      String - the actual execution plan
    Throws:
      `DfException` - exception

  - ### getCutoffMessage

    String getCutoffMessage() throws DfException
    Retrieve the cutoff messages from ESS after the query is executed.
    Returns:
      String - the cutoff messages
    Throws:
      `DfException` - exception

  - ### getDebugInfo

    String getDebugInfo(IDfSession session, IDfXQuery.FtQueryDebugOptions debugOption) throws DfException
    Retrieve debugging information associated with this query
    Parameters:
      `session` - - DFC session identifier that has to be established (connected).
      `debugOption` - - FtQueryDebugOptions option
    Returns:
      String - the value of the debugOption or null if not available
    Throws:
      `DfException` - exception

  - ### getInputStream

    InputStream getInputStream(IDfSession session)
    Return an InputStream object that applications can use it to retrieve the xquery results.
    Parameters:
      `session` - - DFC session identifier that has to be established (connected).
    Returns:
      InputStream object.