IBM Support

ICM search: Finding an item with only the Item ID

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.

    1. Recreate the DDO: DKDDO ddo = dsICM.createDDO(pidString);
    2. Retrieve the item: ddo.retrieve(options);
Querying with only an Item ID

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.
Use query/search as shown in the example below. Take the following notes on performance into consideration.
    • 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.
The following example is best used with the DK_CM_VERSION_LATEST retrieve option to simply get the latest version of the root component to the item.


/**
 * 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.

[{"Product":{"code":"SSRS7Z","label":"IBM Content Manager Enterprise Edition"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Component":"DB2 Information Integrator for Content","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"}],"Version":"8.1;8.2","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}},{"Product":{"code":"SSRS7Z","label":"IBM Content Manager Enterprise Edition"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Component":"Usage","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF027","label":"Solaris"},{"code":"","label":"UNIX"},{"code":"","label":"Windows 2000"},{"code":"","label":"Windows NT"},{"code":"","label":"Windows XP"}],"Version":"8.1;8.2","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}}]

Document Information

Modified date:
06 July 2019

UID

swg21160777

Page Feedback