Question & Answer
Question
How can I retrieve an item with only the Item ID?
Answer
Although no API allows retrieval of an item given just the Item ID, both the query/search and retrieve (given a complete persistent ID (PID)) can work.
Querying with a complete PID String
In order to uniquely identify a specific component DDO, a complete PID is required to directly retrieve an item. An item is accessed by a root component DDO identified by object type, item ID, and component ID.
- Recreate the DDO: DKDDO ddo = dsICM.createDDO(pidString);
- Retrieve the item: ddo.retrieve(options);
If you only have the Item ID, then that can only limit the number matching components down to all versions of all components that make up the item. Multiple versions and multiple components can exist for the same item ID. You can narrow down the possibilities by limiting the available list down to only root components. However, that leaves all versions of that root component. Next you will need to pick a version. To narrow down the version choices, select from the following.
- Select a predetermine version number, such as '1'.
- Tell query to get the latest version in all cases.
- If you know that versioning is not enabled for the item type, you can omit further specification.
- If you know the item type, always specify it instead of a wildcard for faster performance. Otherwise the '*' wildcard should work in most cases.
- Searching only for the Item ID with no attribute conditions or traversals should perform well since it will primarily search one table.
/**
* Find the specified item based on item id , Item type or
* view type. It will throw an exception if multiple versions
* are found or 'null' if none found. While an Item ID is not
* what makes a DKDDO unique, it should return a single DKDDO
* in most cases.
* @param dsICM - Connected DKDatastoreICM object.
* @param entityTypeName - Item Type or Item Type View name.
* Can use '*' wildcard if this is
* not known.
* @param itemId - Item Id of the item to retrieve.
* @param retrieveOptions - Retrieve Options to pass to query.
* Use the DK_CM_VERSION_LATEST option
* to just get the latest version.
* @return Returns one DDO or 'null' if none found.
**/
public static DKDDO findItem(DKDatastoreICM dsICM, String entityTypeName, String itemId ,int retrieveOptions)
throws DKException, Exception{
// Validate Input
if(dsICM==null) throw new Exception("Invalid Input. 'dsICM' is null.");
if(!dsICM.isConnected()) throw new Exception("Invalid Input. Datastore input was never connected.");
if(entityTypeName==null) throw new Exception("Invalid Input. 'entityTypeName' is null.");
if(entityTypeName.trim().length()==0) throw new Exception("Invalid Input. 'entityTypeName' is an empty string.");
if(itemId==null) throw new Exception("Invalid Input. 'itemId' is null.");
if(itemId.trim().length()==0) throw new Exception("Invalid Input. 'itemId' is an empty string.");
System.out.println(" Find Item: '"+itemId);
System.out.println(" Of Type: '"+entityTypeName+"'");
System.out.println("Retrieve Options: "+retrieveOptions);
// Build the query string to look like: "/<EntityType>"
String queryString = "/"+entityTypeName+"[@ITEMID=\""+itemId+"\"]";
System.out.println("Query = :"+queryString);
// Evaluate Query
DKNVPair parms[] = new DKNVPair[3];
parms[0] = new DKNVPair(DKConstant.DK_CM_PARM_MAX_RESULTS, "2");
parms[1] = new DKNVPair(DKConstant.DK_CM_PARM_RETRIEVE, new Integer(retrieveOptions));
parms[2] = new DKNVPair(DKConstant.DK_CM_PARM_END, null);
DKResults results = (DKResults)dsICM.evaluate(queryString, DKConstant.DK_CM_XQPE_QL_TYPE, parms); // Evaluate Query
// Throwing error if multiple found.
if(results.cardinality()>1)
throw new Exception("More than one version of the root component was found. This function only supports uniquely identifying a single root component if the latest version retrieve option or an item type with versioning disabled is used.");
if(results==null) throw new Exception("Results collection null. This is unexpected.");
dkIterator iter = results.createIterator();
DKDDO ddo = null;
if(iter.more()) // If there are any items,
ddo = (DKDDO) iter.next(); // get the next item in the results
if(ddo!=null){
System.out.println("Found DDO: ObjType ='"+((DKPidICM)ddo.getPidObject()).getObjectType()+"'.");
System.out.println(" ItemID ='"+((DKPidICM)ddo.getPidObject()).getItemId()+"'.");
System.out.println(" CompID ='"+((DKPidICM)ddo.getPidObject()).getComponentId() +"'.");
System.out.println(" VerID ='"+((DKPidICM)ddo.getPidObject()).getVersionNumber() +"'.");
} else {
System.out.println("Item not found.");
}
if(iter.more())
System.out.println("Found DDO: + MORE EXIST");
return(ddo);
}//end findItem
More information
- Refer to the SItemTypeRetrievalICM API education sample for more documentation on retrieving items, PID strings, and retrieve options.
- Refer to the SSearchICM API education sample for more documentation on query / search.
- All API samples are installed in the <CMBROOT>\Samples\java\icm and <CMBROOT>\Samples\cpp\icm directory if the Samples & Toolkits for this connector are selected during installation of IBM® DB2® Information Integrator for Content with its connector to DB2 Content Manager. By default, the installation directory on Windows® is C:\CMBROOT and indicated by the CMBROOT environment variable.
Was this topic helpful?
Document Information
Modified date:
06 July 2019
UID
swg21160777