IDfCollections, Part I

In this post I will cover the basic use of IDfCollections.

An IDfCollection object contains the results of a query. You can think of an IDfCollection object as a table with rows and columns. The columns represent the SELECT variables requested in the DQL query, and the rows represent the objects that met the query criteria. It would be tempting (and nice!) to think of an IDfCollection like a java.sql.ResultSet, but it isn’t that functional.

Processing a collection refers to retrieving the data from the IDfCollection object and doing something with it. This is one of the most basic and common tasks you will implement as a Documentum developer. It is a simple task, yet it does require care to avoid some pitfalls.  The following code illustrates how basic IDfCollection processing is done.

String dql = "select r_object_id, object_name, r_creation_date, a_content_type, r_full_content_size, a_is_template from dm_document where folder('/Temp', descend)";
IDfQuery q = new DfQuery();
q.setDQL(dql);
IDfCollection col = q.execute(session, DfQuery.DF_READ_QUERY);
while(col.next()) {
    System.out.print(col.getId("r_object_id").toString() + "\t");
    System.out.print(col.getString("object_name") + "\t");
    System.out.print(col.getDate("r_creation_date").toString() + "\t");
    System.out.print(col.getString("a_content_type") + "\t");
    System.out.print(col.getLong("r_full_content_size") + "\t");
    System.out.println(col.getBoolean("a_is_template").toString());
}
col.close();

Obviously, you will probably do something more interesting with the IDfCollection contents than just printing the results. And therein lies the potential for some problems.

• First, use the next() method to iterate through the contents of the IDfCollection.  Unfortunately, this is the only choice you have.  Unlike the java.sql.ResultSet object that allows forward, backward, and random access to the rows of the collection, the IDfCollection object provides for forward, sequential processing only.
• Always make sure you close() IDfCollections.  You can do it at the end of the processing loop, or in the finally section of a try-catch-finally block.  If you forget, eventually the garbage collector will close and clean them up for you.  However, you are limited to how many collections you can have open at one time (the default is 10).  If you exceed the limit, the DFC won’t let you open any additional IDfCollections until a previous one is closed.
• You can fetch an entire row of the IDfCollection object using the getTypedObject() method like this:
  

  while (col.next()) {
  // *** AVOID THIS ***
  IDfTypedObject tObj = col.getTypedObject();
  System.out.println(tObj.getString(“r_object_id”));
  }

  Unless you have a really good reason, you usually want to avoid instantiating an object just to access its attributes.  All this does is add an unneccessary layer of objects to your code.  Unless you really need the functionality the IDfTypedObject gives you, just retrieve column values directly from the IDfCollection object.

• Also, try to avoid instantiating whole IDfSysObjects from within the processing loop. It seems reasonable (but a little lazy) to write a query that just selects the r_object_id that meets the query criteria, and then instantiates an IDfSysObject to get the rest of the information you are interested in. However, this, like the bullet above, adds unneccessary layers of objects and consumes time and resources. Instantiating an entire IDfSysObject is much more “expensive” than just retrieving specific attributes from and IDf Collection.
  

  while (col.next()) {
  // *** AVOID THIS ***
  IDfSysObject sObj = (IDfSysObject) session.getObject(new DfId(col.getString(“r_object_id”)));
  System.out.print(sObj.getObjectId().toString() + “\t”);
  System.out.println(sObj.getObjectName());
  }

Now, having said all that, in part III of this series I’ll show you when you might actually want to retrieve each row of an IDfCollection object inside of its processing loop.  Next week I’ll talk about determining the size of a collection, detecting if a collection is empty, and a generic processing loop.

Advertisement