Package com.documentum.fc.client

# Interface IDfCollection

All Superinterfaces:
  `IDfTypedObject`

All Known Subinterfaces:
  `IDfContentCollection`

public interface IDfCollection extends IDfTypedObject
This interface provides access to collection objects.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `DF_CLOSED_STATE`
  Indicates a collection is closed.
  `static final int`
  `DF_INITIAL_STATE`
  Indicates a new collection waiting for the first next() call.
  `static final int`
  `DF_NO_MORE_ROWS_STATE`
  Indicates the collection has no more rows.
  `static final int`
  `DF_READY_STATE`
  Indicates a collection is positioned on a row ready for reading.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `close()`
  Closes a collection object.
  `ByteArrayInputStream`
  `getBytesBuffer(String cmd, String buf, String buflen, int length)`
  Reserved for internal use.
  `int`
  `getState()`
  Returns the state of a collection object.
  `int`
  `getStateEx()`
  Returns the state of a collection object.
  `IDfTypedObject`
  `getTypedObject()`
  Returns a row in the collection as an `IDfTypedObject` for later use.
  `boolean`
  `next()`
  Gets the next row in a collection.

  ### Methods inherited from interface com.documentum.fc.client.IDfTypedObject

  `appendBoolean, appendDouble, appendId, appendInt, appendString, appendTime, appendValue, dump, enumAttrs, findAttrIndex, findBoolean, findDouble, findId, findInt, findString, findTime, findValue, getAllRepeatingStrings, getAttr, getAttrCount, getAttrDataType, getBoolean, getDouble, getId, getInt, getLong, getObjectId, getObjectSession, getOriginalSession, getRepeatingBoolean, getRepeatingDouble, getRepeatingId, getRepeatingInt, getRepeatingLong, getRepeatingString, getRepeatingTime, getRepeatingValue, getSession, getSessionManager, getString, getTime, getValue, getValueAt, getValueCount, hasAttr, insertBoolean, insertDouble, insertId, insertInt, insertString, insertTime, insertValue, isAttrRepeating, isNull, remove, removeAll, setBoolean, setDouble, setId, setInt, setNull, setRepeatingBoolean, setRepeatingDouble, setRepeatingId, setRepeatingInt, setRepeatingString, setRepeatingTime, setRepeatingValue, setSessionManager, setString, setTime, setValue, truncate`

- ## Field Details

  - ### DF_INITIAL_STATE

    static final int DF_INITIAL_STATE
    Indicates a new collection waiting for the first next() call.
    See Also:
      - Constant Field Values

  - ### DF_READY_STATE

    static final int DF_READY_STATE
    Indicates a collection is positioned on a row ready for reading.
    See Also:
      - Constant Field Values

  - ### DF_CLOSED_STATE

    static final int DF_CLOSED_STATE
    Indicates a collection is closed.
    See Also:
      - Constant Field Values

  - ### DF_NO_MORE_ROWS_STATE

    static final int DF_NO_MORE_ROWS_STATE
    Indicates the collection has no more rows.
    See Also:
      - Constant Field Values

- ## Method Details

  - ### next

    boolean next() throws DfException
    Gets the next row in a collection.

    This method is usually used to retrieve query results that are returned in a collection object. You must execute the `next` method once for each row that you want to retrieve in a collection object.

    Refer to the DocumentumTM Server Fundamentals for more information about processing queries.

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

    >      IDfCollection col = null;
    >      IDfQuery q = null;
    >      IDfId idObj = null;
    >      String strVal = "";
    >      int intVal = 0;
    >      try
    >      {
    >           q = new DfQuery();
    >           q.setDQL("select object_name, i_contents_id, r_page_cnt from dm_document
    >                where object_name like 'My Name%");
    >           col = q.execute(sess, IDfQuery.READ_QUERY);
    >           while (col.next())
    >           {
    >               strVal = col.getString("object_name");
    >               idObj = col.getId("i_contents_id");
    >               intVal = col.getInt("r_page_cnt");
    >               // Process info...
    >           }
    >      }
    >      catch(DfException ex)
    >      {
    >           // Error handling routine...
    >      }

    Returns:
      `true` if there is another row in the collection; `false` if there are no more rows in the collection.
    Throws:
      `DfException` - if a server error occurs.

  - ### getTypedObject

    IDfTypedObject getTypedObject() throws DfException
    Returns a row in the collection as an `IDfTypedObject` for later use.

    Once you make a `next` call, the collection is advanced to the next row of data and there is no mechanism for going back to a previous row. If you need to retain a row for later use, call this method.

    The following code example demonstrates how to obtain an IDfQuery interface, set a DQL query to the object, execute the query, then save each row in a vector as an IDfTypedObject interface:

    >      DfQuery q = new DfQuery();
    >      q.setDQL("select r_object_id, object_name, r_modify_date from dm_document
    >                where object_name like 'My Name%");
    >      // Assume that m_myRows is declared as a member variable of type vector
    >      m_myRows = new Vector();
    >      try
    >      {
    >           IDfCollection col = q.execute(session, IDfQuery.READ_QUERY);
    >           while(col.next())
    >           {
    >               m_myRows.addElement(col.getTypedObject());
    >           }
    >      }
    >      catch(DfException dfc)
    >      {
    >           // Error handling code
    >      }
    >      ...
    >      // Elsewhere in your code
    >      try
    >      {
    >           int cnt = n_myRows.size();
    >           for (inti=0; i < cnt; i++)
    >           {
    >               IDfTypedObject row = (IDfTypedObject) m_myRows.elementAt(i);
    >               IDfId id = row.getId("r_object_id");
    >               String name = row.getString("object_name");
    >               IDfTime time = row.getTime("r_modify_date");
    >               // Etc., etc...
    >           }
    >      }
    >      catch(DfException dfc);
    >      {
    >           // Error handling code
    >      }

    Returns:
      an IDfTypedObject interface to the row in the collection.
    Throws:
      `DfException` - if a server error occurs.

  - ### close

    void close() throws DfException
    Closes a collection object.

    All collections are automatically closed when you disconnect a session.

    You can have only a limited number of collections open simultaneously on any particular session. This limit is frequently configured to 10 sessions; therefore, you should close a collection once you are finished with it.

    Note: If you set the trace level to any level above 0, and a collection object goes out of scope before you close it, the DFC will write the following message to the trace stream:
    `"Failed to close collection identifier (QID=collection ID)`"
    Threading considerations preclude the DFC from closing the collection in the finalizer method.

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

    >      IDfQuery q = new DfQuery();
    >      q.setDQL("select * from dm_document");
    >      IDfCollection col = q.execute(sess, DfQuery.DF_READ_QUERY);
    >      col.close();

    Throws:
      `DfException` - if a server error occurs.
    See Also:
      - `next()`
      - `IDfQuery.setDQL(java.lang.String)`
      - `IDfQuery.execute(com.documentum.fc.client.IDfSession, int)`

  - ### getState

    int getState()
    Returns the state of a collection object. The following list specifies the collection state corresponding to all return values:

         Integer      Collection State     Defined Static Variable
         1           Ready           IDfCollection.DF_READY_STATE
         2           Closed          IDfCollection.DF_CLOSED_STATE
         3           No More Rows    IDfCollection.DF_NO_MORE_ROWS_STATE

    Returns:
      the state of the collection object
    See Also:
      - `DF_READY_STATE`
      - `DF_CLOSED_STATE`
      - `DF_NO_MORE_ROWS_STATE`

  - ### getStateEx

    int getStateEx()
    Returns the state of a collection object. The following list specifies the collection state corresponding to all return values:

         Integer      Collection State     Defined Static Variable
         0           Initial         IDfCollection.DF_INITIAL_STATE
         1           Ready           IDfCollection.DF_READY_STATE
         2           Closed          IDfCollection.DF_CLOSED_STATE
         3           No More Rows    IDfCollection.DF_NO_MORE_ROWS_STATE

    Returns:
      the state of the collection object
    See Also:
      - `DF_INITIAL_STATE`
      - `DF_READY_STATE`
      - `DF_CLOSED_STATE`
      - `DF_NO_MORE_ROWS_STATE`

  - ### getBytesBuffer

    ByteArrayInputStream getBytesBuffer(String cmd, String buf, String buflen, int length) throws DfException
    Reserved for internal use.
    Parameters:
      `cmd` - the server API that returned the collection object
      `buf` - the name of the server API's attribute that points to the contents stored in memory
      `buflen` - the name of the server API's attribute that specifies the size, in bytes, of the contents stored in memory
    Returns:
      a ByteArrayInputStream containing the value stored in the memory contained in the collection object
    Throws:
      `DfException` - if a server error occurs