Retrieving an item

IBM® Content Manager provides several retrieve options.

To retrieve an item, you must first obtain a DDO object with completed PID information that represents the item (or the component). If you have access to a completed PID object or know the PID string of the item to be retrieved, you can reconstruct a DDO object by using the DKDatastoreICM::createDDOFromPID() method. The DKDatastoreICM::createDDOFromPID() method accepts a PID object or a PID string. You can also use a query to find the items and return DDOs with completed PID information.

Note: The query determines the list of PIDs and creates blank DDOs with the completed PIDs, but the query can call a multi-item retrieve method before returning the DDOs based on your query options.

After you have obtained any valid DDO object, you can retrieve or refresh its contents. You can directly retrieve any DDO that includes the root component, the child component, and individual document part DDOs. An item is accessed through the root component DDO.

There are two types of retrieve methods: multi-item retrieve and single-item retrieve. Multi-item retrieve operation offers a significant performance advantage over single-item retrieve operation that makes separate calls to the server. Whenever you plan to retrieve more than one DDO, you must always use the multi-item retrieve operation unless you require data that can be retrieved only through the single-item retrieve operation.

For example, resource content can be retrieved only through the single-item retrieve operation. When you specify the retrieve options in a query (or search), the query uses the multi-item retrieve operation on the results. You should use the multi-item retrieve operation for all common metadata required from all DDOs. When one DDO requires additional content, such as resource content for a specific item, that item should be retrieved with the single-item retrieve method. For examples of method signatures of single-item retrieve and multi-item retrieve operations and query, see DKDatastoreICM::retrieveObjects(dkCollection,DKNVPair[]) in Application Programming Reference.

IBM Content Manager provides a DKRetrieveOptionsICM class and an integrated DKProjectionListICM class. The granular retrieve options are designed to select data that is required. In addition to the built-in optimizations automatically enabled by using DKRetrieveOptions method, you can get better retrieval performance by retrieving only the subset of data that you plan to use.

Retrieving child components and document parts

You can directly retrieve or refresh individual child components and document part DDOs without calling the retrieve operation on the parent DDOs. However, you cannot update the items by retrieving the component and calling the DKDDO.update() method. All updates must be done through the root component for the item or document. You must modify the child component or document part within the retrieved structure of the root component before calling the DKDDO.update() method on the root component.

Specifying requests and exclusions by using retrieve options

Always specify your list of requests and exclusions for a better performance based on the performance considerations that are documented in the DKRetrieveOptionsICM class under Application Programming Reference. Submitting a DKRetrieveOptionsICM instance enables additional retrieve optimizations that are not available through default or bitwise option behavior if no DKRetrieveOptionsICM instance is submitted.

Important: If you do not specify requests and exclusions, the application performance can be severely impacted.

You must use retrieve options specified through DKRetrieveOptionsICM class to specify what subset of data is required. You should retrieve only the data that you use. You can improve your performance by using retrieve options carefully and spending performance costs only for the data that you use.

For data that you might use for one item only, defer additional retrievals until that data is required. For example, if you are listing 10,000 query results, consider retrieving only minimal attributes for the first page of results and retrieve more data only if the user requests the next page or clicks on a document to view.

You can avoid unnecessary calls to the server, network communication, memory use and object counts for unnecessary objects, and other overhead. Performance implications of every retrieve option setting is documented in the Javadoc reference documentation in DKRetrieveOptionsICM class.

You must always provide retrieve options even if you do not retrieve any new data. The retrieve options that you set are built incrementally with nothing selected by default. Each retrieve option that you set as true is considered a specific request for data and any option that is set as false (default) is considered a specific request to exclude that data. It is better to submit an options object with no changes to demonstrate that you are not requesting any data. If retrieve options are not specified, various selections based on the deprecated bitwise integer retrieve options variants are included by default. The default varies depending on which method you use.

Important: Always use DKRetrieveOptionsICM class whenever possible over the bitwise integer or long retrieve options or no-option variants. By using DKRetrieveOptionsICM class, you enable a number of optimizations and product updates that are not available when you use the old bitwise integer retrieve options, even with equivalent retrieve settings. If you had previously used the bitwise integer retrieve options, see the DKRetrieveOptionsICM class under Application Programming Reference.

For more details, see the Javadoc information for:

DKRetrieveOptionsICM
DKDatastoreICM::retrieveObjects(dkCollection, DKNVPair[])

Additional documentation and examples are provided in the SItemRetrievalICM sample.

Retrieve PID validation or unspecified version number 0

For Java™ APIs, the basic validation for PID completion is relaxed to allow unspecified version number 0 without requiring you to also specify a retrieve option for the latest version. Individual DDOs with unspecified version 0 in their PID now retrieve the latest version for that particular DDO, regardless of whether you specify the retrieve option for the latest version. You can request the latest version for individual DDOs among collections submitted to multi-item retrieve method. You can submit DDOs from retrieved links and folder contents listings without specifying the retrieve option for the latest version.

Retrieving an item: Example

After connecting using a DKDatastoreICM object, search for the item by using the appropriate item ID or other attribute conditions.

Save the query results in a DKResults object if you are using evaluate(). In the following code example, queryStr is the search string in the correct query language format.

DKRetrieveOptionsICM dkRetrieveOpts = 
DKRetrieveOptionsICM::createInstance(dsICM); 
DKNVPair options[] = new DKNVPair[2]; 
options[0] = new DKNVPair(DKConstant.DK_CM_PARM_RETRIEVE,dkRetrieveOpts); 
options[1] = new DKNVPair(DKConstant.DK_CM_PARM_END,null); 
DKResults results = (DKResults)dsICM.evaluate(queryStr, DKConstantICM.DK_CM_XQPE_QL_TYPE, options);

Create an iterator on DKResults and use it to get DDOs, with completed PIDs
Instead of using the query, if you have a PID string that you obtained from a DDO previously and use that PID string to reconstruct a new DDO for an existing item, use the DKDatastoreICM's createDDOFromPID(DKPidICM pid) or createDDOFromPID(String pidString) methods as shown in the following example.
Do not use the DKDDO constructor. You can use this method to re-create a blank DDO if you want to completely clear the existing data within an existing DDO.
Note: If you just performed a query, you can use the DDOs that are returned from query directly.
```
DKPidICM   pid    = ddo.getPidObject(); 
String     pidStr = pid.pidString();
DKDDO      ddo    = dsICM.createDDOFromPID(pid); 
DKDDO      ddo2   = dsICM.createDDOFromPID(pidStr); 
```