Package com.documentum.fc.client

# Interface IDfQuery

public interface IDfQuery
This interface provides functionality for running queries against a repository.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `APPLY`
  Deprecated, Use DF_APPLY.
  `static final int`
  `CACHE_QUERY`
  Deprecated, Use DF_CACHE_QUERY.
  `static final int`
  `DF_APPLY`
  Represents the APPLY query type.
  `static final int`
  `DF_CACHE_QUERY`
  Represents the CACHE QUERY query type.
  `static final int`
  `DF_EXEC_QUERY`
  Represents the EXECUTE QUERY query type.
  `static final int`
  `DF_EXECREAD_QUERY`
  Represents the EXECUTE READ QUERY query type.
  `static final int`
  `DF_GETCONTENT`
  Used internally by DFC.
  `static final int`
  `DF_GETEVENTS`
  Used internally by DFC.
  `static final int`
  `DF_GETLASTCOLL`
  Used internally by DFC.
  `static final int`
  `DF_INTERNAL_READ_QUERY`
  Used internally by DFC.
  `static final int`
  `DF_QUERY`
  Represents the QUERY query type.
  `static final int`
  `DF_READ_QUERY`
  Represents the READQUERY query type.
  `static final int`
  `EXEC_QUERY`
  Deprecated, Use DF_EXEC_QUERY.
  `static final int`
  `EXECREAD_QUERY`
  Deprecated, Use DF_EXECREAD_QUERY.
  `static final int`
  `QUERY`
  Deprecated, Use DF_QUERY.
  `static final int`
  `READ_QUERY`
  Deprecated, Use DF_READ_QUERY.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `IDfCollection`
  `execute(IDfSession session, int queryType)`
  Executes a DQL query.
  `int`
  `getBatchSize()`
  Returns the maximum number of rows that can be returned to the server in each call to the underlying RDBMS.
  `String`
  `getCurrencyCheckValue()`
  Returns how often the query results will be checked for consistency with the server when persistent caching is selected in the query type of execute().
  `String`
  `getDQL()`
  Specifies the DQL statement assigned to a query.
  `void`
  `setBatchSize(int batchSize)`
  Assigns the maximum number of rows that can be returned to the server in each call to the underlying RDBMS.
  `void`
  `setCurrencyCheckValue(String currencyCheckValue)`
  Specifies how often the query results needs to checked for consistency with the server when persistent caching is selected in the query type of execute().
  `void`
  `setDQL(String dqlStatement)`
  Assigns a DQL statement to a query.
  `void`
  `setFlushBatchOnQuery(boolean flushBatch)`
  Specifies whether this query will cause the opening insert batch to flush.

- ## Field Details

  - ### DF_READ_QUERY

    static final int DF_READ_QUERY
    Represents the READQUERY query type.

    Use this query type for queries containing SELECT statements that will not make changes to a repository during processing. You can also execute non-SELECT statements with a READ QUERY query, but there are no performance benefits in doing so.

    Note that if a READ QUERY query makes changes to a repository during processing, the collection returned by the query closes automatically. When the collection is closed up to batch_hint_size objects will be modified but no error or exception will be raised. Consequently, if you want a query to make changes to a repository during processing, use a QUERY query. Refer to the Server Fundamentals for more information about query processing.

    See Also:
      - Constant Field Values

  - ### READ_QUERY

    static final int READ_QUERY
    Deprecated, Use DF_READ_QUERY.
    See Also:
      - Constant Field Values

  - ### DF_QUERY

    static final int DF_QUERY
    Represents the QUERY query type.

    Use this query type for queries containing any DQL statement. However, you must use this query type for queries containing SELECT statements that make changes to a repository during processing. Refer to the Server Fundamentals for more information about query processing.

    See Also:
      - Constant Field Values

  - ### QUERY

    static final int QUERY
    Deprecated, Use DF_QUERY.
    See Also:
      - Constant Field Values

  - ### DF_CACHE_QUERY

    static final int DF_CACHE_QUERY
    Represents the CACHE QUERY query type.

    This query type indicates that a query executes as read-only and stores the results in a query cache file. Use this query type when you are executing a query whose results are generally static. For example, you might use a CACHEQUERY query to return the names of users in a repository.

    Note that for queries without a SELECT statement, you should use the EXEC QUERY, READ QUERY, or QUERY query type. Refer to the Server Fundamentals for more information about query processing.

    See Also:
      - Constant Field Values

  - ### CACHE_QUERY

    static final int CACHE_QUERY
    Deprecated, Use DF_CACHE_QUERY.
    See Also:
      - Constant Field Values

  - ### DF_EXEC_QUERY

    static final int DF_EXEC_QUERY
    Represents the EXECUTE QUERY query type.

    This is same as DF_QUERY. Refer to the Server Fundamentals for more information about query processing.

    See Also:
      - Constant Field Values

  - ### EXEC_QUERY

    static final int EXEC_QUERY
    Deprecated, Use DF_EXEC_QUERY.
    See Also:
      - Constant Field Values

  - ### DF_EXECREAD_QUERY

    static final int DF_EXECREAD_QUERY
    Represents the EXECUTE READ QUERY query type.

    This is same as DF_READ_QUERY. Refer to the Server Fundamentals for more information about query processing.

    See Also:
      - Constant Field Values

  - ### EXECREAD_QUERY

    static final int EXECREAD_QUERY
    Deprecated, Use DF_EXECREAD_QUERY.
    See Also:
      - Constant Field Values

  - ### DF_APPLY

    static final int DF_APPLY
    Represents the APPLY query type.

    Use this query type for queries that invoke procedures that perform system administration functions or run external procedures.

    See Also:
      - Constant Field Values

  - ### APPLY

    static final int APPLY
    Deprecated, Use DF_APPLY.
    See Also:
      - Constant Field Values

  - ### DF_GETEVENTS

    static final int DF_GETEVENTS
    Used internally by DFC.
    See Also:
      - Constant Field Values

  - ### DF_GETLASTCOLL

    static final int DF_GETLASTCOLL
    Used internally by DFC.
    See Also:
      - Constant Field Values

  - ### DF_GETCONTENT

    static final int DF_GETCONTENT
    Used internally by DFC.
    See Also:
      - Constant Field Values

  - ### DF_INTERNAL_READ_QUERY

    static final int DF_INTERNAL_READ_QUERY
    Used internally by DFC.
    See Also:
      - Constant Field Values

- ## Method Details

  - ### execute

    IDfCollection execute(IDfSession session, int queryType) throws DfException
    Executes a DQL query.

    Before calling this method, assign a DQL statement to the query with the `setDQL` method. Refer to the Server DQL Reference Manual for more information about DQL statements.

    The following code example demonstrates how to obtain an IDfQuery interface, set a DQL query to the object, execute the query, then spin through the result set:

    >      IDfQuery q = new DfQuery();
    >      q.setDQL("select * from dm_cabinet");
    >      IDfCollection col = q.execute(sess, DfQuery.DF_READ_QUERY);
    >      while (col.next())
    >      {
    >           // Spin through the attributes...
    >           for (int i = 0; i < col.getAttrCount(); i++)
    >           {
    >               IDfAttr attr = col.getAttr(i);
    >               System.out.print("Attribute Name: " + attr.getName());
    >           }
    >      }
    >      col.close();

    Parameters:
      `session` - the current session
      `queryType` - the type of query that you want to execute; The following list specifies the integer corresponding to all query types:

           Integer           Query Type
           0                 READ QUERY
           1                 QUERY
           2                 CACHE QUERY
           3                 EXECUTE QUERY
           4                 EXECUTE READ QUERY
           5                 APPLY

    Returns:
      an IDfCollection interface to the query results.
    Throws:
      `DfException` - if the query fails to execute or if the specified session has timed out and cannot be re-established.
    See Also:
      - `setDQL(java.lang.String)`

  - ### setDQL

    void setDQL(String dqlStatement)
    Assigns a DQL statement to a query.

    Queries are written with the Document Query Language (DQL). Refer to the Server DQL Reference Manual for more information about DQL statements.

    Parameters:
      `dqlStatement` - the DQL statement

  - ### getDQL

    String getDQL()
    Specifies the DQL statement assigned to a query.

    Queries are written with DQL, Document Query Language. Refer to the Server DQL Reference Manual for more information about DQL statements.

    Returns:
      the query's DQL statement

  - ### setBatchSize

    void setBatchSize(int batchSize)
    Assigns the maximum number of rows that can be returned to the server in each call to the underlying RDBMS.

    Usage Notes Each query that you make to a repository effectively queries the underlying RDBMS. If you know that the information returned from the RDBMS for each row is relatively small, use `setBatchSize` to set a higher maximum number of rows returned for each call to the RDBMS. This will reduce the number of calls to the RDBMS needed to complete a query, which provides better query performance. This method allows you to optimize the performance of queries in remote client sessions. A remote client session is a DFC session in which the DFC and DMCL reside in separate processes. Refer to the Application Developer's Customization Guide for more information about remote and local client sessions.

    Parameters:
      `batchSize` - the maximum number of rows that can be returned to the server in each call to the underlying RDBMS;

  - ### getBatchSize

    int getBatchSize()
    Returns the maximum number of rows that can be returned to the server in each call to the underlying RDBMS.

    Usage Notes Each query that you make to a repository effectively queries the underlying RDBMS. If you know that the information returned from the RDBMS for each row is relatively small, use `setBatchSize` to set a higher maximum number of rows returned for each call to the RDBMS. This will reduce the number of calls to the RDBMS needed to complete a query, which provides better query performance. This method allows you to optimize the performance of queries in remote client sessions. A remote client session is a DFC session in which the DFC and DMCL reside in separate processes. Refer to the Application Developer's Customization Guide for more information about remote and local client sessions.

    Returns:
      the maximum number of rows that can be returned to the server in each call to the underlying RDBMS

  - ### getCurrencyCheckValue

    String getCurrencyCheckValue()
    Returns how often the query results will be checked for consistency with the server when persistent caching is selected in the query type of execute().
    Returns:
      If the value is numeric it indicates the time (in seconds) which the caller is willing to allow the query to be used without being rechecked for consistency. If the requested query is found in the cache and has not been checked for consistency in the specified time period then it is checked and re-issued from the server if necessary. If the value is non-numeric then it specifies a cache configuration object which defines the consistency check rules.

  - ### setCurrencyCheckValue

    void setCurrencyCheckValue(String currencyCheckValue)
    Specifies how often the query results needs to checked for consistency with the server when persistent caching is selected in the query type of execute().
    Parameters:
      `currencyCheckValue` - specifies that the query should be persistently cached and indicates how often the query needs to checked for consistency with the server. If the value is numeric it indicates the time (in seconds) which the caller is willing to allow the query to be used without being rechecked for consistency. If the requested query is found in the cache and has not been checked for consistency in the specified time period then it is checked and re-issued from the server if necessary. If the value is non-numeric then it specifies a cache configuration object which defines the consistency check rules. Specify `null` if you don't want the query persistently cached.

  - ### setFlushBatchOnQuery

    void setFlushBatchOnQuery(boolean flushBatch)
    Specifies whether this query will cause the opening insert batch to flush. Since the batch will cache the insert data, the batch has to flush the data so that the query can return the changes made in the batch. If not set, the query will use the flag set in IDfBatchManager. If the flag is true, server will flush the data whenever there is a query on the type/table that is in batch. If the caller knows that the query is not on data in the batch, setting the flag to false can avoid unnecessary batch flushes.

    Notes The batch is the insert batch, not the query batch.

    Parameters:
      `flushBatch` - boolean `true`, flush the batch when the query is on a batched table (default), `false`, do not flush the batch