Enterprise Information Portal APIs

com.ibm.mm.sdk.server
Class DKDatastoreICM

java.lang.Object
  |
  +--com.ibm.mm.sdk.server.dkAbstractDatastore
        |
        +--com.ibm.mm.sdk.server.DKDatastoreICM
All Implemented Interfaces:
DKConstant, dkDatastore, dkDatastoreIntICM, DKMessageId, dkQueryEvaluator, dkQueryManager

public class DKDatastoreICM
extends dkAbstractDatastore
implements dkDatastoreIntICM

The DKDatastoreICM class is the IBM Content Manager Version 8 and later implementation of the abstract class dkDatastore. Use this class to represent a Content Manager content server in your program. For earlier versions of Content Manager, use DKDatastoreDL.

This class provides facilities to query, retrieve, update, store, and manage content stored in a Content Manager datastore.

The DKDatastoreICM class does not support concurrent access from multiple threads in a multi-threaded program. You need to synchronize concurrent access to the datastore instance in your application. It is recommended that you use one instance of the datastore for each thread.

Since:
Version 8

Fields inherited from interface com.ibm.mm.sdk.common.DKConstant
    For details, see the class or interface
 
Fields inherited from interface com.ibm.mm.sdk.common.DKMessageId
    For details, see the class or interface
 
Constructor Summary
DKDatastoreICM()
          Constructs the datastore and initializes it with the default configuration.
DKDatastoreICM(java.lang.String configuration)
          Constructs the datastore and initializes it using the supplied configuration string.
 
Method Summary
 void addExtension(java.lang.String extensionName, dkExtension extensionObj)
          Adds a new extension object to this datastore.
 void addObject(dkDataObject ddo)
          Adds this DDO into the Content Manager persistent store.
 void addObject(dkDataObject ddo, int option)
          Adds this DDO into the Content Manager persistent sore, with options.
 boolean adminDomainEnabled()
          Returns whether administration domain is enabled for this datastore.
 void changePassword(java.lang.String userId, java.lang.String oldPwd, java.lang.String newPwd)
          Allows a user to change password if authorized
 void checkIn(dkDataObject item)
          Checks in an item previously checked out from the datastore.
 void checkOut(dkDataObject item)
          Checks out an item from the datastore.
 void commit()
          Commits a datastore transaction.
 void connect(java.lang.String datastore_name, java.lang.String user_name, java.lang.String authentication, java.lang.String connect_string)
          Establishes a connection to a Content Manager datastore.
 DKHandle connection()
          Gets the connection handle for this datastore.
 DKDDO createChildDDO(java.lang.String objectType, java.lang.String componentName)
          Creates a child DDO of the given component name under the specified root component.
 DKDDO createDDO(DKPidICM pid)
          Creates a new DDO with object type, properties and attributes set according to the corresponding definition of the item type in this datastore.
 DKDDO createDDO(DKPidICM pid, java.lang.String[] fedAttributeList)
          Creates a new DDO with object type, properties and attributes set based on the suplied Pid and attribute list.
 DKDDO createDDO(java.lang.String pidString)
          Creates a new DDO with object type, properties and attributes set according to the corresponding definition of the item type in this datastore.
 DKDDO createDDO(java.lang.String objectType, int flags)
          Creates a new DDO with object type, properties and attributes set according to the definition of the corresponding item type in this datastore.
 dkDatastoreDef datastoreDef()
          Gets the datastore definition object.
 java.lang.String datastoreName()
          Gets the name of this datastore object.
 java.lang.String datastoreType()
          Gets the datastore type for this datastore.
 void deleteObject(dkDataObject ddo)
          Deletes the specified DDO from the persistent datastore.
 void deleteObject(dkDataObject ddo, int option)
          Deletes this DDO from the persistent store.
 void deleteObjects(dkCollection ddoCollection)
          Deletes a collection of DDOs from the persistent store.
 void deleteObjects(dkCollection ddoCollection, int option)
          Deletes DDOs from this datastore.
 void destroy()
          Destroys the datastore object.
 void disconnect()
          Disconnects from a Content Manager datastore.
 java.lang.Object evaluate(DKCQExpr cqe)
          Evaluates a combined query expression cqe against this datastore and returns the results in a collection.
 java.lang.Object evaluate(java.lang.String command, short commandLangType, DKNVPair[] params)
          Evaluates query string command by executing it against this datastore and returning all results in a collection.
 dkResultSetCursor execute(DKCQExpr cqe)
          Executes a combined query expression cqe against this datastore and returns a result set cursor object to provide access to the results.
 dkResultSetCursor execute(java.lang.String command, short commandLangType, DKNVPair[] params)
          Executes query string command against this datastore and returns a result set cursor object to provide access to the results.
 void executeWithCallback(DKCQExpr cqe, dkCallback callbackObj)
          Executes a combined query expression cqe against this datastore in asynchronous manner and sends the results to the specified callback object callbackObj in blocks.
 void executeWithCallback(java.lang.String command, short commandLangType, DKNVPair[] params, dkCallback callbackObj)
          Executes query string command against this datastore in asynchronous manner and sends the results to the specified callback object callbackObj in blocks.
 dkExtension getExtension(java.lang.String extensionName)
          Gets the specified extension object from this datastore.
 dkSchemaMapping getMapping(java.lang.String mappingName)
          Gets the specified schema mapping information registered in this datastore.
 java.lang.Object getOption(int option)
          Gets a datastore option.
 DKHandle handle(java.lang.String type)
          Gets a datastore handle.
 boolean isConnected()
          Checks to see if the datastore is connected.
 boolean LDAPEnabled()
          Returns whether LDAP is enabled for this datastore.
 dkCollection listAdminEvents(short maxResults)
          Lists all events related to System Administration functions.
 java.lang.String[] listDataSourceNames()
          Lists the names of the available datastores that can be used to connect with.
 dkCollection listDataSources()
          Lists the available datastores that can be used to connect with.
 dkCollection listEntities()
          Gets a list of entities from persistent store.
 java.lang.String[] listEntityAttrNames(java.lang.String entityName)
          Gets a list of attribute names for a given entity name.
 dkCollection listEntityAttrs(java.lang.String entityName)
          Gets a list of attributes for a given entity name.
 java.lang.String[] listEntityNames()
          Gets a list of entity names from persistent store.
 dkCollection listEvents(java.lang.String itemId, short maxResults)
          Lists all events related to the given item id.
 java.lang.String[] listExtensionNames()
          Gets the list of extension objects' names available in this datastore.
 java.lang.String[] listMappingNames()
          Gets the list of registered mapping information from this datastore.
 void moveObject(dkDataObject sourceDDO, dkDataObject destinationDDO, int options)
          Moves the data-object from the current item type to another in this datastore.
 void moveObject(dkDataObject ddo, java.lang.String destinationItemType)
          Moves the data-object from the current item type to another item type in this datastore.
 short platform()
          Returns the platform on which the server for this datastore.
 java.lang.String registerMapping(DKNVPair sourceMap)
          Registers mapping information to this datastore.
 void removeExtension(java.lang.String extensionName)
          Removes an existing extension object from this datastore.
 dkCollection retrieveEvent(int eventCode, short maxResults)
          Retrieves events information for the given event code from the persistent event log.
 dkXDO retrieveFormOverlay(java.lang.String name)
          Retrieves the form overlay object.
 void retrieveObject(dkDataObject ddo)
          Retrieves a DDO from Content Manager persistent store.
 void retrieveObject(dkDataObject ddo, DKNVPair[] options)
          Retrieves this DDO from the persistant store, with options.
 void retrieveObject(dkDataObject ddo, int option)
          Retrieves this DDO from the Content Manager Persistant store, with options.
 void retrieveObjects(dkCollection ddoCollection)
          Retrieves this collection of DDO's from the persistant store.
 void retrieveObjects(dkCollection ddo, DKNVPair[] options)
          Retrieves a collection of DDO's from the persistant store.
 void retrieveObjects(dkCollection ddoCollection, int option)
          Retrieves this collection of DDO's from the persistant store.
 void rollback()
          Rollbacks a datastore transaction.
 java.lang.String schemaName()
          Returns the schema Name
 void setOption(int option, java.lang.Object value)
          Sets a datastore option.
 void startTransaction()
          Starts an explicit transaction.
 boolean textSearchEnabled()
          Returns whether text search is enabled for this datastore.
 void unRegisterMapping(java.lang.String mappingName)
          Unregisters mapping information from this datastore.
 void updateObject(dkDataObject ddo)
          Updates this DDO in the persistent store.
 void updateObject(dkDataObject ddo, int option)
          Updates this DDO in the persistent store.
 java.lang.String userName()
          Gets the user name for this datastore.
 void writeEvent(DKEventDefICM aEvent)
          Writes this event information to the persistent event log.
 
Methods inherited from class com.ibm.mm.sdk.server.dkAbstractDatastore
addObject, addObjects, addObjects, addObjects, clearCache, clearCache, createQuery, createQuery, deleteObject, deleteObjects, evaluate, evaluate, execute, execute, executeWithCallback, executeWithCallback, listAvailableServices, listSchema, listSchemaAttributes, listSearchableEntities, listSearchableEntityNames, listSearchTemplateNames, listSearchTemplates, listServers, serviceMgr, updateObject, updateObjects, updateObjects, updateObjects
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.ibm.mm.sdk.common.dkDatastoreIntICM
informationMiningEnabled, workflowEnabled
 
Methods inherited from interface com.ibm.mm.sdk.common.dkDatastore
addObject, addObjects, addObjects, addObjects, clearCache, clearCache, createQuery, createQuery, deleteObject, deleteObjects, evaluate, evaluate, execute, execute, executeWithCallback, executeWithCallback, listAvailableServices, listSchema, listSchemaAttributes, listSearchableEntities, listSearchableEntityNames, listSearchTemplateNames, listSearchTemplates, listServers, serviceMgr, updateObject, updateObjects, updateObjects, updateObjects
 

Constructor Detail

DKDatastoreICM

public DKDatastoreICM()
               throws DKException,
                      java.lang.Exception
Constructs the datastore and initializes it with the default configuration.
Throws:
DKException - if a problem is encountered.

DKDatastoreICM

public DKDatastoreICM(java.lang.String configuration)
               throws DKException,
                      java.lang.Exception
Constructs the datastore and initializes it using the supplied configuration string.
Parameters:
configuration - configuration string used for initialization. Configuration string is a sequence of name/value pairs separated by semi colons. Valid name/value pairs are:
  • DSNAME=<datastore_name> Supplies the datastore name. Optional
  • DBAUTH=<SERVER | CLIENT> Database authentication information. If SERVER is supplied the database userid and password will be supplied to the server. If CLIENT is supplied no database userid and password will be supplied to the server. The default is SERVER. Optional
  • LDAPORG=<LDAP organization> Specifies the LDAP organization providing the directory information. This can be used when the list of datasources is in IBM Secure Way. Optional
  • ICMSERVERSFILE=<(datasource information file location)> Specifies the file location of the datasource information. Optional
  • ICMSERVERSURL=<(datasource information url location)> Specifies the url location of the datasource information. Optional
  • ICMENVFILE=<(database connection information file location)> Specifies the file location of the database connection information. Optional
  • ICMENVURL=<(database connection information url location)> Specifies the url location of the database connection information. Optional
  • CHKDBPOOL=<YES | NO> Check for database pooling. The default is YES. Optional
Throws:
DKException - if a problem is encountered.
Method Detail

connect

public void connect(java.lang.String datastore_name,
                    java.lang.String user_name,
                    java.lang.String authentication,
                    java.lang.String connect_string)
             throws DKException,
                    java.lang.Exception
Establishes a connection to a Content Manager datastore.
Specified by:
connect in interface dkDatastore
Overrides:
connect in class dkAbstractDatastore
Parameters:
datastore_name - the datastore name to connect with
user_name - the user name for establishing the connection
authentication - user's password
connect_string - the connect string used for initializing connection options. Connect string is a sequence of name/value pairs separated by semi-colons. Valid name/value pairs are listed below:
  • SQLUID=<database userid> userid for the underlying database. Optional
  • SQLPWD=<database password> user's password for the undelying database. Optional
  • DBAUTH=<SERVER | CLIENT> Database authentication information. If SERVER is supplied the database userid and password will be supplied to the server. If CLIENT is supplied no database userid and password will be supplied to the server. The default is SERVER. Optional
  • SCHEMA=<database schema> database schema name to use. Optional
  • APPLNAME=<application name> Specifies the application name you are running. It is used to identify trace and log information. Optional
  • NPWD=<new password for userid> Changes user's password to this new value. Only valid if userid is not a system userid. Optional
  • LANG=<database language> Server language. Optional
  • TRACESERVERLEVEL=<trace level> Trace level for the server. Optional
    • The default trace level for the server is 0.
    • ICM trace flags
      • 0 ICMTRACE_OFF
      • 1 ICMTRACE_BASIC
      • 2 ICMTRACE_DETAILED
      • 4 ICMTRACE_DATA
      • 8 ICMTRACE_PERFORMANCE
      • 16 ICMTRACE_PARSEBUILD
      • 32 ICMTRACE_MEMDEBUG
      • 256 ICMTRACE_CACHE_TRACE
      • 512 ICMTRACE_CACHE_ALLOC
      • 1024 ICMTRACE_CACHE_MGT
    • Trace level is constructed by adding the numbers above. For example, a common tracing level is 15 (calculated by adding up 1 (ICMTRACE_BASIC), 2 (ICMTRACE_DETAILED), 4 (ICMTRACE_DATA), and 8 (ICMTRACE_PERFORMANCE)).
Throws:
DKException - if a problem is encountered.

disconnect

public void disconnect()
                throws DKException,
                       java.lang.Exception
Disconnects from a Content Manager datastore.
Specified by:
disconnect in interface dkDatastore
Overrides:
disconnect in class dkAbstractDatastore
Throws:
DKException - if a problem is encountered.

getOption

public java.lang.Object getOption(int option)
                           throws DKException,
                                  java.lang.Exception
Gets a datastore option.
Specified by:
getOption in interface dkDatastore
Overrides:
getOption in class dkAbstractDatastore
Parameters:
option - the option identifier.
Returns:
an option value. Valid options and returned values are:
  • Option DK_CM_OPT_CACHE. Values are: <DK_CM_TRUE|DK_CM_FALSE> Cache is enabled. Default is DK_CM_TRUE. Optional
Throws:
DKException - if a problem is encountered.

setOption

public void setOption(int option,
                      java.lang.Object value)
               throws DKException,
                      java.lang.Exception
Sets a datastore option.
Specified by:
setOption in interface dkDatastore
Overrides:
setOption in class dkAbstractDatastore
Parameters:
option - the option identifier.
value - the option value.
Throws:
DKException - if a problem is encountered.
See Also:
above for valid options and values.

evaluate

public java.lang.Object evaluate(java.lang.String command,
                                 short commandLangType,
                                 DKNVPair[] params)
                          throws DKException,
                                 java.lang.Exception
Evaluates query string command by executing it against this datastore and returning all results in a collection. The total number of returned results can be limited by specifying the DKConstant.DK_CM_PARM_MAX_RESULTS query option.

For details on query syntax, refer to the Application Programming Guide.

Example:

 String query = "/Journal/Journal_Article[contains-text"
            + "(@Title, \" 'Design' & 'Index' \")=1] SORTBY (@Title)";
 DKNVPair options[] = new DKNVPair[3];
 options[0] = new DKNVPair(DKConstant.DK_CM_PARM_MAX_RESULTS, "50");
 options[1] = new DKNVPair(DKConstant.DK_CM_PARM_RETRIEVE,
                           new Integer(DKConstant.DK_CM_CONTENT_ATTRONLY |
                              DKConstant.DK_CM_CONTENT_LINKS_OUTBOUND));
 options[2] = new DKNVPair(DKConstant.DK_CM_PARM_END, null);
 DKResults results = (DKResults)dsICM.evaluate(query,
                                  DKConstant.DK_CM_XQPE_QL_TYPE, options);

 // Display results in the collection.
 dkIterator iter = results.createIterator();
 System.out.println("  Number of Results: " + results.cardinality());
 DKDDO  ddo = null;
 while(iter.more()) {
   ddo = (DKDDO) iter.next();
   System.out.println("     - Item ID:  "
          + ((DKPidICM)ddo.getPidObject()).getItemId()
          + "  (" + ddo.getPidObject().getObjectType() + ")");
 }
 

Specified by:
evaluate in interface dkDatastore
Overrides:
evaluate in class dkAbstractDatastore
Parameters:
command - a query string
commandLangType - a type of query (must be DKConstant.DK_CM_XQPE_QL_TYPE)
params - additional query options in the form of name/value pairs (refer to the execute method for more details)
Returns:
a collection of results for this query
Throws:
DKException - if a problem is encountered
java.lang.Exception - if a problem is encountered
See Also:
execute(String, short, DKNVPair[]), executeWithCallback(String, short, DKNVPair[], dkCallback)

evaluate

public java.lang.Object evaluate(DKCQExpr cqe)
                          throws DKException,
                                 java.lang.Exception
Evaluates a combined query expression cqe against this datastore and returns the results in a collection. This method is mostly used internally to run federated queries and is not advised for external use. Use the string version of the evaluate method to execute your queries.

Specified by:
evaluate in interface dkDatastore
Overrides:
evaluate in class dkAbstractDatastore
Parameters:
cqe - a combined query expression object
Returns:
a collection of results for this query
Throws:
DKException - if a problem is encountered
java.lang.Exception - if a problem is encountered
See Also:
evaluate(String, short, DKNVPair[]), execute(String, short, DKNVPair[]), executeWithCallback(String, short, DKNVPair[], dkCallback)

execute

public dkResultSetCursor execute(java.lang.String command,
                                 short commandLangType,
                                 DKNVPair[] params)
                          throws DKException,
                                 java.lang.Exception
Executes query string command against this datastore and returns a result set cursor object to provide access to the results.

For details on query syntax, refer to the Application Programming Guide.

A few notes about using the result set cursor.

Important: make sure to close and destroy the result set cursor once you have finished using it. To close the result set cursor, call one of the following methods: dkResultSetCursor.close(), dkResultSetCursor.destroy(). To completely clean up the result set cursor, it is suggested that you use dkResultSetCursor.destroy(). All open result set cursors are closed when either dkDatastore.disconnect() or dkDatastore.destroy() method is called.

If you want the result set cursor to be automatically processed for you while performing a query, use the DKDatastoreICM.evaluate method. This method automatically closes the result set cursor before returning all the results in a collection.

Example:

 String query = "/Journal[@NumPages > 50]";
 DKNVPair options[] = new DKNVPair[3];
 options[0] = new DKNVPair(DKConstant.DK_CM_PARM_MAX_RESULTS, "100");
 options[1] = new DKNVPair(DKConstant.DK_CM_PARM_RETRIEVE,
                          new Integer(DKConstant.DK_CM_CONTENT_CHILDREN));
 options[2] = new DKNVPair(DKConstant.DK_CM_PARM_END, null);
 dkResultSetCursor cursor = dsICM.execute(query,
                                  DKConstant.DK_CM_XQPE_QL_TYPE, options);

 DKDDO  ddo = null;
 String itemId = "";

 // Display results using a result set cursor.
 while((ddo = cursor.fetchNext()) != null){
   itemId = ((DKPidICM)ddo.getPidObject()).getItemId();
   System.out.println("     - Item ID:  " + itemId + "  ("
                      + ddo.getPidObject().getObjectType() + ")");
 }
 // VERY IMPORTANT STEP:
 cursor.destroy(); // Close & destroy cursor, ending implicit transaction.
 

Specified by:
execute in interface dkDatastore
Overrides:
execute in class dkAbstractDatastore
Parameters:
command - a query string
commandLangType - a type of query (must be DKConstant.DK_CM_XQPE_QL_TYPE)
params - additional query options in the form of name/value pairs
  Description of query options:
  • Name = DKConstant.DK_CM_PARM_MAX_RESULTS
    Value = An integer in string format that specifies the maximum number of results that will be returned by the query.
    If this option is specified, the result set cursor stops processing results when this number of results has been processed. No indication is given to the application that there are additional results available. If max results is set to 0, there is no max, so all results will be returned.
    If this option is not specified, all results will be returned.
    Example: "5"
  • Name = DKConstant.DK_CM_PREPARE_QUERY
    Value = none required.
    If this option is specified, the query is only prepared, but the cursor is not opened, and the query is not actually executed. The result set cursor's open() method must be called to open the cursor and execute the query.
    If this option is not specified, the query will be prepared, the cursor opened, and the query will be executed.
  • Name = DKConstant.DK_CM_PARM_PREFETCH_SIZE
    Value = Integer value
    If this option is specified, the value for this option indicates the block size in which results are retrieved from the datastore. A small value N will allow for faster display of the first N results, but will increase overall retrieval time for the whole result set.
    If this option is not specified, a default block size, which should be optimal for majority of applications, will be used.
  • Name = DKConstant.DK_CM_PARM_CONTENT
    This option specifies how much content is retrieved when results are returned from the query. This option is ignored if the DKConstant.DK_CM_PARM_RETRIEVE is specified. It is suggested to always use DKConstant.DK_CM_PARM_RETRIEVE option instead of the DKConstant.DK_CM_PARM_CONTENT option.
    Value = one of the following strings: "IDONLY", "NO", "ATTRONLY", and "YES".
    Here is how these option values are mapped to retrieve option values used with the DKConstant.DK_CM_PARM_RETRIEVE option:
    "IDONLY" = DKConstant.DK_CM_CONTENT_IDONLY
    "NO" = DKConstant.DK_CM_CONTENT_NO
    "ATTRONLY" = DKConstant.DK_CM_CONTENT_ATTRONLY
    "YES" = (DK_CM_CONTENT_ATTRONLY | DK_CM_CONTENT_CHILDREN | DK_CM_CONTENT_YES)
    If this option is not specified, default retrieval value is "ATTRONLY".
  • Name = DKConstant.DK_CM_PARM_RETRIEVE
    Value = described under DKDatastoreICM.retrieveObject(dkDataObject, int) method.
    If this option is specified, it takes precedence over the DKConstant.DK_CM_PARM_CONTENT option above. This option specifies what to retrieve for the items that are returned.
    If this option is not specified, retrieval is DKConstant.DK_CM_CONTENT_ATTRONLY.
    If you do not want the results to be retrieved at all, set the value to DKConstant.DK_CM_CONTENT_IDONLY.
    For performance reasons, content retrieval from the resource manager is never done by query. To retrieve content stored on the resource manager, use the DDO returned from query, set the content retrieve option, and call one of the retrieve methods that accept a single DDO.
  • Name = DKConstant.DK_CM_PARM_PROJECTION_LIST
    Value = described under DKDatastoreICM.retrieveObject(dkDataObject, DKNVPair[]) method.
    This option allows the user to apply a projection onto which attributes get retrieved in the hierarchical representation of the returned item. This way, the returned DDO is set with only the desired attributes.

Returns:
a datastore result set cursor to the results of the query
Throws:
DKException - if a problem is encountered
java.lang.Exception - if a problem is encountered
See Also:
evaluate(String, short, DKNVPair[]), executeWithCallback(String, short, DKNVPair[], dkCallback), retrieveObject(dkDataObject, int), retrieveObject(dkDataObject, DKNVPair[])

execute

public dkResultSetCursor execute(DKCQExpr cqe)
                          throws DKException,
                                 java.lang.Exception
Executes a combined query expression cqe against this datastore and returns a result set cursor object to provide access to the results. This method is mostly used internally to run federated queries and is not advised for external use. Use the string version of the execute method to execute your queries.

Specified by:
execute in interface dkDatastore
Overrides:
execute in class dkAbstractDatastore
Parameters:
cqe - a combined query expression object
Returns:
a datastore result set cursor to the results of the query
Throws:
DKException - if a problem is encountered
java.lang.Exception - if a problem is encountered
See Also:
execute(String, short, DKNVPair[]), evaluate(String, short, DKNVPair[]), executeWithCallback(String, short, DKNVPair[], dkCallback)

executeWithCallback

public void executeWithCallback(java.lang.String command,
                                short commandLangType,
                                DKNVPair[] params,
                                dkCallback callbackObj)
                         throws DKException,
                                java.lang.Exception
Executes query string command against this datastore in asynchronous manner and sends the results to the specified callback object callbackObj in blocks. You can get the results from the callback object as soon as they are available. A callback object is any object that implements the dkCallback interface. This object is defined and created by the user program.

IMPORTANT: NO datastore operations are allowed from the callback object. For example, it is not allowed to list item type definitions or call CRUD (Create, Retrieve, Update, Delete) methods inside of the callback object's dataCallback(dkCollection, boolean) method. You can display the results as long as this does not require datastore operations or you can wait until the query completes as indicated by the isDone() method returning true.

If you want to stop receiving results, call the cancelQuery() method on your callbackObj object and wait until the isDone() method returns true.

Example:

 String query = "/Journal/Journal_Article[@VERSIONID = latest-version(.)]";
 DKNVPair options[] = new DKNVPair[2];
 options[0] = new DKNVPair(DKConstant.DK_CM_PARM_RETRIEVE,
                    new Integer(DKConstant.DK_CM_CONTENT_ITEMTREE));
 options[1] = new DKNVPair(DKConstant.DK_CM_PARM_END, null);
 // Create Callback Object (any object implementing dkCallback interface).
 SSearchCallbackObjectICM callbackObject = new SSearchCallbackObjectICM();
 dsICM.executeWithCallback(query, DKConstant.DK_CM_XQPE_QL_TYPE,
                           options, callbackObject);

 // Wait for Callback Object to receive all results.
 // This thread would normally do other work instead of simply waiting.
 boolean isDone = false;
 while(isDone == false) {
   System.out.println("Waiting...");
   java.lang.Thread.sleep(100);
   isDone = callbackObject.isDone();
   if(callbackObject.error()) {
     throw callbackObject.getFirstException();
   }
 }

 // Method in the callback object's class
 // that is called for every block of results.
 public boolean dataCallback (dkCollection ddoList,
                              boolean resultsComplete) {
   serverIsDone = resultsComplete;

   try {
     if (ddoList != null) {
       dkIterator iter = ddoList.createIterator();
       String itemId = "";
       while (iter.more()) {
         DKDDO ddo = (DKDDO) iter.next();
         results.add(ddo);
         itemId = ((DKPidICM)ddo.getPidObject()).getItemId();
         System.out.println ("Callback Object:  - Item ID:  " +
                            itemId + "  (" +
                            ddo.getPidObject().getObjectType() + ")");
       }
     }
   } catch (DKException e) {
     printException(e);
     if (firstException == null)    // If it is the first failure, save it
       firstException = e;
   }

   if (userRequestsCancel) { // If the user requests to cancel the query,
                             // report to server.
      return (true);
   } else {                  // Otherwise, return whether or not the server
                             // has indicated that it is done.
     return (serverIsDone);
   }
 }
 

Specified by:
executeWithCallback in interface dkDatastore
Overrides:
executeWithCallback in class dkAbstractDatastore
Parameters:
command - a query string
commandLangType - a type of query (must be DKConstant.DK_CM_XQPE_QL_TYPE)
params - additional query options in the form of name/value pairs
callbackObj - an object that will be called by this method for every block of results
Throws:
DKException - if a problem is encountered
java.lang.Exception - if a problem is encountered
See Also:
execute(String, short, DKNVPair[]), evaluate(String, short, DKNVPair[])

executeWithCallback

public void executeWithCallback(DKCQExpr cqe,
                                dkCallback callbackObj)
                         throws DKException,
                                java.lang.Exception
Executes a combined query expression cqe against this datastore in asynchronous manner and sends the results to the specified callback object callbackObj in blocks. This method is mostly used internally to run federated queries and is not advised for external use. Use the string version of the executeWithCallback method to execute your queries.

Specified by:
executeWithCallback in interface dkDatastore
Overrides:
executeWithCallback in class dkAbstractDatastore
Parameters:
cqe - a combined query expression object
callbackObj - an object that will be called by this method for every block of results
Throws:
DKException - if a problem is encountered
java.lang.Exception - if a problem is encountered
See Also:
execute(String, short, DKNVPair[]), evaluate(String, short, DKNVPair[]), executeWithCallback(String, short, DKNVPair[], dkCallback)

addObject

public void addObject(dkDataObject ddo)
               throws DKException,
                      java.lang.Exception
Adds this DDO into the Content Manager persistent store. The corresponding item type for this DDO must exist already.
Specified by:
addObject in interface dkDatastore
Overrides:
addObject in class dkAbstractDatastore
Parameters:
ddo - The DDO to be added to this datastore.
Throws:
DKException - if a problem is encountered.

addObject

public void addObject(dkDataObject ddo,
                      int option)
               throws DKException,
                      java.lang.Exception
Adds this DDO into the Content Manager persistent sore, with options. The only valid option is
Specified by:
addObject in interface dkDatastore
Overrides:
addObject in class dkAbstractDatastore
Parameters:
ddo - the DDO to be added to this datastore.
option - option for add.
Throws:
DKException - if a problem is encountered
java.lang.Exception - if a problem is encountered

retrieveObject

public void retrieveObject(dkDataObject ddo)
                    throws DKException,
                           java.lang.Exception
Retrieves a DDO from Content Manager persistent store. The DDO should contain a a valid peristent identifier (PID). The DDO may represent a root or child component of an item.
Specified by:
retrieveObject in interface dkDatastore
Overrides:
retrieveObject in class dkAbstractDatastore
Parameters:
ddo - the ddo to be retrieved from this datastore
Throws:
DKException - if a problem is encountered
java.lang.Exception - if a problem is encountered
DKDataObjectNotFound - if a problem is encountered
See Also:
retrieveObject(dkDataObject, int)

retrieveObject

public void retrieveObject(dkDataObject ddo,
                           int option)
                    throws DKException,
                           java.lang.Exception
Retrieves this DDO from the Content Manager Persistant store, with options. The DDO should contain a valid persistant identifier(PID). Options can be combined using OR boolean operator. These are the supported retrieve options: The default retrieve option is DK_CM_CONTENT_ONELEVEL.
Specified by:
retrieveObject in interface dkDatastore
Overrides:
retrieveObject in class dkAbstractDatastore
Parameters:
ddo - the ddo to be retrieved from this datastore
option - retrieve option, constructed by performing a logical OR (with | operator) of the supported options described above
Throws:
DKException - if a problem is encountered
java.lang.Exception - if a problem is encountered

retrieveObjects

public void retrieveObjects(dkCollection ddoCollection)
                     throws DKException,
                            java.lang.Exception
Retrieves this collection of DDO's from the persistant store. If the retrieval of all the DDO's in the collection fails, then an DKDataObjectNotFoundException will be thrown. If the retrieval of at least one of the the DDO's in the collection succeeds, then the DDO's that cannot be retrieved will be marked as FAIL in the last_operation property of DDO. This property contains a DKNVPair with (name,value) pair such as ("Retrieve","Success"). The default retrieve option is described under the retrieveObject (dkDataObject, int) method. This default will be applied to all DDO's in the collection.
For performance reasons, retrieve options related to content retrieval are ignored in retrieve methods that accept collections of DDO's. This behavior is equivalent to content retrieve option DK_CM_CONTENT_NO. The parts TOC is not retrieved by default. DK_CM_CONTENT_YES option retrieves the parts TOC for documents. Use retrieve methods that accept a single DDO to retrieve content.
Specified by:
retrieveObjects in interface dkDatastore
Overrides:
retrieveObjects in class dkAbstractDatastore
Parameters:
ddoCollection - collection of DDO's to be retrieved from this datastore
Throws:
DKException - if a problem is encountered
java.lang.Exception - if a problem is encountered
DKDataObjectNotFound - if a problem is encountered

retrieveObjects

public void retrieveObjects(dkCollection ddoCollection,
                            int option)
                     throws DKException,
                            java.lang.Exception
Retrieves this collection of DDO's from the persistant store. If the retrieval of all the DDO's in the collection fails, then an DKDataObjectNotFoundException will be thrown. If the retrieval of at least one of the the DDO's in the collection succeeds, then the DDO's that cannot be retrieved will be marked as such.
The retrieve option is applied globally to all the DDO's in the collection. For a list of valid retrieve options, refer to the retrieveObject (dkDataObject, int) method.
For performance reasons, retrieve options related to content retrieval are ignored in retrieve methods that accept collections of DDO's. This behavior is equivalent to content retrieve option DK_CM_CONTENT_NO. Use retrieve methods that accept a single DDO to retrieve content.
Specified by:
retrieveObjects in interface dkDatastore
Overrides:
retrieveObjects in class dkAbstractDatastore
Parameters:
ddoCollection - the collection of DDO's to be retrieved from this datastore
option - option for retrieve
Throws:
DKException - if a problem is encountered
java.lang.Exception - if a problem is encountered

retrieveObject

public void retrieveObject(dkDataObject ddo,
                           DKNVPair[] options)
                    throws java.lang.Exception
Retrieves this DDO from the persistant store, with options. You can specify retrieval with projections by providing a list of selected attributes in the option parameter. Attribute not in the list will not be retrieved.
Specified by:
retrieveObject in interface dkDatastore
Overrides:
retrieveObject in class dkAbstractDatastore
Parameters:
ddo - DDO to be retrieved from this datastore
options - DKNVPair[] options for retrieve
Supported Options (DKNVPair[] options for retrieve) if projection list is supplied
  • NAME: DKConstant.DK_CM_PARM_RETRIEVE, VALUE: Integer
    Supported Retrieve Options
    • DKConstant.DK_CM_CONTENT_ITEMTREE
    • DKConstant.DK_CM_CONTENT_ITEMTREE_NO_LINKS
    • DKConstant.DK_CM_CHECKOUT
    • DKConstant.DK_CM_VERSION_LATEST
    • DKConstant.DK_CM_CONTENT_LINKS_OUTBOUND
    • DKConstant.DK_CM_CONTENT_LINKS_INBOUND
      (these options are described under retrieveObject (dkDataObject, int) method)
  • NAME: DKConstant.DK_CM_PARM_PROJECTION_LIST, VALUE: DKNVPair[]
    This option allows the user to apply a projection onto which attributes get retrieved in the hierarchical representation of the returned item. This way, the returned DDO is set with only the desired attributes.
    Value Expected of DKConstant.DK_CM_PARM_PROJECTION_LIST
    • DKNVPair[0] = NAME: String of itemtype0 name, VALUE: dkCollection of Strings that are the qualified names of attributes to be projected for this item type
    • DKNVPair[1] = NAME: String of itemtype1 name, VALUE: dkCollection of Strings that are the qualified names of attributes to be projected for this item type
    • DKNVPair[2] = NAME: String of itemtype2 name, VALUE: dkCollection of Strings that are the qualified names of attributes to be projected for this item type
    • DKNVPair[...] = NAME: String of itemtype... name, VALUE: dkCollection of Strings that are the qualified names of attributes to be projected for this item type
    • DKNVPair[N] = NAME: String of itemtypeN name, VALUE: dkCollection of Strings that are the qualified names of attributes to be projected for this item type

    Specific Example of a Projection List
    • NAME: DKConstant.DK_CM_PARM_PROJECTION_LIST, VALUE: DKNVPair[
      • element 0: Name = "Journal", Value = collection of "Journal_Article/Journal_Section/Title", "Title", "Journal_Article/Title", "Journal_Article/Classification"
      • element 1: Name = "Book" Value = collection of "Book_Chapter/" + DK_ICM_ALL_ATTRS, "Book_Author/" + DK_ICM_SYSTEM_ATTRS, "Book_Chapter/Book_Section/SectionNum"
      • element 2: Name = "Conference" Value = collection of DK_ICM_ALL_ATTRS, "Conference_Note/NoteNum"]

    The names in the projection list should be partially qualified (contain the whole path to the attribute starting from [but NOT including] the root item type). See the DKAttrDefICM.getQualifiedName() and related methods for details. The names should not be fully qualified because the schema mapping already includes the entity name, which points to the root item type.

    Two new constants are defined in DKConstantICM:
    • String DK_ICM_ALL_ATTRS (all attributes [both system-defined and user-defined] should be returned for this component type). Note that a user attribute is allowed to be specified together with this parameter for the same component type. For example, if element 2 above is:
      element 2: Name = "Conference" Value = collection of DK_ICM_ALL_ATTRS, "Title", "Conference_Note/NoteNum"
      then all attributes belonging to the root component type Conference will be returned (since Title is one of them), and still only the NoteNum attribute will be returned for the Conference_Note component type.
    • String DK_ICM_SYSTEM_ATTRS (only system attributes should be returned for this component type). Note that since system attributes (e.g. ITEMID, VERSIONID) are always returned anyway, it is not necessary to include this parameter, for example, for Book_Section to only return SectionNum attribute in element 1 of the projection list above.

    Restrictions of Projections
    • No holes in the projection list
    • Projection list must start from root no matter what root/child component is being retrieved
Throws:
DKException - if a problem is encountered
java.lang.Exception - if a problem is encountered

retrieveObjects

public void retrieveObjects(dkCollection ddo,
                            DKNVPair[] options)
                     throws java.lang.Exception
Retrieves a collection of DDO's from the persistant store. You can specify retrieval with projections by providing a list of selected attributes in the option parameter. Attribute not in the list will not be retrieved. If the retrieval of all the DDO's in the collection fails, then an DKDataObjectNotFoundException will be thrown. If the retrieval of at least one of the the DDO's in the collection succeeds, then the DDO's that cannot be retrieved will be marked as FAIL in the last_operation property of DDO. This property contains a DKNVPair with (name,value) pair such as ("Retrieve","Success").
For performance reasons, retrieve options related to content retrieval are ignored in retrieve methods that accept collections of DDO's. This behavior is equivalent to content retrieve option DK_CM_CONTENT_NO. Use retrieve methods that accept a single DDO to retrieve content.
Specified by:
retrieveObjects in interface dkDatastore
Overrides:
retrieveObjects in class dkAbstractDatastore
Parameters:
ddo - collection of DDO's to be retrieved from this datastore
options - DKNVPair[] options for retrieve
See retrieveObject(dkDataObject, DKNVPair[]) method for more details
Throws:
DKException - if a problem is encountered
java.lang.Exception - if a problem is encountered

updateObject

public void updateObject(dkDataObject ddo)
                  throws DKException,
                         java.lang.Exception
Updates this DDO in the persistent store. A new version of this item is created if the versioning flag in the item type definition for this item is set to on. The default behaviour of updateObject is not to check in the item after update.
Specified by:
updateObject in interface dkDatastore
Overrides:
updateObject in class dkAbstractDatastore
Parameters:
ddo - - the DDO to be updated.
Throws:
DKException - if a problem is encountered.

updateObject

public void updateObject(dkDataObject ddo,
                         int option)
                  throws DKException,
                         java.lang.Exception
Updates this DDO in the persistent store. A new version of this item is created if the versioning flag in the item type definition for this item is set to on. The default behaviour of updateObject is not to check in the item after update.
Specified by:
updateObject in interface dkDatastore
Overrides:
updateObject in class dkAbstractDatastore
Parameters:
ddo - - the item DDO to be updated in this datastore.
option - - The update options. Valid values are: DK_CM_CHECKIN : check the item in after update. The default is not to check in the item. DK_CM_VERSION_LATEST: update the latest version. DK_CM_VERSION_NEW: create a new version of this item. This is applicable only if the version control on the item type is set to version the item or to application controlled. If this is not the case, the item is updated and no error is returned but a new version is not created.
Throws:
DKException - if a problem is encountered
java.lang.Exception - if a problem is encountered

deleteObject

public void deleteObject(dkDataObject ddo)
                  throws DKException,
                         java.lang.Exception
Deletes the specified DDO from the persistent datastore.
Specified by:
deleteObject in interface dkDatastore
Overrides:
deleteObject in class dkAbstractDatastore
Parameters:
ddo - - DDO to be deleted from this datastore.
Throws:
DKException - if a problem is encountered.

deleteObject

public void deleteObject(dkDataObject ddo,
                         int option)
                  throws DKException,
                         java.lang.Exception
Deletes this DDO from the persistent store.
Specified by:
deleteObject in interface dkDatastore
Overrides:
deleteObject in class dkAbstractDatastore
Parameters:
ddo - the DDO to be deleted from this datastore.
option - delete option, the default is 0 (zero) which will perform a regular delete
Throws:
DKException - if a problem is encountered.
Supported Delete Options
  • DKConstantICM.DK_ICM_DELETE_ALL_VERSIONS - Delete all versions of the item

deleteObjects

public void deleteObjects(dkCollection ddoCollection)
                   throws DKException,
                          java.lang.Exception
Deletes a collection of DDOs from the persistent store.
Specified by:
deleteObjects in interface dkDatastore
Overrides:
deleteObjects in class dkAbstractDatastore
Parameters:
ddoCollectoin - - the collection of DDOs representing items to be deleted from this persistent store.
Throws:
DKException - if a problem is encountered.

deleteObjects

public void deleteObjects(dkCollection ddoCollection,
                          int option)
                   throws DKException,
                          java.lang.Exception
Deletes DDOs from this datastore.
Specified by:
deleteObjects in interface dkDatastore
Overrides:
deleteObjects in class dkAbstractDatastore
Parameters:
ddoCollectoin - the DDO collection to be deleted from this datastore.
option - delete option, the default is 0 (zero) which will perform a regular delete
Throws:
DKException - if a problem is encountered.
Supported Delete Options
  • DKConstantICM.DK_ICM_DELETE_ALL_VERSIONS - Delete all versions of the item

moveObject

public void moveObject(dkDataObject ddo,
                       java.lang.String destinationItemType)
                throws DKException,
                       java.lang.Exception
Moves the data-object from the current item type to another item type in this datastore. After the move, the data object will be relocated into the destination item type but will retain the same itemId. The default is not to check-in the item. You can only move a root component.
WARNING:
Specified by:
moveObject in interface dkDatastoreIntICM
Parameters:
ddo - the data-object to be moved
destinationItemType - the destination item type to move this data-object to.
Throws:
DKException - if a problem is encountered
java.lang.Exception - if a problem is encountered
See Also:
moveObject(dkDataObject, dkDataObject, int)

moveObject

public void moveObject(dkDataObject sourceDDO,
                       dkDataObject destinationDDO,
                       int options)
                throws DKException,
                       java.lang.Exception
Moves the data-object from the current item type to another in this datastore. The destination data-object has the format of the destination item type. It contains some additional attributes which do not exist in the source item type that you want to set in the destination item. The destination data-object is necessary when such attributes are not nullable, thus requiring values to be set. The relevant values from source data object will be copied over into the destination data-object. This process would filter out attributes and other data not relevant to the destination item type. You should create the destination DDO using dkDatastore.createDDO() method and populate it as necessary. After the move, the destination item will be created in the destination item type having the same itemId as the source item. You can only move a root component.
WARNING:
Specified by:
moveObject in interface dkDatastoreIntICM
Parameters:
sourceDDO - the data-object to be moved
destinationDDO - the template of destination data-object
options - valid options are
  • DK_CM_CHECKIN : the default is not to checkin the item.
  • DK_CM_VERSION_NEW : the default is not to create a new version. This option has some limitations.
  • DK_CM_KEEP_IN_AUTOFOLDER : the default is to remove from the current auto folder.
Throws:
DKException - if a problem is encountered
java.lang.Exception - if a problem is encountered
See Also:
moveObject(dkDataObject, java.lang.String)

commit

public void commit()
            throws DKException,
                   java.lang.Exception
Commits a datastore transaction.
Specified by:
commit in interface dkDatastore
Overrides:
commit in class dkAbstractDatastore
Throws:
DKException - if a problem is encountered.

rollback

public void rollback()
              throws DKException,
                     java.lang.Exception
Rollbacks a datastore transaction.
Specified by:
rollback in interface dkDatastore
Overrides:
rollback in class dkAbstractDatastore
Throws:
DKException - if a problem is encountered.

isConnected

public boolean isConnected()
                    throws java.lang.Exception
Checks to see if the datastore is connected.
Specified by:
isConnected in interface dkDatastore
Overrides:
isConnected in class dkAbstractDatastore
Returns:
true, if connected.

datastoreName

public java.lang.String datastoreName()
                               throws java.lang.Exception
Gets the name of this datastore object. Usually this returns the server name for the datastore.
Specified by:
datastoreName in interface dkDatastore
Overrides:
datastoreName in class dkAbstractDatastore
Returns:
datastore name.

datastoreType

public java.lang.String datastoreType()
                               throws java.lang.Exception
Gets the datastore type for this datastore.
Specified by:
datastoreType in interface dkDatastore
Overrides:
datastoreType in class dkAbstractDatastore
Returns:
datastore type. For DKDatastoreICM, the datastore type is DK_ICM_DSTYPE.

connection

public DKHandle connection()
                    throws java.lang.Exception
Gets the connection handle for this datastore.
Specified by:
connection in interface dkDatastore
Overrides:
connection in class dkAbstractDatastore
Returns:
connection handle.

handle

public DKHandle handle(java.lang.String type)
                throws java.lang.Exception
Gets a datastore handle.
Specified by:
handle in interface dkDatastore
Overrides:
handle in class dkAbstractDatastore
Parameters:
type - type of datastore handle wanted. Hande Types
DK_ICM_CONNECT_HANDLE
Returns:
a datastore handle.

userName

public java.lang.String userName()
                          throws java.lang.Exception
Gets the user name for this datastore.
Specified by:
userName in interface dkDatastore
Overrides:
userName in class dkAbstractDatastore
Returns:
user name.

listDataSources

public dkCollection listDataSources()
                             throws DKException,
                                    java.lang.Exception
Lists the available datastores that can be used to connect with.
Specified by:
listDataSources in interface dkDatastore
Overrides:
listDataSources in class dkAbstractDatastore
Returns:
a collection of dkServerDef objects.
Throws:
DKException - if a problem is encountered.

listDataSourceNames

public java.lang.String[] listDataSourceNames()
                                       throws DKException,
                                              java.lang.Exception
Lists the names of the available datastores that can be used to connect with.
Specified by:
listDataSourceNames in interface dkDatastore
Overrides:
listDataSourceNames in class dkAbstractDatastore
Returns:
an array of server names.
Throws:
DKException - if a problem is encountered.

listEntities

public dkCollection listEntities()
                          throws DKException,
                                 java.lang.Exception
Gets a list of entities from persistent store.
Specified by:
listEntities in interface dkDatastore
Overrides:
listEntities in class dkAbstractDatastore
Returns:
a collection of dkEntityDef objects.
Throws:
DKException - if an error occurs.

listEntityNames

public java.lang.String[] listEntityNames()
                                   throws DKException,
                                          java.lang.Exception
Gets a list of entity names from persistent store.
Specified by:
listEntityNames in interface dkDatastore
Overrides:
listEntityNames in class dkAbstractDatastore
Returns:
an array of entity names.
Throws:
DKException - if an error occurs.

listEntityAttrs

public dkCollection listEntityAttrs(java.lang.String entityName)
                             throws DKException,
                                    java.lang.Exception
Gets a list of attributes for a given entity name.
Specified by:
listEntityAttrs in interface dkDatastore
Overrides:
listEntityAttrs in class dkAbstractDatastore
Parameters:
entityName - the name of the entity that owns the attributes.
Returns:
a dkCollection of dkAttrDef objects.
Throws:
DKException - if the entity name does not exist.

listEntityAttrNames

public java.lang.String[] listEntityAttrNames(java.lang.String entityName)
                                       throws DKException,
                                              java.lang.Exception
Gets a list of attribute names for a given entity name.
Specified by:
listEntityAttrNames in interface dkDatastore
Overrides:
listEntityAttrNames in class dkAbstractDatastore
Parameters:
entityName - name of the entity that owns the attributes.
Returns:
an array of attribute names.
Throws:
DKException - if the entity name does not exist.

datastoreDef

public dkDatastoreDef datastoreDef()
                            throws DKException,
                                   java.lang.Exception
Gets the datastore definition object.
Specified by:
datastoreDef in interface dkDatastore
Overrides:
datastoreDef in class dkAbstractDatastore
Returns:
the DKDatastoreDefICM object. Each call to this method will return the same object.
Throws:
DKException - if a problem is encountered.
See Also:
DKDatastoreDefICM

registerMapping

public java.lang.String registerMapping(DKNVPair sourceMap)
                                 throws DKException,
                                        java.lang.Exception
Registers mapping information to this datastore.
Specified by:
registerMapping in interface dkDatastore
Overrides:
registerMapping in class dkAbstractDatastore
Parameters:
sourceMap - - source name and mapping information. The name part of the NVPair specifies the source of mapping information. A string literal "SCHEMA" indicates that the mapping informaiton is provided in the value part in form of schema mapping object.
Returns:
the mapping name for the mapping information.
Throws:
DKException - if a problem is encountered.

unRegisterMapping

public void unRegisterMapping(java.lang.String mappingName)
                       throws DKException,
                              java.lang.Exception
Unregisters mapping information from this datastore.
Specified by:
unRegisterMapping in interface dkDatastore
Overrides:
unRegisterMapping in class dkAbstractDatastore
Parameters:
mappingName - - the name of the mapping information.
Throws:
DKException - if a problem is encountered.

listMappingNames

public java.lang.String[] listMappingNames()
                                    throws DKException,
                                           java.lang.Exception
Gets the list of registered mapping information from this datastore.
Specified by:
listMappingNames in interface dkDatastore
Overrides:
listMappingNames in class dkAbstractDatastore
Returns:
an array of the names of the registered mapping information.
Throws:
DKException - if a problem is encountered.

getMapping

public dkSchemaMapping getMapping(java.lang.String mappingName)
                           throws DKException,
                                  java.lang.Exception
Gets the specified schema mapping information registered in this datastore.
Specified by:
getMapping in interface dkDatastore
Overrides:
getMapping in class dkAbstractDatastore
Parameters:
mappingName - - the name of the schema mapping information.
Returns:
the schema mapping object.
Throws:
DKException - if a problem is encountered.

getExtension

public dkExtension getExtension(java.lang.String extensionName)
                         throws DKException,
                                java.lang.Exception
Gets the specified extension object from this datastore.
Specified by:
getExtension in interface dkDatastore
Overrides:
getExtension in class dkAbstractDatastore
Parameters:
extensionName - name of the extension object.
Returns:
an extension object.
Throws:
DKException - if a problem is encountered.
See Also:
extension methods]

addExtension

public void addExtension(java.lang.String extensionName,
                         dkExtension extensionObj)
                  throws DKException,
                         java.lang.Exception
Adds a new extension object to this datastore. The extension object is implemented based on the Extension Object pattern described in "Pattern Languages for Program Design, vol. 3, R. Martin, et al (eds), Addison Wesley, 1998".
Specified by:
addExtension in interface dkDatastore
Overrides:
addExtension in class dkAbstractDatastore
Parameters:
extensionName - - the name of new extension object.
extensionObj - - the extension object to be added.
Throws:
DKException - if a problem is encountered.
See Also:
extension methods]

removeExtension

public void removeExtension(java.lang.String extensionName)
                     throws DKException,
                            java.lang.Exception
Removes an existing extension object from this datastore.
Specified by:
removeExtension in interface dkDatastore
Overrides:
removeExtension in class dkAbstractDatastore
Parameters:
extensionName - - name of extension object to be removed.
Throws:
DKException - if a problem is encountered.
See Also:
extension methods]

listExtensionNames

public java.lang.String[] listExtensionNames()
                                      throws DKException,
                                             java.lang.Exception
Gets the list of extension objects' names available in this datastore.
Specified by:
listExtensionNames in interface dkDatastore
Overrides:
listExtensionNames in class dkAbstractDatastore
Returns:
an array of extension objects' names.
Throws:
DKException - if a problem is encountered.
See Also:
extension methods]

createDDO

public DKDDO createDDO(java.lang.String objectType,
                       int flags)
                throws DKException,
                       java.lang.Exception
Creates a new DDO with object type, properties and attributes set according to the definition of the corresponding item type in this datastore. The flag indicates additional properties that need to be set. This is the official and recommended way to create Items. This method will create a new root Item of the specified item type. This method will allow the system to automatically setup important information in the DKDDO structure, which allows for easier and greater functionality, such as Resources, CM Document Model, and Folders. The DDO returned will have the appropriate properties and attributes setup to fit the corresponding item type definition.

Resource Items
The Item Type Definition determines what type of DDO is created. If it is a resource, the correct XDO will be returned, depending on the XDO Class specified in the Item Type Definition. The returned DDO may be cast to the correct structure, since will be setup correctly according to the Item Type Definition. For more information, please refer to the "Returns" documentation.

Item Property Types
An Item or DDO must have a generic "type" property associated with it. This generic type of the DDO is Document, Folder, or Item. When creating Items, the Item Property must be specified as the second parameter of the Datastore's createDDO function.

The value is stored in the DDO's property named, "DK_CM_PROPERTY_ITEM_TYPE", which should not be confused with the overall Item Type Definition that describes this the structure of this Item. "PROPERTY_ITEM_TYPE" refers to the "Item Property", not the Item Type Definition, something specific to the ICM connector.

    Available Item Property Types:

    Item Property   Constant        Definition
    -------------   --------------  ------------------------------------------------------
    Document        DK_CM_DOCUMENT  Item will represent a document or stored data.  The
                                    information contained in this item will may form a
                                    document.  This can be considered a "Common Document"
                                    since it does not rigidly mean an implementation of a
                                    specific document model.
    ......................................................................................
    Folder          DK_CM_FOLDER    Item will represent an object somehow containing or
                                    referencing contents / objects.  This can be
                                    considered a "Common Folder" since it does not rigidly
                                    mean an implementation of a specific document model.
                                    In the ICM Connector, it will automatically create an
                                    empty DKFolder collection which can hold contents.
    ......................................................................................
    Item (Default)  DK_CM_ITEM      Generic Item.  This is the Item Property Type for all
                                    Semantic Types that are not Document or Folder.
    --------------------------------------------------------------------------------------
    Note:  Constants available in com.ibm.mm.sdk.common.DKConstant.
  
Semantic Type
When creating Items, a semantic type can be specified as the second parameter of the Datastore's createDDO function. A semantic type in general is a metaphor for an item. It gives it an enforceable characteristic for basic operations. Where applicable, semantic types are enforced within EIP OOAPI and can be enforced externally as customers see fit.

The value is stored in the DDO's property DKConstantICM.DK_ICM_PROPERTY_SEMANTIC_TYPE, which in many cases may contain the same value as the Item Property Type.

    Available Semantic Types:

    Semantic Type   Constant          Definition
    -------------   ----------------  ------------------------------------------------
    <Any>           <User Specified>  CreateDDO will assign any value specified to
                                      the semantic type value.  Since user-programs
                                      may enforce semantics as they wish, no values
                                      will be disallowed, except for Item Type
                                      Definitions of classification Document Model.
    ..................................................................................
    Document        DK_ICM_SEMANTIC_  Item will represent a document or stored data.
                    TYPE_DOCUMENT     The information contained in this item will may
                                      form a document.  This can be considered a
                                      "Common Document" since it does not rigidly
                                      mean an implementation of a specific document
                                      model.
    ..................................................................................
    Folder          DK_ICM_SEMANTIC_  Item will represent an object somehow
                    TYPE_FOLDER       containing or referencing contents / objects.
                                      This can be considered a "Common Folder" since
                                      it does not rigidly mean an implementation of a
                                      specific document model.  In the ICM Connector,
                                      it will automatically create an empty DKFolder
                                      collection which can hold contents.
    ..................................................................................
    Container       DK_ICM_SEMANTIC_  Item will represent a container or generic item.
                    TYPE_CONTAINER    This is equivalent to the Item Property Type of
                                      DK_CM_ITEM.
    ..................................................................................
    Annotation      DK_ICM_SEMANTIC_  CM Document Model Annotation Part.  For Items
                    TYPE_ANNOTATION   created of an Item Type with a classification
                                      declaring CM Document Model, parts may be
                                      created and added to make up a document.
    ..................................................................................
    History         DK_ICM_SEMANTIC_  CM Document Model History Part.  For Items
                    TYPE_HISTORY      created of an Item Type with a classification
                                      declaring CM Document Model, parts may be
                                      created and added to make up a document.
    ..................................................................................
    Note            DK_ICM_SEMANTIC_  CM Document Model Note Part.  For Items
                    TYPE_NOTE         created of an Item Type with a classification
                                      declaring CM Document Model, parts may be
                                      created and added to make up a document.
    ..................................................................................
    Base            DK_ICM_SEMANTIC_  CM Document Model Base Part.  For Items
                    TYPE_BASE         created of an Item Type with a classification
                                      declaring CM Document Model, parts may be
                                      created and added to make up a document.
    ..................................................................................
    <User Defined>  <User Defined>    A User Defined Semantic Type.  Please refer to
                                      the Semantic Type Samples for more information.
    ----------------------------------------------------------------------------------
    Note:  Constants available in com.ibm.mm.sdk.common.DKConstantICM.
 
Specified by:
createDDO in interface dkDatastore
Overrides:
createDDO in class dkAbstractDatastore
Parameters:
objectType - - the name of the Item Type defined in this datastore. The first parameter takes the name of the Item Type that defines the entire Item. This may also be considered the Root Item Type, since the DDO returned is the Root Component DDO. The Item Type definition should be defined at design-time in this datastore through the System Administration Client or API.

flags - - indicates additional properties of the DDO. This is the Item Property / Semantic Type. The second parameter determines the Item Property & Semantic Type of the DDO, such as Document, Folder, Item, or User-Defined.
Returns:
The DDO returned is a new DKDDO of the Root Component. If the Item Type defines extended functionality such as XDO Resource functionality, the returned DKDDO is the correct derived descendent from DKDDO, such as DKLobICM, DKTextICM, DKImageICM, DKStreamICM, and DKVideoStreamICM and may be cast to those types.
Throws:
DKException - if errors are detected such as the following:
  • The Item Type name given does not exist in this datastore.
  • The Semantic Type specified is incompatible with the Item Type specified.
  • Child Component Type name specified instead of a Root Item Type name.
  • Other Usage Errors
See Also:
createDDO(java.lang.String pidString), createChildDDO(java.lang.String, java.lang.String)

createDDO

public DKDDO createDDO(java.lang.String pidString)
                throws DKException,
                       DKUsageError,
                       java.lang.Exception
Creates a new DDO with object type, properties and attributes set according to the corresponding definition of the item type in this datastore.
Specified by:
createDDO in interface dkDatastoreIntICM
Parameters:
pidString - - a string created from DKPidICM.pidString() method.
Returns:
a new DDO of the given object type with all the properties and attributes set, so that the user only need to set the attribute values. The attribute values are initialized to null.
Throws:
DKException - if a problem is encountered.
DKUsageError - if a problem is encountered.
java.lang.Exception - if a problem is encountered.
See Also:
createDDO methods]

createDDO

public DKDDO createDDO(DKPidICM pid,
                       java.lang.String[] fedAttributeList)
                throws DKException,
                       DKUsageError,
                       java.lang.Exception
Creates a new DDO with object type, properties and attributes set based on the suplied Pid and attribute list.
Parameters:
pid - - a valid instance of DKPidICM object.
fedAttributeList - - an array of attribute strings
Returns:
a new DDO of the given object type with all the properties and attributes set, so that the user only need to set the attribute values. The attribute values are initialized to null.
Throws:
DKException - if a problem is encountered.
DKUsageError - if a problem is encountered.
java.lang.Exception - if a problem is encountered.
See Also:
createDDO methods]

createDDO

public DKDDO createDDO(DKPidICM pid)
                throws DKException,
                       DKUsageError,
                       java.lang.Exception
Creates a new DDO with object type, properties and attributes set according to the corresponding definition of the item type in this datastore.
Specified by:
createDDO in interface dkDatastoreIntICM
Parameters:
pid - a valid instance of DKPidICM
Returns:
a new DDO of the given object type with all the properties and attributes set, so that the user only need to set the attribute values. The attribute values are initialized to null.
Throws:
DKException - if a problem is encountered.
DKUsageError - if a problem is encountered.
java.lang.Exception - if a problem is encountered.
See Also:
createDDO methods]

createChildDDO

public DKDDO createChildDDO(java.lang.String objectType,
                            java.lang.String componentName)
                     throws DKException,
                            java.lang.Exception
Creates a child DDO of the given component name under the specified root component. The child component can be located anywhere under the root component, it does not have to be a direct child of the root. The created DDO will have all properties and attributes of the child component already set up, so that the user only need to set the attribute values. The attribute values are initialized to null.
Specified by:
createChildDDO in interface dkDatastoreIntICM
Parameters:
objectType - - the name of the item type (root).
componentName - - the name of the child component to be created.
Returns:
a DDO object representing the child component.
Throws:
DKException - if a problem is encountered.
java.lang.Exception - if a problem is encountered.
See Also:
createDDO methods above]

destroy

public void destroy()
             throws DKException,
                    java.lang.Exception
Destroys the datastore object. This method performs the datastore cleanup if needed.
Specified by:
destroy in interface dkDatastore
Overrides:
destroy in class dkAbstractDatastore
Throws:
DKException - if a problem is encountered.

startTransaction

public void startTransaction()
                      throws DKException,
                             java.lang.Exception
Starts an explicit transaction. Youd need to either call commit() or rollback() to end the transaction and to release the resources. You cannot call startTransaction() twice without calling commit() or rollback() in between.
Specified by:
startTransaction in interface dkDatastoreIntICM
Overrides:
startTransaction in class dkAbstractDatastore
Throws:
DKException - if a problem is encountered.

checkIn

public void checkIn(dkDataObject item)
             throws DKException,
                    java.lang.Exception
Checks in an item previously checked out from the datastore. Check-in releases exclusive updating privileges to this item.
Specified by:
checkIn in interface dkDatastoreIntICM
Parameters:
item - the item to checked in.
Throws:
DKException - if a problem is encountered.

checkOut

public void checkOut(dkDataObject item)
              throws DKException,
                     java.lang.Exception
Checks out an item from the datastore. The current user will have exclusive update privileges to the item. All other users are allowed read access only, until the item is checked back in.
Specified by:
checkOut in interface dkDatastoreIntICM
Parameters:
item - the item to checked-out.
Throws:
DKException - if a problem is encountered.

writeEvent

public void writeEvent(DKEventDefICM aEvent)
                throws DKException,
                       java.lang.Exception
Writes this event information to the persistent event log.
Parameters:
aEvent - a DKEventDefICM object to be written to the event log.
Throws:
DKException - if a problem is encountered.

listEvents

public dkCollection listEvents(java.lang.String itemId,
                               short maxResults)
                        throws DKException,
                               java.lang.Exception
Lists all events related to the given item id. Returns a collection of DKEventDefICM objects.
Parameters:
itemId - an item id .
maxResults - the maxium number of DKEventDefICM objects to be returned in the collection.
Throws:
DKException - if a problem is encountered.

listAdminEvents

public dkCollection listAdminEvents(short maxResults)
                             throws DKException,
                                    java.lang.Exception
Lists all events related to System Administration functions.
Parameters:
maxResults - the maxium number of events to retrieve. 0 means no limits.
Returns:
Returns a collection of DKEventDefICM objects.

retrieveEvent

public dkCollection retrieveEvent(int eventCode,
                                  short maxResults)
                           throws DKException,
                                  java.lang.Exception
Retrieves events information for the given event code from the persistent event log.
Parameters:
eventCode - the given event code to retrieve the DKEventDefICM object.
Returns:
Returns a collection of DKEventDefICM objects with the information

changePassword

public void changePassword(java.lang.String userId,
                           java.lang.String oldPwd,
                           java.lang.String newPwd)
                    throws DKException,
                           java.lang.Exception
Description copied from interface: dkDatastore
Allows a user to change password if authorized

Note:DKUsageError exception thrown if method is not implemented

Specified by:
changePassword in interface dkDatastore
Overrides:
changePassword in class dkAbstractDatastore
Following copied from interface: com.ibm.mm.sdk.common.dkDatastore
Parameters:
userId - - userid
oldPwd - - old password
newPwd - - new password
See Also:
dkUserManagement.changePassword( java.lang.String, java.lang.String,java.lang.String)

retrieveFormOverlay

public dkXDO retrieveFormOverlay(java.lang.String name)
                          throws DKException,
                                 java.lang.Exception
Retrieves the form overlay object.
Parameters:
name - the name of the form overlay object.
Returns:
the form overlay XDO object, null if the form overlay does not exist..
Throws:
DKException - if an error occurs.

textSearchEnabled

public boolean textSearchEnabled()
                          throws java.lang.Exception
Returns whether text search is enabled for this datastore.
Specified by:
textSearchEnabled in interface dkDatastoreIntICM
Returns:
true if text search is enabled, false otherwise

LDAPEnabled

public boolean LDAPEnabled()
                    throws java.lang.Exception
Returns whether LDAP is enabled for this datastore.
Specified by:
LDAPEnabled in interface dkDatastoreIntICM
Returns:
true if LDAP is enabled.

adminDomainEnabled

public boolean adminDomainEnabled()
                           throws java.lang.Exception
Returns whether administration domain is enabled for this datastore.
Specified by:
adminDomainEnabled in interface dkDatastoreIntICM
Returns:
true if admin domain is enabled.

platform

public short platform()
Returns the platform on which the server for this datastore. Possible values for this are:
Specified by:
platform in interface dkDatastoreIntICM
Returns:
Short specifying the platform of the server.

schemaName

public java.lang.String schemaName()
                            throws DKException,
                                   java.lang.Exception
Returns the schema Name
Specified by:
schemaName in interface dkDatastoreIntICM
Returns:
schema name of this Content Manager server.

EIP Java APIs

(c) Copyright International Business Machines Corporation 1996, 2002. IBM Corp. All rights reserved.