DKDatastoreICM instances represent a connected session to an IBM® Content Manager server and is the focal point through which persistent operations take place within a session. For example, the DKDatastoreICM provides connection services, data persistence (create, update, retrieve, and delete content), transaction support, query/search, and more.
Multithreading
A single instance of DKDatastoreICM does not support multi-threading with concurrent access from multiple threads in a multi-threaded program. Multi-threaded applications must either use separate connected DKDatastoreICM instances (recommended) (one datastore instance per thread) or synchronize concurrent access to the datastore instance within your application.
Since: Version 8
class DKEXPORT DKDatastoreICM : public dkDatastore
{
public:
DKDatastoreICM();
DKDatastoreICM(const char* configuration);
virtual ~DKDatastoreICM();
virtual void connect (const char* datastore_name,
const char* user_name = "",
const char* authentication = "",
const char* connect_string = "");
virtual void disconnect();
virtual void getOption(long option, DKAny& value);
virtual void setOption(long option, DKAny& value);
virtual DKAny evaluate (const char* command,
const short commandLangType =
DK_CM_XQPE_QL_TYPE,
const DKNVPair* parms = 0);
virtual DKAny evaluate (DKCQExpr* cqe);//Deprecated
virtual dkResultSetCursor* execute (const char* command,
const short commandLangType =
DK_CM_XQPE_QL_TYPE,
const DKNVPair* parms = 0);
virtual dkResultSetCursor* execute (DKCQExpr* cqe);//Deprecated
virtual void executeWithCallback (const char* command,
const short commandLangType,
const DKNVPair* parms,
dkCallback* callbackObj);
virtual void executeWithCallback (DKCQExpr* cqe,
dkCallback* callbackObj);//Deprecated
virtual void validate (const char* xqpe_query);
virtual void addObject(dkDataObject* dataobj);
virtual void addObject(dkDataObject* dataobj, long option);
virtual void addObjects(dkCollection * ddoCollection);
virtual void addObjects(dkCollection * ddoCollection, long option);
virtual void addPIDtoRecordIDMappings(dkCollection* coll);
virtual void deleteObject(dkDataObject* dataobj, long option);
virtual void deleteObject(dkDataObject* dataobj);
virtual void deleteObjects(dkCollection *ddoColl, long option);
virtual void deleteObjects(dkCollection *ddoColl);
virtual void deletePIDtoRecordIDMappings(dkCollection* coll);
virtual void retrieveObject(dkDataObject* dataobj);//Deprecated
virtual void retrieveObject(dkDataObject* dataobj,long option);//Deprecated
virtual void retrieveObject(dkDataObject* dataobj, const DKNVPair* parms, long arraySize);
virtual void retrieveObjects( dkCollection *ddoColl);//Deprecated
virtual void retrieveObjects( dkCollection *ddoColl, int option);//Deprecated
virtual void retrieveObjects( dkCollection *ddoColl, const DKNVPair* parms, long arraySize);
virtual void updateObject(dkDataObject* dataobj);
virtual void updateObject(dkDataObject* dataobj, long option);
virtual void commit ();
virtual void rollback ();
virtual DKBoolean isConnected();
virtual DKHandle* connection();
virtual DKHandle* handle(const char* type);
virtual dkCollection* listDataSources();
virtual DKString* listDataSourceNames(long& arrarySize);
virtual dkCollection* listEntities();
virtual DKString* listEntityNames(long& arraySize);
virtual dkCollection* listEntityAttrs(const char* entityName);
virtual DKString* listEntityAttrNames(const char* entityName,
long& arraySize);
virtual dkDatastoreDef* datastoreDef();
virtual DKString registerMapping(DKNVPair* sourceMap);
virtual void unRegisterMapping(const char* mappingName);
virtual DKString* listMappingNames(long& arraySize);
virtual dkCollection* listPIDtoRecordIDMappings(DKPIDICM * pid);
virtual dkSchemaMapping* getMapping(const char* mappingName);
virtual dkExtension* getExtension(const char* extensionName);
virtual void addExtension(const char* extensionName,
dkExtension* extensionObj);
virtual void removeExtension(const char* extensionName);
virtual DKString* listExtensionNames(long& arraySize);
virtual DKDDO* createDDO(const char* itemTypeViewName, long semanticType);
virtual DKDDO* createDDO(DKString pidString);//Deprecated
virtual DKDDO* createDDO(DKPidICM * pid);//Deprecated
virtual DKDDO* createDDO(DKPidICM* pid, bool initializeMetadataStructures);//Deprecated
virtual DKDDO* createDDO(DKPidICM* pid, DKString *fedAttrList, long numOfFedAttrs);//Deprecated
virtual DKDDO* createDDO(const char* itemTypeViewName, long semanticType, bool initializeMetadataStructures);//Deprecated
virtual DKDDO* createChildDDO(DKString itemTypeComponentViewName, DKString childTypeViewName);
virtual DKDDO* createDDOFromPID(DKPidICM* pid);
virtual DKDDO* createDDOFromPID(DKString pidString);
virtual void checkIn(dkDataObject* item);
virtual void checkOut(dkDataObject* item);
virtual void clearCache(int option);
virtual void unlockCheckedOut(dkDataObject* dataObject);
virtual void startTransaction();
virtual void validateConnection()
virtual DKBoolean adminDomainEnabled();
virtual DKBoolean informationMiningEnabled();
virtual DKBoolean isUserCacheEnabled();
virtual DKBoolean LDAPEnabled();
virtual short platform();
virtual DKBoolean textSearchEnabled();
virtual DKBoolean workflowEnabled();
virtual DKBoolean isCheckedOut(dkDataObject* dobj);
virtual DKString checkedOutUserid(dkDataObject* dobj);
virtual DKString schemaName();
virtual dkCollection* listEvents(const char* itemId, short maxResults);
virtual dkCollection* listAdminEvents(short maxResults);
virtual dkCollection* retrieveEvent(long eventCode);
virtual void writeEvent(DKEventDefICM* aEvent);
virtual string getAPIVersion();
virtual void moveObject(dkDataObject* sourceDDO, dkDataObject* destinationDDO, long options=0);
virtual void moveObject(dkDataObject* ddo, const char* destinationItemType);
virtual void dkXDO* retrieveFormOverlay(DKString name);
virtual void changePassword(const char* userId,const char* oldPwd,const char* newPwd);
virtual DKBoolean setLocaleAndCodePage(char * locale, char * codePage);
virtual void getLocaleAndCodePage(DKString & locale, DKString & codePage);
DKString getName(DKDDO* ddo);
DKDDO* getDefaultFolder();
DKDDO* getRootFolder();
};DKDatastoreICM()DKDatastoreICM(const char* configuration)virtual ~DKDatastoreICM()DKSequentialCollection seqColl = new DKSequentialCollection();
DKSequentialCollection seqColl = new DKSequentialCollection();
DKPidICM pid = new DKPidICM(pidString);
long recordId = 1111;
seqColl.addElement(new DKPIDRecordIDPair(pid,recordId););
dsICM.addPIDtoRecordIDMappings(seqColl);Parameters: coll - a dkCollection of DKPIDRecordIDPair objects.
Exceptionpublic void addPIDtoRecordIDMappings(dkCollection* coll)Deprecated.
Allows a user to change password if authorized.
Specified by: changePassword in class dkDatastore
Overrides: changePassword in class dkAbstractDatastore
Parameters: item - Root component DDO for the item to check in (unlock).
public void changePassword(String userId,String oldPwd,String newPwd) throws DKException, ExceptionException: DKException if a problem is encountered.
Establishes a connection to an IBM Content Manager Version 8 datastore.
Parameters:
Connect string used for connection. This is used to provide additional connection options. Valid connect_string name/value pairs separated by semi colons are:
Exception:DKException - if a problem is encountered.
virtual void connect (const char* datastore_name,
const char* user_name = "",
const char* authentication = "",
const char* connect_string = "");Disconnects from an IBM Content Manager datastore. If this object is not going to be used anymore, you must call the destroy() method to free up all resources.
Specified by: disconnect in class dkDatastore
Overrides: disconnect in class dkAbstractDatastore
virtual void disconnect();Exception:DKException - if a problem is encountered.
Gets a datastore option.
Specified by: getOption in class dkDatastore
Overrides: getOption in class dkAbstractDatastore
Parameters:
Enabled/disabled cache.
Values are: DK_CM_TRUE (default), DK_CM_FALSE
Enabled/disabled LAN cache.
Values are: DK_CM_TRUE (default), DK_CM_FALSE
virtual void getOption(long option, DKAny& value);Exception:DKException - if a problem is encountered.
Sets a datastore option.
Specified by: setOption in class dkDatastore
Overrides: setOption in class dkAbstractDatastore
Parameters:
virtual void setOption(long option, DKAny& value);Exception:DKException - if a problem is encountered.
Performs the requested query and returns once all results are populated as DDOs in a single, completed results collection and retrieved based on submitted retrieve options (or defaults). (The actual number of results can be limited through query options to avoid an excessively large collection or long response time.) Use execute() to iterate over a large number of results with an optimized cursor that intelligently retrieves data in blocks over time as the next results are requested. For information on constructing query strings, performing queries, and processing results, refer to the SSearchICM and SItemRetrievalICM API education samples, Application Programming Guide, and Multi-Item Retrieve detailed reference documentation and options.
Always Specify Retrieve Options
Query identifies the IDs of all component DDOs (root components, child components, and document parts) matching the submitted query and creates blank DDOs with completed PID information. Query itself does not retrieve meta-data or content. However, query can call multi-item retrieve on your behalf (and does so by default). When no retrieve options are supplied, for backward compatibility, query assumes default deprecated bitwise 'int' retrieve options selections (deprecated options are less optimal compared to new options and therefore should be avoided). Regardless of deprecation, default selections are very unlikely to be the most optimal choice for your application after considering performance implications and choosing retrieve requests wisely. You should always specify your own retrieve options with your own list of requests and exclusions for the best possible performance based on the detailed performance considerations documented in the DKRetrieveOptionsICM reference documentation. Additionally, submitting a DKRetrieveOptionsICM instance enables additional retrieve optimizations that are not available through default or deprecated bitwise option behavior and avoids using the deprecated bitwise options by default. See the retrieve options section of multi-item retrieve reference documentation.
Brief Example: See sample SSearchICM for more detailed examples and documentation.
// Given DKDatastoreICM instance as variable "dsICM".
String query = "/Journal/Journal_Article[(@Author=\"Smith\"] SORTBY (@Title)";
DKRetrieveOptionsICM dkRetrieveOptions = DKRetrieveOptionsICM.createInstance(dsICM);
dkRetrieveOptions.baseAttributes(true);
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,dkRetrieveOptions);
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());
while(iter.more()) {
DKDDO 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:Deprecated values: Note that some values accepted by this interface are now deprecated. See the queryOptionsDKNVPair in execute(String,short,DKNVPair[]) documentation.
Returns: a dkCollection of DKDDO instances (or subclass such as DKLobICM, DKTextICM, or DKImageICM depending on item type and XDO classifications) for root components, child components, or document parts found as the results of this query. Depending on retrieve options, the DDOs were submitted to multi-item retrieve on your behalf or are otherwise blank DDOs with completed PID information. For information on data structures for meta-data and content within retrieved DDOs, see DKRetrieveOptionsICM reference documentation.virtual DKAny evaluate(const char* query, short queryLanguageID
DKNVPair[] queryOptionsDKNVPair);Deprecated. Always construct queries using the recommended query language and always submit retrieve options (using DKRetrieveOptionsICM) for performance advantages and optimizations.
Use DKDatastoreICM::evaluate(String queryString, short queryLangID, DKNVPair[] queryOptions)
Evaluates a combined query expression cqe against this datastore and returns the results in a collection.
Deprecation details
This method is not advised or recommended for public use. This method is typically used indirectly by federated query calls submitted through a DKDatastoreFed session. Additional behaviors of this method are not documented, but can cause slightly different behavior than you might expect. Always construct a query string using the proper language.
Always specify retrieve options for optimal performance and control. Explained in detail in the retrieve options section of method retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions). Retrieve methods with no option parameter assume default deprecated bitwise 'int' retrieve options selections (which can vary depending on the method). Default selections are very unlikely to be the most optimal choice for your application after considering performance implications and choosing retrieve requests wisely.
Furthermore, all bitwise 'int' retrieve options are deprecated and not recommended (which are the assumed defaults of no-option signatures). Use DKRetrieveOptionsICM instances instead. DKRetrieveOptionsICM offers performance advantages and enables optimizations (see retrieve options section of method retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions). Methods and option values accepting int and integer option signatures as well as no-option signatures are deprecated. Use the equivalent method with the DKNVPair[] options parameter signature instead of the deprecated int, integer, or no-option signature for retrieve options and provide a valid DKRetrieveOptionsICM clearly indicating your intent.
Specified by: evaluate in interface dkDatastore
Overrides evaluate in class dkAbstractDatastore
Parameters: cqe - a combined query expression object
Returns: See DKDatastoreICM::evaluate(String queryString, short queryLangID, DKNVPair[] queryOptions)
virtual DKAny evaluate (DKCQExpr* cqe);Executes query string command against this datastore and returns a result set cursor object to provide access to the results.
Performs the requested query and returns an optimized cursor to results populated as DDOs. The cursor intelligently retrieves data in blocks over time as the next results are requested. A connection remains open while the cursor is open. Blocks of data are retrieved together in sets. Use evaluate() to obtain all results at once without the need for a separate open connection or to avoid multiple blocks of fetch and retrieve if all results are needed immediately.
For information on constructing query strings, performing queries, and processing results, refer to:
Always Specify Retrieve Options
Query identifies the IDs of all component DDOs (root components, child components, and document parts) matching the submitted query and creates blank DDOs with completed PID information. Query itself does not retrieve meta-data or content. However, query can call multi-item retrieve on your behalf (and does so by default). When no retrieve option is supplied, query assumes default deprecated bitwise 'int' retrieve options selections (deprecated options are non-optimal and should be avoided). Regardless of deprecation, default selections are very unlikely to be the most optimal choice for your application after considering performance implications and choosing retrieve requests wisely. You should always specify your own retrieve options with your own list of requests and exclusions for the best possible performance based on the detailed performance considerations documented in the DKRetrieveOptionsICM reference documentation. Additionally, submitting a DKRetrieveOptionsICM instance enables additional retrieve optimizations that are not available through default or deprecated bitwise option behavior and avoids using the deprecated bitwise options by default. See the retrieve options section of multi-item retrieve reference documentation.
Brief Example: See sample SSearchICM for more detailed examples and documentation.
// Given DKDatastoreICM instance as variable "dsICM".
String query = "/Journal[@NumPages > 50] SORTBY (@Title)";
DKRetrieveOptionsICM dkRetrieveOptions = DKRetrieveOptionsICM.createInstance(dsICM);
dkRetrieveOptions.baseAttributes(true);
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,dkRetrieveOptions);
options[2] = new DKNVPair(DKConstant.DK_CM_PARM_END, null);
// VERY IMPORTANT, be sure to ensure the cursor is closed even
// if an error occurs while you are iterating through the results.
// If an exception is thrown, remember "cursor" will be null.
dkResultSetCursor cursor = null;
try{
cursor = dsICM.execute(query,DKConstant.DK_CM_XQPE_QL_TYPE,options);
// Display results using a result set cursor.
while((ddo = cursor.fetchNext()) != null){
System.out.println(" - Item ID: " +
((DKPidICM)ddo.getPidObject()).getItemId() +
" (" + ddo.getPidObject().getObjectType() + ")");
}
}catch(DKException e){
... // Your error handling (see SConnectDisconnectICM sample)
}finally{
// VERY IMPORTANT STEP:
if(cursor!=null)
cursor.destroy(); // close & destroy cursor
}Parameters:
DKNVPair[] Details
[Strongly Recommended] You should always specify your own retrieve options with your own list of requests and exclusions for the best possible performance based on the detailed performance considerations documented in the DKRetrieveOptionsICM reference documentation. Additionally, submitting a DKRetrieveOptionsICM instance enables additional retrieve optimizations that are not available through default or deprecated bitwise option behavior and avoids using the deprecated bitwise options by default. See the retrieve options section of multi-item retrieve. See detailed DKRetrieveOptionsICM reference documentation (includes performance considerations).
You can perform an "IDONLY" (nothing selected to retrieve beyond the PID) query by submitting a DKRetrieveOptionsICM with all selections set to 'false' (initial values) to exclude all selections. Since query itself returns the PID information in DDOs and can call multi-item retrieve on your behalf, the fastest possible response time from query is to simply return without retrieving any meta-data or content. You can call multi-item retrieve or single-item retrieve on some or all DDOs at any time on your own once you have the DDOs. If you do not set retrieve options, this is not the default.
[Deprecated and not recommended]. Use DKRetrieveOptionsICM instances instead. DKRetrieveOptionsICM offers performance advantages and enables optimizations not available when using deprecated bitwise 'int' options. This setting accepts deprecated bitwise int option values in an Integer object. All bitwise 'int' retrieve options are deprecated and not recommended. For deprecated bitwise values, see DKDatastoreICM::retrieveObjects(dkCollection,int bitwiseRetrieveOptionsInt.
If no retrieve option (of any value type) is provided at all, the default retrieve option assumed is deprecated bitwise 'int' option DKConstant.DK_CM_CONTENT_ATTRONLY. However, it is always better to clearly indicate your intent with retrieve options.
[Deprecated and not recommended]. Use "Retrieve Options" (DKConstant.DK_CM_PARM_RETRIEVE = DKRetrieveOptionsICM instance) instead of "Content Options". Always use retrieve options and value type DKRetrieveOptionsICM. DKRetrieveOptionsICM offers performance advantages and enables optimizations not available when using deprecated bitwise 'int' retrieve options or "content options".
"Content Options" specify how much content is retrieved when results are returned from query. This option is ignored if any retrieve option (DKConstant.DK_CM_PARM_RETRIEVE) is specified, which takes precedent in all cases.
Content options are specified as String objects with the following supported values. The values are mapped to the bitwise 'int' retrieve options indicated. However, all bitwise 'int' retrieve options are deprecated and not recommended. For details on the mapped deprecated bitwise values, see DKDatastoreICM::retrieveObjects(dkCollection,int bitwiseRetrieveOptionsInt.
| Content Options | Bitwise 'int' Retrieve Options |
|---|---|
| (deprecated) "IDONLY" = | (deprecated) DKConstant.DK_CM_CONTENT_IDONLY |
| (deprecated) "ATTRONLY" = | (deprecated) DKConstant.DK_CM_CONTENT_ATTRONLY |
| deprecated) "NO" = | (deprecated) DKConstant.DK_CM_CONTENT_NO |
| (deprecated) "YES" = | (deprecated) DK_CM_CONTENT_ATTRONLY | DK_CM_CONTENT_CHILDREN | DK_CM_CONTENT_YES |
[Deprecated and not recommended]. Use integrated DKProjectionListICM with DKRetrieveOptionsICM::attributeFilters(DKProjectionListICM) instead for projection list and attribute filtering capabilities. Submit as part of retrieve options instance under integrated interface. Do not submit separate projection list requests or using the deprecated DKNVPair[] form of a projection list.
[Recommended] Specify a maximum number of results that you want as a non-negative integer formatted in a String. To specify no maximum number of results, specify value "0" (zero) (which is also the default if this option is not specified). No indication is provided to indicate whether or not there exist additional results beyond the maximum number requested. You cannot extend the results of an existing open cursor. However, if you sort your results by a unique attribute value (or perhaps based on ITEMID, you can issue another query with a condition on all returned values such that the value (such as ITEMID) is greater than the value contained in the last DDO in the set. This effectively allows you to resume where you left off.
options[0] = new DKNVPair(DKConstant.DK_CM_PARM_MAX_RESULTS, "50"); The integer value of this option indicates the required block size in which results are fetched and retrieved in the optimized cursor. For example, when the first result is accessed, this many actual results will be pre-fetched and retrieved (with multi-item retrieve) to minimuze number of individual fetch and retrieve operations while balancing how far ahead to read and pre-fetch. Then when the second result is accessed, the next pre-fetched result is returned without any additional server calls. When a request is made and no more readily available pre-fetched results exist for the existing pre-fetched block, the next block is pre-fetched.
A small pre-fetch value N allows for faster display of the first N results, but will increase the overall retrieval time for the whole result set. Retrieving all results in one block (effectively an evaluate() call) is the fastest overall time, but costs more time up front for the call to return and loads more DDOs concurrently in memory, which can be a scaling concern if you have a very large set of results.
If not specified, an unspecified default block size managed by the system is used which is typically reasonable for the majority of applications.
Returns
a dkResultSetCursor of DKDDO instances (or subclass such as DKLobICM, DKTextICM, or DKImageICM depending on item type and XDO classifications) for root components, child components, or document parts found as the results of this query. Depending on retrieve options, the DDOs were submitted to multi-item retrieve on your behalf or are otherwise blank DDOs with completed PID information. For information on data structures for meta-data and content within retrieved DDOs, see DKRetrieveOptionsICM reference documentation.
virtual dkResultSetCursor* execute(const char* query, short queryLanguageID, DKNVPair[] queryOptionsDKNVPair)Exception: DKException. Exceptions are reported if errors are detected. For some information on specific retrieve-related exceptions, see DKRetrieveOptionsICM documentation.
Gets the count of the number of results found by the specified query without the extra overhead of returing the list of individual results. Note that this count is only considered an estimate since it is only accurate at the exact instant it is called since the system is not frozen. If the same query is performed to obtain the individual results, the actual size of the results from that call can differ from the previous count call because the data might have changed on the server.
Most query options are not applicable to executeCount() and are ignored if submtted. The only option that is honored and affects the count are the following options:
Brief Example
// Given DKDatastoreICM instance as variable "dsICM".
String query = "/Journal/Journal_Article[(@Author=\"Smith\"] SORTBY (@Title)";
DKRetrieveOptionsICM dkRetrieveOptions = DKRetrieveOptionsICM.createInstance(dsICM);
DKNVPair options[] = new DKNVPair[2];
options[1] = new DKNVPair(DKConstant.DK_CM_PARM_RETRIEVE,dkRetrieveOptions);
options[2] = new DKNVPair(DKConstant.DK_CM_PARM_END, null);
// Get the count
long count = dsICM.executeCount(query,DKConstant.DK_CM_XQPE_QL_TYPE,options);
// Display results count.
System.out.println(" Number of Results: " + count);
Parameters:
Returns: the count of results that match the query string.
Exception: DKException. See DKDatastoreICM::execute(const char* queryString, short queryLangID, DKNVPair[] queryOptions)
Deprecated. Always construct queries using the recommended query language and always submit retrieve options (using DKRetrieveOptionsICM) for performance advantages and optimizations. Use DKDatastoreICM::execute(const char* queryString, short queryLangID, DKNVPair[] queryOptions)
Executes a combined query expression cqe against this datastore and returns a result set cursor object to provide access to the results.
Deprecation Details
First, this method is not advised or recommended for public use. This method is typically used indirectly by federated query calls submitted through a DKDatastoreFed session. Additional behaviors of this method are not documented, but can cause slightly different behavior than you might expect. Always construct a query string using the proper language.
Second, always specify retrieve options for optimal performance and control. Explained in detail in the "Retrieve Options (STRONGLY RECOMMENDED)" section of method DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions). Retrieve methods with no option parameter assume default deprecated bitwise 'int' retrieve options selections (which can vary depending on the method). Default selections are very unlikely to be the most optimal choice for your application after considering performance implications and choosing retrieve requests wisely.
Furthermore, all bitwise 'int' retrieve options are deprecated and not recommended (which are the assumed defaults of no-option signatures). Use DKRetrieveOptionsICM instances instead. DKRetrieveOptionsICM offers performance advantages and enables optimizations (see "Retrieve Options (STRONGLY RECOMMENDED)" section of method DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions). Methods and option values accepting int and Integer option signatures as well as no-option signatures are deprecated. Use the equivalent method with the DKNVPair[] options parameter signature instead of the deprecated int, Integer, or no-option signature for retrieve options and provide a valid DKRetrieveOptionsICM clearly indicating your intent.
Specified by: execute in interface dkDatastore
Overrides execute in class dkAbstractDatastore
Parameters: cqe - a combined query expression object
Returns: See DKDatastoreICM::execute(String queryString, short queryLangID, DKNVPair[] queryOptions)
virtual DKAny evaluate (DKCQExpr* cqe);virtual dkResultSetCursor* execute (DKCQExpr* cqe);Deprecated. Always construct queries using the recommended query language. Use DKDatastoreICM::executeCount(String queryString,short,DKNVPair[] queryOptions).
Gets the count of the number of results that a combined query expression (cqe) would produce if it were executed. This issues a count query to the datastore to get the number of results. Note that this count is only an estimate and only accurate at the exact instant it is called. When the same query is executed to get results, the size of the result set may differ from the count.
Deprecation Details
This method is not advised or recommended for public use. This method is typically used indirectly by federated query calls submitted through a DKDatastoreFed session. Additional behaviors of this method are not documented, but can cause slightly different behavior than you might expect. Always construct a query string using the proper language.
Parameters: cqe - a combined query expression object
Returns: Use DKDatastoreICM::executeCount(const char* queryString, short queryLangID, DKNVPair[] queryOptions).
Exception: DKException. Use DKDatastoreICM::executeCount(String queryString, short queryLangID, DKNVPair[] queryOptions).Asynchronously executes the specified query and requests that the results be reported to the specified callback object in blocks over time as they become available. This call will immediately return, likely before any results are available. In a separate thread, the API will make calls back to methods on your callback object instance that you supplied to this call.
The callback object is an instance of any object implementing the dkCallback interface. Typically this is a class you wrote, compiled, and created an instance to use for this call. Query will report results by calling methods on this object instance for every block of results.
See SSearchICM and SSearchCallbackObjectICM samples for more details and examples.
No Persistent Operations Allowed Within Callback Object
You cannot invoke any persistent operations or datastore operations from the callback object with the same datastore session associated with the DDOs in the results returned since it is the same connection currently in use for processing the remaining query results for your object. You should not perform any persistent operations in the same thread used to call your callback object asynchronously. For example, within the callback object, you cannot list item type definitions, create new items, update existing items, delete items, or retrieve items. You can display the results as long as this does not require datastore operations. However, you can issue persistent calls within the callback object as soon as the query completes (indicated by the parameter isDone with value 'true' specified to your implementation of dkCallback::dataCallback(dkCollection ddoList, boolean isDone)).
If you want to stop receiving additional results, return 'true' to indicate a cancel request when the server calls your implementation of boolean dkCallback::dataCallback(dkCollection ddoList, boolean isDone) method on your callback object. The query is not necessarily immediately cancelled. Wait until dkCallback::dataCallback(dkCollection ddoList, boolean isDone) is called again, but with parameter isDone is marked as true. For convenience, the callback interface defines method dkCallback::dataCallback(dkCollection ddoList, boolean isDone). However, note that this method makes no call to the server. This is simply a convention for other threads reading your callback object. Your implementation must take note of the request and return the submitted cancel request the next time boolean dkCallback::dataCallback(dkCollection ddoList, boolean isDone) is called again.
Brief example: See samples SSearchICM and SSearchCallbackObjectICM for more detailed examples and documentation.
// Given DKDatastoreICM instance as variable "dsICM".
String query = "/Journal[@NumPages > 50] SORTBY (@Title)";
DKRetrieveOptionsICM dkRetrieveOptions = DKRetrieveOptionsICM.createInstance(dsICM);
dkRetrieveOptions.baseAttributes(true);
DKNVPair options[] = new DKNVPair[2];
options[1] = new DKNVPair(DKConstant.DK_CM_PARM_RETRIEVE,dkRetrieveOptions);
options[2] = 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);
// Suppose we wait for Callback Object to receive all results.
// This thread would normally do other work instead of simply waiting,
// such as displaying results as they arrive.
boolean isDone = false;
while(isDone == false) {
System.out.println("Waiting...");
java.lang.Thread.sleep(100);
isDone = callbackObject.isDone(); // Not actual callback interface, but often added for convenience.
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){
m_serverIsDone = resultsComplete; // Record server's decision in member variable for isDone().
try{
if(ddoList != null){
dkIterator iter = ddoList.createIterator();
while(iter.more()){
DKDDO ddo = (DKDDO) iter.next();
results.add(ddo);
System.out.println ("Callback Object:- Item ID:
"+((DKPidICM)ddo.getPidObject()).getItemId()
+" ("+ddo.getPidObject().getObjectType()+")");
}
}
}catch(DKException e){
printException(e);
if(firstException == null) // If it is the first failure, save it
firstException = e;
}
// If the user of your callback instance requests to cancel the query, report to server.
if(m_userRequestsCancel){ // member variable possibly set by cancelQuery()
return(true);
}else{ // Otherwise, return whether or not the server has indicated that it is done.
return(resultsComplete);
}
}Specified by: executeWithCallback in interface dkDatastore
Overrides executeWithCallback in class dkAbstractDatastore
Parameters:
virtual void executeWithCallback( const char* query,
short queryLanguageID,
DKNVPair[] queryOptionsDKNVPair,
dkCallback yourCallbackImpl);Deprecated Always construct queries using the recommended query language and always submit retrieve options (using DKRetrieveOptionsICM) for performance advantages and optimizations. Use DKDatastoreICM::executeWithCallback(String queryString,short,DKNVPair[],dkCallback)
Executes With Callback. See DKDatastoreICM::executeWithCallback(String queryString,short,DKNVPair[],dkCallback).
Deprecation details
First, this method is not advised or recommended for public use. This method is typically used indirectly by federated query calls submitted through a DKDatastoreFed session. Additional behaviors of this method are not documented, but can cause slightly different behavior than you might expect. Always construct a query string using the proper language.
Second, always specify retrieve options for optimal performance and control. Explained in detail in the retrieve options section of method DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions). Retrieve methods with no option parameter assume default deprecated bitwise 'int' retrieve options selections (which can vary depending on the method). Default selections are very unlikely to be the most optimal choice for your application after considering performance implications and choosing retrieve requests wisely.
Furthermore, all bitwise 'int' retrieve options are deprecated and not recommended (which are the assumed defaults of no-option signatures). Use DKRetrieveOptionsICM instances instead. DKRetrieveOptionsICM offers performance advantages and enables optimizations (see retrieve options section of method DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions). Methods and option values accepting int and Integer option signatures as well as no-option signatures are deprecated. Use the equivalent method with the DKNVPair[] options parameter signature instead of the deprecated int, Integer, or no-option signature for retrieve options and provide a valid DKRetrieveOptionsICM clearly indicating your intent.
Specified by: executeWithCallback in interface dkDatastore
Overrides executeWithCallback in class dkAbstractDatastore
Parameters:
Exception: DKException. See DKDatastoreICM::executeWithCallback(String queryString,short,DKNVPair[],dkCallback)
virtual void executeWithCallback(DKCQExpr* cqe, dkCallback* callbackObj);Validates the syntax, but not the semantics, of the query string. For instance, it does not check that the correct types are used in comparisons (such as comparing a string attribute to an integer), or that text search is done on attributes that are text-searchable. This type of semantic error causes exceptions to be thrown by the evaluate/execute/executeWithCallback methods.
Parameters: xqpe_query - an XML-based query string that would also be passed to the evaluate, execute, and executeWithCallback methods.
virtual void validate(const char* xqpe_query);Adds this DDO into the IBM Content Manager persistent store. The corresponding item type for this DDO must exist already. Add this new item, including all child components, to the IBM Content Manager persistent store. The tree of component DDOs with all supported attributes, properties, content, and child components are added through the root component DDO. Use the appropriate createDDO() methods to create the item in memory first. By default, the item will be checked in (unlocked).
When adding a hierarchical item, all hierarchical constraints must be met when the item is created. For example, the item must have a single hierarchical parent. The parent is specified by setting the DKConstantICM.DK_ICM_PROPERTY_PARENT_FOLDER property to the parent DDO. Note that naming and other hierarchical constraints must also be met. For more information on hierarchical constraints, see: DKDatastoreICM::getRootFolder().
Note that when creating a hierarchical item, if that item's parent can also be concurrently reindexed or deleted, or its hierarchical links modified, an inconsistency might be introduced into the hierarchical model. For more information, see: DKDatastoreICM::getRootFolder().
Example
// Given a connected DKDatastoreICM object named 'dsICM'
DKDDO ddo = dsICM.createDDO("myItemType",DK_CM_DOCUMENT);
short dataId= ddo.dataId("myAttr");
ddo.setData(dataId,"My Attribute Value");
dsICM.addObject(ddo);Specified by: addObject in interface dkDatastore
Overrides addObject in class dkAbstractDatastore
Parameters:ddoObject - data object for the root component of the item to be added.
virtual void addObject(dkDataObject* ddoObject);Exception DKException - if a problem is encountered.
Adds this DDO into the IBM Content Manager persistent store, with options. For more details, see the description for addObject(dkDataObject* ddoObject). The options are
Specified by: addObject in interface dkDatastore
Overrides: addObject in class dkAbstractDatastore
Parameters:
virtual void addObject(dkDataObject* dataobj, long option);Exception DKException - if a problem is encountered.
Adds a collection of new items, including all child components, to the IBM Content Manager persistent store. The tree of component DDOs, with all supported attributes, properties, content, and child components, are added through the root component DDO of each item. Use the appropriate createDDO() methods to create the item in memory first. By default, the item will be checked in (unlocked). A collection may be created using the DKSequentialCollection object.
// Given a connected DKDatastoreICM* object named 'dsICM'
DKDDO* ddo1 = dsICM->createDDO("myItemType",DK_CM_DOCUMENT);
DKDDO* ddo2 = dsICM->createDDO("myItemType",DK_CM_ITEM);
DKDDO* ddo3 = dsICM->createDDO("myItemType",DK_CM_FOLDER);
short dataId1= ddo1->dataId("myAttr");
short dataId2= ddo2->dataId("myAttr");
short dataId3= ddo3->dataId("myAttr");
ddo1->setData(dataId1,DKString("My Attribute Value"));
ddo2->setData(dataId2,DKString("My Attribute Value"));
ddo3->setData(dataId3,DKString("My Attribute Value"));
dkCollection* coll = new DKSequentialCollection();
coll->addElement((dkDataObjectBase*)ddo1);
coll->addElement((dkDataObjectBase*)ddo2);
coll->addElement((dkDataObjectBase*)ddo3);
dsICM->addObjects(coll); Parameters: ddoCollection - collection of root component DDOs for the items to be added. The dkCollection may be created using a DKSequentialCollection object.
virtual void addObjects(dkCollection * ddoCollection);Parameters:
virtual void addObjects(dkCollection * ddoCollection, long option);Deletes this item version from the persistent store.
When deleting a hierarchical item, an exception is thrown if the delete will violate a hierarchical item type constraint. For example, because all hierarchical items must have a hierarchical parent, a hierarchical folder that has children cannot be deleted. For more information about hierarchical constraints, see: DKDatastoreICM::getRootFolder().
Note that when deleting a hierarchical folder, if this folder is concurrently being used as a parent folder for creating a hierarchical item, there is a chance that an inconsistency will be introduced into the hierarchical model. For more details, see: DKDatastoreICM::getRootFolder().
Specified by: deleteObject in interface dkDatastore
Overrides: deleteObject in class dkAbstractDatastore
Parameters: dataobj - the root component DDO for the item version to be deleted from this datastore.
virtual void deleteObject(dkDataObject* dataobj);Exception DKException - if a problem is encountered.
Deletes this item version from the persistent store.
When deleting a hierarchical item, an exception is thrown if the delete will violate a hierarchical item type constraint. For example, because all hierarchical items must have a hierarchical parent, a hierarchical folder that has children cannot be deleted. For more information about hierarchical constraints, see: DKDatastoreICM::getRootFolder().
Note that when deleting a hierarchical folder, if this folder is concurrently being used as a parent folder for creating a hierarchical item, there is a chance that an inconsistency will be introduced into the hierarchical model. For more details, see: DKDatastoreICM::getRootFolder().
Specified by: deleteObject in interface dkDatastore
Overrides: deleteObject in class dkAbstractDatastore
Parameters:
virtual void deleteObject(dkDataObject* dataObject,option);Exception DKException - if a problem is encountered.
Deletes item versions contained in a collection from the persistent store.
Specified by: deleteObject in interface dkDatastore
Overrides: deleteObject in class dkAbstractDatastore
Parameters:
ddoColl - the collection of root component DKDDO objects representing items versions to be deleted from this persistent store. The dkCollection object can be obtained from search results (DKResults), from a child collection of a parent DDO (DKChildCollection), from the collection of folder contents (DKFolder), from a document parts collection (DKParts), or you may create a collection separately using the DKSequentialCollection object.
virtual void deleteObjects(dkCollection *ddoColl);Exception DKException - if a problem is encountered.
Deletes item versions contained in a collection from the persistent store.
Specified by: deleteObject in interface dkDatastore
Overrides: deleteObject in class dkAbstractDatastore
Parameters:
virtual void deleteObjects(dkCollection *ddoColl, long option);Exception DKException - if a problem is encountered.
DKSequentialCollection seqColl = new DKSequentialCollection();
DKSequentialCollection seqColl = new DKSequentialCollection();
DKPidICM pid = new DKPidICM(pidString);
long recordId = 1111;
seqColl.addElement(new DKPIDRecordIDPair(pid,recordId););
dsICM.deletePIDtoRecordIDMappings(seqColl);Parameters: coll - a dkCollection of DKPIDRecordIDPair objects.
Exception:Deprecated. Always submit retrieve options and always use the DKRetrieveOptionsICM object for specifying options for performance advantages and optimizations. Use method DKDatastoreICM::retrieveObject(dkDataObject ddo,DKNVPair[] retrieveOptions).
Single-Item Retrieve: See DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions).
Deprecation Details
Always specify retrieve options for optimal performance and control. Explained in detail in the retrieve options section of method DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions). Retrieve methods with no option parameter assume default deprecated bitwise 'int' retrieve options selections (which can vary depending on the method). Default selections are very unlikely to be the most optimal choice for your application after considering performance implications and choosing retrieve requests wisely.
Furthermore, all bitwise 'int' retrieve options are deprecated and not recommended (which are the assumed defaults of no-option signatures). Use DKRetrieveOptionsICM instances instead. DKRetrieveOptionsICM offers performance advantages and enables optimizations (see retrieve options section of method DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions). Methods and option values accepting int and Integer option signatures as well as no-option signatures are deprecated. Use the equivalent method with the DKNVPair[] options parameter signature instead of the deprecated int, Integer, or no-option signature for retrieve options and provide a valid DKRetrieveOptionsICM clearly indicating your intent.
Specified by: retrieveObject in interface dkDatastore
Overrides: retrieveObject in class dkAbstractDatastore
Parameters: dataobj- See dataobj parameter in DKDatastoreICM::retrieveObject(dkDataObject ddo,DKNVPair[] retrieveOptions)
virtual void retrieveObject(dkDataObject* dataObject);Exception DKException - See DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions).
Deprecated. Always submit retrieve options and always use the DKRetrieveOptionsICM object for specifying options for performance advantages and optimizations. Use method DKDatastoreICM::retrieveObject(dkDataObject ddo,DKNVPair[] retrieveOptions).
For single-Item retrieve, see DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions).
Deprecation Details
All bitwise 'int' retrieve options are deprecated and not recommended. Use DKRetrieveOptionsICM instances instead. DKRetrieveOptionsICM offers performance advantages and enables optimizations (see retrieve options section of method DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions). Methods and option values accepting int and integer option signatures as well as no-option signatures are deprecated. Use the equivalent method with the DKNVPair[] options parameter signature instead of the deprecated int, Integer, or no-option signature for retrieve options and provide a valid DKRetrieveOptionsICM clearly indicating your intent.
Specified by: retrieveObject in interface dkDatastore
Overrides: retrieveObject in class dkAbstractDatastore
Parameters:
Always specify retrieve options for optimal performance and control. Explained in detail in the retrieve options section of method DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions).
Deprecated 'int' Retrieve Options
All bitwise 'int' retrieve options are deprecated and not recommended. Use DKRetrieveOptionsICM instances instead. DKRetrieveOptionsICM offers performance advantages and enables optimizations. This setting accepts deprecated bitwise int option values.
For deprecated bitwise values, see DKDatastoreICM::retrieveObjects(dkCollection,int bitwiseRetrieveOptionsInt)
virtual void retrieveObject(dkDataObject* dataobj,long option);Exception DKException - See DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions).
Retrieves this DDO from the persistent store, with options. You can specify a retrieval with projection by providing a list of selected attributes in the option parameter. Attributes not in the list will not be retrieved.
Parameters:
virtual void retrieveObject(dkDataObject* dataobj, const DKNVPair* parms, long arraySize);Deprecated. Always submit retrieve options and always use the DKRetrieveOptionsICM object for specifying options for performance advantages and optimizations. Use method DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions)
For optimized multi-item retrieve, see DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions)
Deprecation Details
Always specify retrieve options for optimal performance and control. Explained in detail in the retrieve options section of method DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions). Retrieve methods with no option parameter assume default deprecated bitwise 'int' retrieve options selections (which can vary depending on the method). Default selections are very unlikely to be the most optimal choice for your application after considering performance implications and choosing retrieve requests wisely.
Furthermore, all bitwise 'int' retrieve options are deprecated and not recommended (which are the assumed defaults of no-option signatures). Use DKRetrieveOptionsICM instances instead. DKRetrieveOptionsICM offers performance advantages and enables optimizations (see retrieve options section of method DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions). Methods and option values accepting int and Integer option signatures as well as no-option signatures are deprecated. Use the equivalent method with the DKNVPair[] options parameter signature instead of the deprecated int, Integer, or no-option signature for retrieve options and provide a valid DKRetrieveOptionsICM clearly indicating your intent.
Specified by: retrieveObject in interface dkDatastore
Overrides: retrieveObject in class dkAbstractDatastore
Parameters: ddoColl - See ddoColl parameter in DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions)
virtual void retrieveObjects( dkCollection *ddoColl);Exception DKException - See DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions).
Deprecated. Always submit retrieve options and always use the DKRetrieveOptionsICM object for specifying options for performance advantages and optimizations. Use method DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions)
For optimized multi-item retrieve, see DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions)
Deprecation Details
All bitwise 'int' retrieve options are deprecated and not recommended. Use DKRetrieveOptionsICM instances instead. DKRetrieveOptionsICM offers performance advantages and enables optimizations (see retrieve options section of method DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions). Methods and option values accepting int and integer option signatures as well as no-option signatures are deprecated. Use the equivalent method with the DKNVPair[] options parameter signature instead of the deprecated int, Integer, or no-option signature for retrieve options and provide a valid DKRetrieveOptionsICM clearly indicating your intent.
Specified by: retrieveObject in interface dkDatastore
Overrides: retrieveObject in class dkAbstractDatastore
Parameters:
Always specify retrieve options for optimal performance and control. Explained in detail in the retrieve options section of method DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions).
All bitwise 'int' retrieve options are deprecated and not recommended. Use DKRetrieveOptionsICM instances instead. DKRetrieveOptionsICM offers performance advantages and enables optimizations (see "Retrieve Options (STRONGLY RECOMMENDED)" section of method DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions). Methods and option values accepting int and Integer option signatures as well as no-option signatures are deprecated. Use the equivalent method with the DKNVPair[] options parameter signature instead of the deprecated int, integer, or no-option signature for retrieve options and provide a valid DKRetrieveOptionsICM clearly indicating your intent.
This option accepts deprecated bitwise int option values, which are constructed by passing any one or more of the following options. Multiple options can be combined by performing a logical OR (with | operator). For example, DKConstant.DK_CM_CONTENT_ATTRONLY | DKConstant.DK_CM_CHECKOUT.
Deprecated Bitwise 'int' Retrieve Options:
virtual void retrieveObjects( dkCollection *ddoColl, int option);Exception DKException - See DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions).
For single-item retrieve (important details described in the next paragraph), see DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions)
This particular method retrieves or refreshes one root component, child component, or document part DDO, making separate server call each time this method is invoked. When you have multiple DDOs to retrieve, instead use a single optimized call to multi-item retrieve for significantly faster performance retrieving multiple DDOs. Use single-item retrieve for features that are not supported through multi-item retrieve for performance considerations.
Specified by: retrieveObject in interface dkDatastore
Overrides: retrieveObject in class dkAbstractDatastore
Parameters:
Any valid IBM Content Manager DDO representing a root component, child component, or document part. Valid DDO instances are typically obtained through the following sources.
Always specify retrieve options for optimal performance and control. This is explained in detail in the retrieve options section of method DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions).
See optionsDKNVPair in DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions)
Deprecated Values
Note that some values accepted by this interface are now deprecated. See optionsDKNVPair in retrieveObjects(dkCollection,DKNVPair[]) documentation.
Exception DKException - See DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions).
Optimized Multi-Item Retrieve
Retrieving DDOs
With any valid DDO, you can retrieve or refresh its contents. You can directly retrieve any DDO, including root component, child component, and individual document part DDOs. An "item" is typically accessed through the root component DDO.
There are two types of retrieve methods, multi-item retrieve and single-item retrieve. Multi-item retrieve offers a very significant performance advantage over making separate calls to single-item retrieve. Whenever you plan to retrieve more than one DDO, always use multi-item retrieve unless you require data that can only be retrieved through single-item retrieve. For example, resource content can only be retrieved through single-item retrieve in order to acknowledge the performance cost of retrieving large objects which typically should be used on a single-item basis. When retrieve options are submitted to query (or search) methods, query uses multi-item retrieve on your behalf on the results returned. An application should typically use multi-item retrieve for all common meta-data required of all DDOs and when one DDO require additional content, such as resource content for a specific item, that item should be submitted to single-item retrieve for its content.
Retrieve Options (STRONGLY RECOMMENDED)
Always specify your list of requests and exclusions for the best possible performance based on the detailed performance considerations documented in the DKRetrieveOptionsICM reference documentation. Submitting a DKRetrieveOptionsICM instance enables additional retrieve optimizations that are not available through default or bitwise option behavior if no DKRetrieveOptionsICM instance is submitted.
Retrieve options specified through DKRetrieveOptionsICM are strongly recommended to specify exactly what subset of data is required. Retrieve only data you plan to use and omit requests for data that you will not use. You can push your performance significantly further by using retrieve options wisely and spending performance costs only for data you will use. For data you might use only for one item, consider deferring additional retrieval until it is needed. For example, if 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 usage and object counts for unnecessary objects, and other overhead. Performance implications of every retrieve option setting is documented in detail in the reference documentation (Javadoc) for each setting (in DKRetrieveOptionsICM). You are in complete control. Retrieve exactly what you need, nothing more and nothing less, and you will squeeze the best possible performance.
The DKRetrieveOptionsICM class includes detailed reference documentation (Javadoc). The Javadoc is your complete guide to retrieve options with detailed information on performance considerations, behavior notes, data structures of where to find retrieved data within the DKDDO for any given option, and more. In order to get the best possible performance, you should thoroughly understand the DKRetrieveOptionsICM Javadoc and use retrieve options as wisely as possible. See DKRetrieveOptionsICM Javadoc for more information.
You should always provide retrieve options, even if it is to simply specify that you plan to exclude everything and not retrieve any new data. Retrieve option settings are built up incrementally, with nothing selected by default. Each setting marked as 'true' is considered a specific request for data and any setting marked as 'false' (default) is considered a specific request to exclude that data. It is much better to submit an options object with no changes to clearly demonstrate that you request nothing than for the system to attempt to guess your intentions. If no-option retrieve method is used or if no retrieve options are specified, the default is to include various selections based on the deprecated bitwise 'int' retrieve options variants and the default varies depending on which method you invoke which is strongly discouraged.
Creating & Passing DKRetrieveOptionsICM Instances
It is easy to create and pass a DKRetrieveOptionsICM instance to any retrieve method supporting the DKNVPair[] retrieve option interface.
If you prefer to create your own DKNVPair[], see documentation in DKRetrieveOptionsICM.dkNVPair() which explains further and provides examples.
Example
// Given DKDatastoreICM instance as variable "dsICM".
// Given DKDDO instances as variables "ddo1","ddo2", and "ddo3".
DKRetrieveOptionsICM dkRetrieveOptions = DKRetrieveOptionsICM.createInstance(dsICM);
dkRetrieveOptions.baseAttributes(true);
dkCollection coll = new DKSequentialCollection(); // Or any class implementing the dkColleciton interface.
coll.addElement(ddo1);
coll.addElement(ddo2);
coll.addElement(ddo3);
dsICM.retrieveObjects(coll,dkRetrieveOptions.dkNVPair());You can reuse the same retrieve options object instance instead of creating a new one for every call. However, remember to set the options that you do not want to 'false' because they do not revert to their defaults between uses.
Deprecated Bitwise 'int' Retrieve Options
All int and Integer retrieve option values and interfaces are deprecated. For example, an old style of retrieve options accepted were specified through an 'int' or Integer parameter type and accepted bitwise values from constants that could be added together, such as deprecated option DKConstantICM.DK_CM_CONTENT_ATTRONLY. Furthermore, retrieve operations with no options argument assume a default bitwise 'int' option and should also be considered deprecated.
Always use DKRetrieveOptionsICM whenever possible over the bitwise 'int' retrive options or no-option variants. Simply by using DKRetrieveOptionsICM you enable a significant number of optimizations and product updates that are not available when you use the old bitwise 'int' retrieve options, even if equivalent retrieve settings. If you had previously used the bitwise 'int' retrieve options, thoroughly read the DKRetrieveOptionsICM reference and take advantage of faster performance by using the new granular options as wisely as possible.
Retrieving Child Components and Document Parts
You can directly retrieve or refresh individual child component and document part DDOs without the need to call retrieve on the parent DDOs. However, items cannot be updated by retrieving the component and calling the DKDDO.update() method. All updates must be handled through the root component for the item or document. The child component or document part must be be modified within the retrieved structure of the root component, and then the DKDDO.update() method should be called on the root component.
Related Samples
Additional Notes
Significant additional documentation on retrieve behavior in general and other notes are detailed in both the DKRetrieveOptionsICM class documentation and within the detailed explanations of each setting. These details are not repeated here. For example, depending on your retrieve option settings, a DKDataObjectNotFoundException is thrown if all DDOs in the collection fail retrieval (such as if all have since been deleted by another user). If retrieval at least one DDO succeeds during retrieval, no such error is thrown. However, each DDO is fitted with a success or failure indicator to let you know of retrieve success, which is detailed in the DKRetrieveOptionsICM documentation.
Specified by: retrieveObject in interface dkDatastore
Overrides: retrieveObject in class dkAbstractDatastore
Parameters:
Collection of DDOs to be retrieved. Any collection implementing the dkCollection interface is accepted, provided it contains valid DKDDO instances for IBM Content Manager. A dkCollection of DDOs includes the collection returned from query results (DKResults), from a child collection of a parent DDO (DKChildCollection), from the collection of folder contents (DKFolder), from a document parts collection (DKParts), or you can create your own collection separately using a DKSequentialCollection or your own implementation of dkCollection.
Valid DDO instances are typically obtained through the following sources.
Always specify retrieve options for optimal performance and control. Explained in detail in the retrieve options section of method DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions)
It is easy to create and pass a DKRetrieveOptionsICM instance to any retrieve method supporting the DKNVPair[] retrieve option interface.
If you prefer to create your own DKNVPair[], see documentation in DKRetrieveOptionsICM.dkNVPair() which explains further and provides examples.
DKNVPair[] Details
The DKNVPair[] should contain DKNVPair with the following supported name-value pairs:
[Deprecated and not recommended]. Use integrated DKProjectionListICM with DKRetrieveOptionsICM::attributeFilters(DKProjectionListICM) instead for projection list and attribute filtering capabilities. Submit as part of retrieve options instance under integrated interface. Do not submit separate projection list requests or using the deprecated DKNVPair[] form of a projection list.
Deprecated DKNVPair[] Form of Projection List
A projection list (in the deprecated form) consists of individual projections for each item type. Each item type projection is specified through a DKNVPair where the DKNVPair name is the name of the item type and the value is a dkCollection of String objects containing the "qualified" attribute names (including child component type steps) projected for that item type. All item type projections are combined into one DKNVPair[] to be passed as the value to the retrieve options DKNVPair[].
The attribute names in the projection list should be "partially qualified" (contain the component type path to the attribute starting from [but NOT including] the root component type). Use method DKAttrDefICM.getQualifiedName() on the attribute definitions to identify the qualified name.
Example
DKNVPair[0] = DKNVPair(ItemType Name, dkCollection of "qualified" attribute names as Strings)
DKNVPair[1] = DKNVPair(ItemType Name, dkCollection of "qualified" attribute names as Strings)
DKNVPair[N] = DKNVPair(ItemType Name, dkCollection of "qualified" attribute names as Strings)
DKNVPair[0] = DKNVPair("Journal", dkCollection{"Journal_Article/Journal_Section/Title",
"Title","Journal_Article/Title","Journal_Article/Classification"})
DKNVPair[1] = DKNVPair("Book", dkCollection{"Book_Chapter/"+DK_ICM_ALL_ATTRS,
"Book_Author/"+DK_ICM_SYSTEM_ATTRS,"Book_Chapter/Book_Section/SectionNum"})
DKNVPair[2] = DKNVPair("Converence", dkCollection{DK_ICM_ALL_ATTRS,"Conference_Note/NoteNum"}) Special Keywords:
Restrictions
Projection lists are significantly improved through the integrated DKProjectionListICM to be used with DKRetrieveOptionsICM::attributeFilters(DKProjectionListICM)
Exception DKException - Exceptions are reported if errors are detected. For some information on specific exceptions, see DKRetrieveOptionsICM documentation.
Updates this item version in the persistent store. A new version will be saved if the item type definition has versioning set to Always. The default behaviour of updateObject is not to check in the item after update.
If this method is called on an item that is not changed and not checked out, an exception is thrown.
Specified by: updateObject in interface dkDatastore
Overrides: updateObject in class dkAbstractDatastore
Parameters: dataObject - Root component DDO for the item version to be updated.
virtual void updateObject(dkDataObject* dataObject);Exception DKException - if a problem is encountered.
Updates this item version in the persistent store. A new version will be saved if the item type definition has versioning set to Always. The default behaviour of updateObject is not to check in the item after update.
If this method is called on an item that is not changed and not checked out, an exception is thrown.
Specified by: updateObject in interface dkDatastore
Overrides: updateObject in class dkAbstractDatastore
Parameters:
virtual void updateObject(dkDataObject* dataobj, long option);Exception DKException - if a problem is encountered.
Starts an explicit transaction. The user needs to call either commit() or rollback() to end the transaction and to release the resources associated with the transaction. startTransaction cannot be called twice without calling commit() or rollback in between. If an error is detected by the APIs after this call and before commit() or rollback() are called(), the API may rollback all persistent changes after this point when an error occurs.
Specified by: startTransaction in interface dkDatastoreIntICM
Overrides: startTransaction in class dkAbstractDatastore
Parameters: None
virtual void startTransaction();Exception DKException - if a problem is encountered.
Starts an explicit transaction. The user needs to call either commit() or rollback() to end the transaction and to release the resources associated with the transaction. startTransaction cannot be called twice without calling commit() or rollback in between. If an error is detected by the APIs after this call and before commit() or rollback() are called(), the API may rollback all persistent changes after this point when an error occurs.
Specified by: validateConnection in interface dkDatastore
Overrides: validateConnection in class dkAbstractDatastore
Returns: a short number. The return values are:
virtual void validateConnection();Exception DKException - if a problem is encountered.
Commits all persistent changes performed by API calls after an explicit transaction was started with the startTransaction() method. If an explicit transaction has not been started, this call will have no persistent effect.
Specified by: commit in interface dkDatastore
Overrides: commit in class dkAbstractDatastore
Parameters: None
Returns: None
virtual void commit ();Exception DKException - if a problem is encountered.
Rolls back all persistent changes performed by API calls after an explicit transaction was started with the startTransaction() method. If an explicit transaction has not been started or if the transaction was automatically rolled back, this call will have no persistent effect.
Specified by: rollback in interface dkDatastore
Overrides: rollback in class dkAbstractDatastore
Parameters: None
Returns: None
virtual void rollback (); Exception DKException - if a problem is encountered.
Determines if this datastore object has been connected. Please note that this does not validate the status of the current connection. It returns true if DKDatastoreICM::connect() has been called and completed successfully, regardless of the actual state of the current communication.
Specified by: isConnected in interface dkDatastore
Overrides: isConnected in class dkAbstractDatastore
Parameters: None
Returns: TRUE if the datastore object has been connected, FALSE otherwise.
virtual DKBoolean isConnected();Gets the connection handle for this datastore.
Specified by: connection in interface dkDatastore
Overrides: connection in class dkAbstractDatastore
Returns: connection handle
virtual DKHandle* connection();Gets a datastore handle.
Specified by: handle in interface dkDatastore
Overrides: handle in class dkAbstractDatastore
Parameters: type - type of datastore handle wanted. Handle types: DK_ICM_CONNECT_HANDLE
Returns: a datastore handle.
virtual DKHandle* handle(const char* type);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.
virtual dkCollection* listDataSources();Exception DKException - if a problem is encountered.
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
Parameters: arraySize - size of the returned array
Returns: List of data source names as an array of DKString variables.
virtual DKString* listDataSourceNames(long& arrarySize);Exception DKException - if a problem is encountered.
Gets a list of entities from the persistent store.
Specified by: listEntities in interface dkDatastore
Overrides: listEntities in class dkAbstractDatastore
Parameters: None
Returns: a collection of dkEntityDef objects.
virtual dkCollection* listEntities();Exception DKException - if a problem is encountered.
Retrieves a list of entity names from the persistent store.
Specified by: listEntityNames in interface dkDatastore
Overrides: listEntityNames in class dkAbstractDatastore
Parameters: arraySize - size of the retrieved array
Returns: array of entity names.
virtual DKString* listEntityNames(long& arraySize);Exception DKException - if a problem is encountered.
Retrieves a list of attributes for the given entity name.
Specified by: listEntityAttrs in interface dkDatastore
Overrides: listEntityAttrs in class dkAbstractDatastore
Parameters: entityName - name of the entity that owns the attributes.
Returns: a dkCollection of dkAttrDef objects.
virtual dkCollection* listEntityAttrs(const char* entityName);Exception DKException - if entity name does not exist.
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.
virtual DKString* listEntityAttrNames(const char* entityName,long& arraySize);Exception DKException - if entity name does not exist.
Retrieves the list of attributes defined in the current datastore.
Returns: Collection of attribute as instances of DKAttrDefICM.
virtual dkCollection* listAttrs();Retrieves a list of names for attributes defined in the current datastore.
Parameters: arraySize - size of attribute name arrays
Returns: array of attribute names as DKString variables
virtual DKString* listAttrNames(long& arraySize);Checks whether an item is checked out from the datastore.
Parameters: dataObject - root component DDO for the item to check if the item is checked out.
Returns: TRUE if the specified DDO is checked out; FALSE otherwise
virtual DKBoolean isCheckedOut(dkDataObject* dataObject);Returns the user ID of the user who checked out the item.
Parameters: dataObject - root component DDO of the item to to check. Returns:
Returns: User ID who has checked out the specified DDO as a DKString variable
virtual DKString checkedOutUserid(dkDataObject* dataObject);Specified by: checkIn in interface dkDatastoreIntICM
Parameters: item - Root component DDO for the item to check in (unlock).
Exception: DKException if a problem is encountered.
public void checkIn(dkDataObject* item)Specified by: checkOut in interface dkDatastoreIntICM
Parameters: item - Root component DDO for the item to be checked out (locked).
Exception: DKException if a problem is encountered.
public void checkOut(dkDataObject* item) Retrieves 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.
See also: DKDatastoreDefICM
virtual dkDatastoreDef* datastoreDef();Exception DKException - if problem is encountered.
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 information is provided in the value part in the form of the schema mapping object.
Returns: mapping name for the mapping information
virtual DKString registerMapping(DKNVPair* sourceMap);Exception DKException - if problem is encountered.
Unregisters the mapping information from this datastore.
Specified by: unRegisterMapping in interface dkDatastore
Overrides: unRegisterMapping in class dkAbstractDatastore
Parameters mappingName - name of the mapping information
virtual void unRegisterMapping(const char* mappingName);Exception DKException - if problem is encountered.
Retrieves the list of registered mapping information from this datastore.
Specified by: listMappingNames in interface dkDatastore
Overrides: listMappingNames in class dkAbstractDatastore
Parameters: arraySize - size of returned mapping names array.
Returns an array of the names of the registered mapping information.
virtual DKString* listMappingNames(long& arraySize);Exception DKException - if problem is encountered.
Parameters: rid - The record id to search for.
Returns: dkCollection of DKPIDRecordIDPair objects that represent the set of mappings that correspond to the parameter 'rid'. If no mappings corresponding to 'rid' are found, an empty collection is returned.
Exception
public dkCollection listPIDtoRecordIDMappings(long rid)Parameters: pid - The pid to search for.
Returns: dkCollection of DKPIDRecordIDPair objects that represent the set of mappings that correspond to the parameter 'pid'. If no mappings corresponding to 'pid' are found, an empty collection is returned.
Exception
public dkCollection listPIDtoRecordIDMappings(DKPidICM pid)Retrieves the specified schema mapping information registered in this datastore.
Specified by: getMapping in interface dkDatastore
Overrides: getMapping in class dkAbstractDatastore
Parameters: mapping name - the name of the schema mapping information.
Returns the schema mapping object.
virtual dkSchemaMapping* getMapping(const char* mappingName);Exception DKException - if problem is encountered.
Retrieves the specified extension object from this datastore. For example, the option 'DK_CM_DATASTORE_EXT' will retrieve the DKDatastoreExtICM* object.
DKDatastoreExtICM* dsExtICM = (DKDatastoreExtICM*) dsICM->getExtension(DK_CM_DATASTORE_EXT);Specified by: getExtension in interface dkDatastore
Overrides: getExtension in class dkAbstractDatastore
Parameters: extensionName - name of the extension object to be retrieved. For the DKDatastoreExtICM object, use DK_CM_DATASTORE_EXT.
Returns extension object
virtual dkExtension* getExtension(const char* extensionName);Exception DKException - if problem is encountered.
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:
virtual void addExtension(const char* extensionName,dkExtension* extensionObj);Exception DKException - if problem is encountered.
Removes an existing extension object from this datastore.
Specified by: removeExtension in interface dkDatastore
Overrides: removeExtension in class dkAbstractDatastore
Parameters: extensionName - name of the extension object to be removed.
virtual void removeExtension(const char* extensionName);Exception DKException - if problem is encountered.
Gets the list of extension objects' names available in this datastore.
Specified by: listExtensionNames in interface dkDatastore
Overrides: listExtensionNames in class dkAbstractDatastore
Parameters: arraySize - size of extension object name array
Returns: array of extension object names
virtual DKString* listExtensionNames(long& arraySize);Exception DKException - if problem is encountered.
Create a root component DDO for a new item that has not been previously saved persistently. Creates a new DDO with object type, properties and attributes set according to the definition of the corresponding item type in this datastore. The semantic type indicates additional properties that need to be set. This method creates a new root component (in memory) for an item of the specified item type. This method allows the system to automatically set up important information in the DKDDO structure, which allows for easier and greater functionality, such as Resources, IBM Content Manager document model, and folders. The DDO returned will have the appropriate properties and attributes set up to fit the corresponding item type definition. This method prepares a new DDO instance in memory for you to modify prior to saving. In order to persist changes, you must save your new DDO using DKDDO::add() or DKDatastoreICM::addObject(). (See the SItemCreationICM sample).
In order to recreate a DDO for an existing component that is already saved persistently, instead use createDDOFromPID(...) if you have the PID object or a PID string that uniquely identifies the existing component or use query (DKDatastoreICM::evaluate() or execute()) to return recreated DDOs for existing items that match your search conditions. Then use retrieve to populate the persistent data into the blank recreated DDO.
In order to create a new child DDO, instead use createChildDDO(String itemType, String childType)
Initialized Metadata Structures in DDO
When using this method, the DDO is pre-filled with the following:
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 can be cast to the correct structure because it will be set up 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. You submit only one value, but the Item Property and Semantic Type values are derived and set separately in the DDO. The Item Property types are a subset of Semantic Types. Be sure to read and understand the "Semantic Type" section as well.
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.
| Item Property | Constant | Definition |
|---|---|---|
| Document | DK_CM_DOCUMENT | Item generically represents a document. This can be considered a "common document" because it does not rigidly mean an implementation of a specific document model. This does not necessarily mean a document with parts using the IBM Content Manager document model, which is instead controlled by the document classification in the item type definition. |
| Folder | DK_CM_FOLDER | Item represents a folder that can contain other items. This item features a built-in DKFolder collection which can hold folder contents which form folder links to other items. An empty DKFolder collection is automatically added. All items with this value are capable of using the DKFolder mechanism. However, this value does not necessarily mean that a solution uses the DKFolder mechanism and could instead implement its own folder solution. This value means any interpretation of a folder, but the built-in DKFolder is available to such items. Note that you can create non-folder links and references from items of any semantic type or item property type. |
| Item (Default) | DK_CM_ITEM | Generic Item. This is the Item Property Type for all Semantic Types that are not Document or Folder. |
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. Semantic types are primarily a feature for application use and are typically not enforced or especially meaningful within the IBM Content Manager server. This gives items an enforceable characteristic for some basic operations and provides applications with the ability to apply a semantic. Where applicable, semantic types are enforced within IBM Content Manager, but primarily the only semantic type that has any meaning, validation, or enforcement is FOLDER.
Be careful of relying on semantic type values if your application reads items created by other applications or tools since the meaning and enforcement can vary among applications. For example, do not rely on the various part semantic types since parts are allowed to be set with any semantic type value. Instead rely first on the PID's object type which identifies the exact item type which you might recognize or you can retrieve the definition to tell you more, such as classification as a part, XDO class, etc. You can rely on the semantic type as a secondary measure if you do not recognize the object type.
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.
| Semantic Type | Constant | Definition |
|---|---|---|
| Any | User Specified | CreateDDO will assign any value specified to the semantic type value. Since applications might enforce semantics as they wish, no values will be disallowed, except for item types classified as "document" (document model). |
| Document | DK_ICM_SEMANTIC_ TYPE_DOCUMENT | Item generically represents a document. This can be considered a "common document" because it does not rigidly mean an implementation of a specific document model. This does not necessarily mean a document with parts using the IBM Content Manager document model, which is instead controlled by the "document" classification in the item type definition. Equivalent to item property type DK_CM_DOCUMENT. |
| Folder | DK_ICM_SEMANTIC_ TYPE_FOLDER | Item represents a folder that can contain other items. This item features a built-in DKFolder collection which can hold folder contents which form folder links to other items. An empty DKFolder collection is automatically added. All items with this value are capable of using the DKFolder mechanism. However, this value does not necessarily mean that a solution uses the DKFolder mechanism and could instead implement its own folder solution. This value means any interpretation of a folder, but the built-in DKFolder is available to such items. Note that you can create non-folder links and references from items of any semantic type or item property type. Equivalent to item property type DK_CM_FOLDER. |
| Container | DK_ICM_SEMANTIC_ TYPE_CONTAINER | Item represents a generic container or generic item. Equivalent to item property type DK_CM_ITEM. Solutions can implement a containment relationship through any solution of their choice except for the built-in DKFolder mechanism (folder links). You can use links of any other link type, reference attributes, or any other custom solution of your choice. |
| Base | DK_ICM_SEMANTIC_ TYPE_BASE | Alleged to most nearly resemble document part of type "BASE" for use in the built-in document model where parts are created and added to make up a document. However, this value does *not* uniquely identify or make this a BASE part. This value is not validated or enforced. The item type of the part (identified in the PID's object type for the part DDO) is what makes this part a BASE part. BASE parts can be created with any semantic type of your choice. Set this semantic type for BASE parts, but when detecting part types, use the PID's object type first. Use this value if you created your own custom part item types so that other applications that might not know your custom part type and could map it to the nearest similar part type that it understands. |
| BaseText | DK_ICM_SEMANTIC_ TYPE_BASETEXT | Same as BASE (See "Base" documentation for details) except alleged to most nearly resembles "BASETEXT". |
| BaseStream | DK_ICM_SEMANTIC_ TYPE_BASESTREAM | Same as BASE (See "Base" documentation for details) except alleged to most nearly resembles "BASESTREAM". |
| Annotation | DK_ICM_SEMANTIC_ TYPE_ANNOTATION | Same as BASE (See "Base" documentation for details) except alleged to most nearly resembles "ANNOTATION". |
| History | DK_ICM_SEMANTIC_ TYPE_HISTORY | Same as BASE (See "Base" documentation for details) except alleged to most nearly resembles "HISTORY". |
| Note | DK_ICM_SEMANTIC_ TYPE_NOTE | Same as BASE (See "Base" documentation for details) except alleged to most nearly resembles "NOTE". |
| User Defined | User Defined | A User Defined Semantic Type. Refer to the Semantic Type Samples for more information. |
DDO Constructors not recommended
Using the various DKDatastoreICM::createDDO() methods are the official and recommended way to create DKDDO instances (or subclasses). Creating DDOs using "new" or any means of instantiating a DDO instance directly from a DDO class is not recommended. As explained previously, the createDDO() methods instantiate the correct subclass and set up any other necessary information within the DDOs in order to function correctly with other operations.
Overrides: createDDO in class dkAbstractDatastore
Parameters:
Specify a semantic type for this particular item instance. A semantic type can indicate additional properties of the DDO. This is the Item Property / Semantic Type described previously in this method.
For example, values are typically Document, Folder, Item, or User-Defined. However you should first rely on the PID's object type to tell you the item type name, which tells you important details such as validated document part type, item type classification, etc. Semantic types are not restricted and can be set to any valid semantic type by the application creating DDO. If multiple applications operate on the same persistent store, do not expect specific values for semantic types. The only semantic type that has a unique meaning that applies to functionality is the Folder semantic type. Also "document" classified item types restrict semantic type to either Document or Folder. Document parts are frequently set to a semantic type that matches the part type, but is not validated or guaranteed. For document parts, your application should rely on the PIDs object type (item type) to indicate the part type for any pre-defined part types, not semantic type. However, for unknown user-defined part types, you can check the semantic type in order to indicate the nearest known pre-defined part type for compatibility.
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.
virtual DKDDO* createDDO(const char* itemTypeViewName, long semanticType);Exception DKException - if errors are detected as following:
Deprecated. Replaced by createDDOFromPID(String pidString) which defaults to the recommended option setting (FALSE).
Same as createDDOFromPID(String pidString) except that you can control whether or not recreated DDO is pre-filled with initialized meta-data structures such as properties, attributes, empty child collections, empty parts collections, and empty folder collections. See createDDOFromPID(String pidString).
For recommendations, defaults, and more information impacted meta data structures, see detailed parameter 'initializeMetadataStructures' documentation.
WARNING
Note that if initializing metadata structures through a method that recreates a DDO for an existing item from a PID object or PID string:
However, if using a method that crates a new item DDO and takes the semantic type, your semantic type value is set in the DDO and the default ACL is used.
Deprecation details:
Always use createDDOFromPID(...)) instead of createDDO(...) when recreating DDO from a PID object (DKPidICM) or PID string. The option to control 'initializeMetadataStructures' has been removed and always defaults to the recommended setting (FALSE for recreating DDOs from a PID). Full details for the reason for this change is the same as explained in deprecated createDDO(String). See "Deprecation Details" in createDDO(String).
Specified by: createDDO in interface dkDatastoreIntICM
Parameters:
Recommendation:
For new items or components that have not yet been saved persistently for the first time, you typically want the DDO to be filled out with all meta-data structures and default/initial values. In this case submit TRUE.
Extremely advanced users might prefer to set to FALSE and populate exactly what is wanted to minimize overhead (not typical).
To recreate DDOs for existing items or components based on a PID or PID String, you should submit FALSE. Leverage retrieve functionality to populate the DDO with the data structures you request with the actual values. Initializing with defaults can be misleading or confusing since the state of the existing DDO appears as if it has data retrieved but does not contain accurate information.
For examples on when and why you should or should not initialize metadata structures, see section "Blank DDOs versus Initialized Metadata Structures (WARNING for C++)" in method createDDOFromPID(String pidString).
Defaults:
WARNING
Note that if initializing metadata structures through a method that recreates a DDO for an existing item from a PID object or PID string:
However, if using a method that crates a new item DDO and takes the semantic type, your semantic type value is set in the DDO and the default ACL is used.
For more information and examples on when and why you should or should not initialize metadata structures, see section "Blank DDOs versus Initialized Metadata Structures (WARNING for C++)" in method createDDOFromPID(String pidString).
Returns: a recreated DDO, same as described for the return value in createDDOFromPID(String pidString). However, returned DDO might include initialized metadata structures depending on the 'initializeMetadataStructures' parameter to this method.
virtual DKDDO* createDDO(DKPidICM* pid, bool initializeMetadataStructures);Exception
Deprecated. Replaced by createDDOFromPID(String pidString).
WARNING FOR C++ if not using createDDOFromPID()
In C++, this method's default behavior initializes meta-data structures rather than returning a blank DDO and is not recommended. See "WARNING FOR C++" section under section "Blank DDOs versus Initialized Metadata Structures" in createDDOFromPID(String pidString).
Deprecation details
Always use createDDOFromPID(...)) instead of createDDO(...) when recreating DDO from a PID object (DKPidICM) or PID string. The reason for this change is the following:
Specified by: createDDO in interface dkDatastoreIntICM
Parameters: pidString- Same as 'pidString' parameter in createDDOFromPID(String pidString)
virtual DKDDO* createDDO(DKString pidString);Exception
Deprecated (Federated Connector) Recreate a federated-mapped DDO given the PID object for an existing component DDO.
Same as createDDO(DKPidICM) except that this applied for federated mapped DDOs and you supply a federated attribute list. See createDDO(DKPidICM).
Deprecation details
This method provides support for recreating DDOs for the federated connector given a list of federated attributes to initialize in the DDO. The federated connector is deprecated, this method should only be used with the federated connector, and this method is used primarily directly by the federated connector or operations supporting the federated connector. There is little reason for you to use this method directly. To recreate DDOs for the IBM Content Manager connector, use createDDOFromPID(DKPidICM).
This method is used to recreate a DDO object given the PID object for an existing component DDO in the persistent store
Parameters: pidString- a string created from DKPidICM.pidString() method.
Returns: a recreated DDO, same as described for the return value in createDDOFromPID(String pidString). However, returned DDO includes all the properties and attributes so that the user only needs to set the attribute values. The attribute values are initialized to defaults or null.
virtual DKDDO* createDDO((DKPidICM *pid, DKString *fedAttrList,
long numOfFedAttrs);Exception
Deprecated. Replaced by createDDOFromPID(DKPidICM).
WARNING for C++ (if not using createDDOFromPID())
In C++, this method's default behavior initializes meta-data structures rather than returning a blank DDO and is not recommended. See "WARNING FOR C++" section under section "Blank DDOs versus Initialized Metadata Structures" in createDDOFromPID(String pidString).
Deprecation details
Always use createDDOFromPID(...)) instead of createDDO(...) when recreating DDO from a PID object (DKPidICM) or PID string. The reason for this change is the same as explained in deprecated createDDO(String). See "Deprecation Details" in createDDO(String).
Specified by: createDDO in interface dkDatastoreIntICM
Parameters: pid- Same as 'pid' parameter in createDDOFromPID(DKPidICM)
virtual DKDDO* createDDO(DKPidICM *pid);Exception
Deprecated
Replaced by createDDOFromPID(const char* itemTypeViewName, long semanticType). See createDDOFromPID(const char* itemTypeViewName, long semanticType)
This method follows the same documentation explained in method in createDDO(DKString itemTypeViewName, long semanticType) except that it also has a third parameter, bool initializeMetadataStructures, which is the same as is documented in the similar parameter in createDDO(DKString pidString, bool initializeMetadataStructures). See DKDatastoreICM::createDDO(DKString itemTypeViewName, long semanticType) and then 'initializeMetadataStructures' in DKDatastoreICM::createDDO(DKString pidString, bool initializeMetadataStructures).
Specified by: createDDO in interface dkDatastoreIntICM
Parameters:
Recommendation:
For new items or components that have not yet been saved persistently for the first time, you typically want the DDO to be filled out with all meta-data structures and default/initial values. In this case submit TRUE.
Exteremely advanced users might prefer to set to FALSE and populate exactly what is wanted to minimize overhead (not typical).
To recreate DDOs for existing items or components based on a PID or PID String, you should submit FALSE. Leverage retrieve functionality to populate the DDO with the data structures you request with the actual values. Initializing with defaults can be misleading or confusing since the state of the existing DDO appears as if it has data retrieved but does not contain accurate information.
Defaults:
For createDDO() methods without this parameter, this setting defaults to TRUE in C++ (FALSE in Java).
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.
virtual DKDDO* createDDO(const char* itemTypeViewName, long semanticType, bool initializeMetadataStructures);Exception
Recreate a blank DDO for an existing component that is already saved persistently if you have the PID object or a PID string that uniquely identifies the existing component. This works for any component DDO, including root components of items, child components, and document parts. Then use retrieve (with DKRetrieveOptionsICM) to populate the persistent data into the blank recreated DDO. Remember to use DKRetrieveOptionsICM with your retrieve request to ensure that for all values found within the DDO reflect accurate persisted data that you requested and nothing else.
If you have access to the PID object (DKPidICM) or have access an instance of the DDO that you want to recreate ((DKPidICM)ddo.getPidObject()), use createDDOFromPID(DKPidICM) instead of createDDOFromPID(String pidString) to save unnecessary string parsing to recreate the DKPidICM.
If you do not have the PID object or PID string, instead use query (DKDatastoreICM::evaluate() or execute()) to return recreated DDOs for existing items that match your search conditions.
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 can be cast to the correct structure because it will be set up correctly according to the Item Type Definition. For more information, please refer to the "Returns" documentation.
DDO Constructors Not Recommended
See section "DDO Constructors Not Recommended" in method createDDO(String itemType, int semanticType).
Blank DDOs versus Initialized Metadata Structures (WARNING for C++)
When recreating DDOs for existing components from PID objects or PID strings, you should always create blank DDOs (with completed PIDs). Then use retrieve (with DKRetrieveOptionsICM) to populate the persistent data into the blank recreated DDO. This way you can differentiate between accurate data populated only by the retrieve operation rather than mixed in with defaults or initial values which can remain depending on your retrieve options, attribute filters (or projections), or other reasons. For any attribute or child collection in the DDO, you want to be certain that it is accurate if it exists in the DDO rather than being uncertain whether you are looking at the initial value or if it was verified and updated by the retrieve operation.
For example, suppose you find an empty child collection in your DDO. If you had initialized the metadata structures in a recreated DDO or if you used deprecated bitwise 'int' retrieve options (or defaults), you do not know whether the empty child collection means there are no children in the persistent item or you did not retrieve children of this child type. However, if you uses a blank DDO and retrieve with DKRetrieveOptionsICM, you can trust that no collection means not yet known and a collection with cardinality '0' means that retrieve has checked and there are in fact '0' for that child type. Similarly had you used attribute filters with a non-blank DDO, you would not know which attributes were retrieved and accurate among the initialized full list of attributes.
Remember to use DKRetrieveOptionsICM with your retrieve request to enable optimizations and ensure that only features you request are updated within the DDO. Using deprecated bitwise 'int' options or defaults can alter other aspects within the DDO that are not refreshed.
Some createDDO() methods offer an additional boolean parameter, 'initializeMetadataStructures)' to control whether DDOs are pre-filled with defaults and initialized structures. (See parameter documentation in the various methods for more information). However, you should always initialize for new component DDOs and never initialize for recreating DDOs from PIDs. All methods that offer non-recommended or ambiguous behavior has been deprecated. Use only non-deprecated createDDO() methods and you will always be using the recommended solution.
WARNING FOR C++ (if not using createDDOFromPID())
Unlike Java, the default behavior for createDDO(String pidString) and createDDO(DKPidICM) in C++ does not create blank DDOs since it initializes metadata structures by default. Therefore C++ DDOs from these methods waste unnecessary memory and performance initializing data structures and suffer from ambiguity concerns mentioned previously. These methods have been deprecated and replaced by createDDOFromPID(...) which offers the recommended behavior by default (does not initialize metadata structures). Furthermore, old query or old retrieve (whenever you do not submit a DKRetrieveOptionsICM instance) use the deprecated default behavior internally which is another reason why you should always submit a DKRetrieveOptionsICM instance to query or retrieve.
Specified by: createDDOFromPID in interface dkDatastoreIntICM
Parameters: pidString: The PID string that uniquely identifies the persistent component. PID strings can be obtained from the PID object from persisted DDOs that you still have in memory and that have been previously saved or retrieved. Use DKDDO::getPidObject() and DKPidICM.pidString() or other pidString() methods.
Returns: a blank DDO instance (of the appropriate subclass) with the completed PID. Note that meta-data structures such as attributes and child components are not yet populated in the DDO until retrieved. If the DDO returned is a root component and 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, or DKVideoStreamICM and can be cast to those types based on the XDO classification defined in the item type definition.
virtual DKDDO* createDDOFromPID(DKString pidString);Exception
Same as createDDOFromPID(String pidString) except that this method accepts a PID object (DKPidICM) rather than a PID string and is slightly faster if you have access to the PID object. See createDDOFromPID(String pidString).
If you have access to the PID object (DKPidICM) or have access an instance of the DDO that you want to recreate ((DKPidICM)ddo.getPidObject()), use createDDOFromPID(DKPidICM) instead of createDDOFromPID(String pidString) to save unnecessary string parsing to recreate the DKPidICM.
This method clones the submitted PID object. This method does not directly use or modify the submitted PID and does not assume ownership of the object. You can continue to use your original PID object and the recreated DDO without affecting the each other.
All DDOs created by createDDO() methods have PID objects. However the PID objects are completed only within DDOs that have been previously saved or retrieved. Although you can recreate a DDO using a PID object from an unsaved item, the cloned PID in the recreated DDO will not uniquely identify the persistent component of the original item. Therefore, you typically should obtain PID objects from DDOs that have been previously persisted and therefore have a completed PID that can be used to uniquely identify the persistent component.
WARNING FOR C++ (if not using createDDOFromPID())
See "WARNING FOR C++" section under section "Blank DDOs versus Initialized Metadata Structures" in createDDOFromPID(String pidString)
Specified by: createDDOFromPID in interface dkDatastoreIntICM
Parameters: pid: A DKPidICM object that uniquely identifies the persistent component. The submitted PID object will be cloned by this method and you retain ownership of your original PID object. PID objects can be obtained from existing DDO instances using (DKPidICM)ddo.getPidObject().
All DDOs created by createDDO() methods have PID objects. However the PID objects are completed only within DDOs that have been previously saved or retrieved. Although you can recreate a DDO using a PID object from an unsaved item, the cloned PID in the recreated DDO will not uniquely identify the persistent component of the original item.
Returns: a new DDO as explained in more detail in createDDOFromPID(String pidString)
virtual DKDDO* createDDOFromPID(DKString pidString);Exception
Create a child component DDO for a new child component that has not been previously saved persistently (whether adding to a new item or updating an existing item with a new child component). The child component can be located anywhere under the root component, it does not have to be a direct child of the root. Creates a new DDO with object type, properties and attributes set according to the definition of the corresponding component type in this datastore. This method creates a new child component (in memory) for a child of the specified component type. This method allows the system to automatically set up important information in the DKDDO structure, which allows for easier and greater functionality. The DDO returned will have the appropriate properties and attributes set up to fit the corresponding component type definition. This method prepares a new DDO instance in memory for you to modify prior to saving.
This DDO returned not associated with its parent component or item. You must access the child collection for this child component type in the parent DDO and add this DDO to the collection. In order to persist changes, you must save the whole item by saving the root component DDO, using DKDDO::add() or DKDatastoreICM::addObject() if the item has not been saved persistently or using DKDDO::update() or DKDatastoreICM::updateObject() to save changes to an existing item, if the root component is already persistent. Remember to check out (lock) an item and retrieve the latest information me before updating to ensure you have the latest data before making changes on top of potentially outdated data. In order to recreate a DDO for an existing component that is already saved persistently, instead use createDDOFromPID(...) if you have the PID object or a PID string that uniquely identifies the existing component or use query (DKDatastoreICM::evaluate() or execute()) to return recreated DDOs for existing items that match your search conditions. Then use retrieve to populate the persistent data into the blank recreated DDO.
In order to create a new item or root component DDO, instead use createDDO(String itemType, int semanticType)
Initialized Metadata Structures in DDO
When using this method, the DDO is pre-filled with the following.
However, note that the following apply only to root components and therefore are not pre-filled in child DDOs.
DDO constructors not recommended
See section "DDO Constructors Not Recommended" in method createDDO(String itemType, int semanticType).
Specified by: createChildDDO in interface dkDatastoreIntICM
Parameters:
Returns: a new DDO object representing the child component. Child DDOs use class DKDDO and are not sub-classed further (unlike root components).
virtual DKDDO* createChildDDO(DKString itemTypeViewName, DKString childComponentTypeViewName);Exception DKException - if a problem is encountered.
Determines whether the administration domain is enabled for this datastore or not.
Specified by: adminDomainEnabled in interface dkDatastoreIntICM
Returns: TRUE if the administration domain is enabled for this datastore; FALSE otherwise
virtual DKBoolean adminDomainEnabled();Determines whether information mining is enabled for this datastore or not.
Returns: TRUE if the information mining is enabled for this datastore; FALSE otherwise
virtual DKBoolean informationMiningEnabled();Return true if user cache is enabled, false otherwise. when user cache is enabled, it also implies that global cache is enabled also, within JVM not per datastore instance.
Returns: Returns TRUE if the user cache is enabled; FALSE otherwise
virtual DKBoolean isUserCacheEnabled();Determines whether LDAP is enabled for this datastore or not.
Specified by: LDAPEnabled in interface dkDatastoreIntICM
Returns: TRUE if LDAP is enabled for this datastore; FALSE otherwise
virtual DKBoolean LDAPEnabled();Returns the platform on which the server for this datastore. Possible values for this are:
Specified by: LDAPEnabled in interface dkDatastoreIntICM
Returns: Short specifying the platform of the server.
virtual short platform();Returns whether text search is enabled for this datastore.
Specified by: textSearchEnabled in interface dkDatastoreIntICM
Returns: TRUE if text search is enabled, FALSE otherwise
virtual DKBoolean textSearchEnabled();Determines whether the workflow service is enabled on the datastore or not.
Returns: TRUE if the workflow service is enabled; FALSE otherwise
virtual DKBoolean workflowEnabled();Currently not implemented. Retrieves the locale and code page being used by this datastore instance.
Parameters:
virtual void getLocaleAndCodePae(DKString & locale, DKString & codePage);Currently not implemented. Sets the value of the locale and code page to be sued by this datastore instance. Calling this method is optional. You can pass in a string of zero length for either one of the two values that you do not want to specify.
Parameters: locale - codePage -
Returns: TRUE if the call succeeded; FALSE otherwise.
virtual DKBoolean setLocaleAndCodePage(char * locale, char * codePage);Returns the schema name for this IBM Content Manager datastore
Specified by: schemaName in interface dkDatastoreIntICM
Returns: schema name of this IBM Content Manager server.
DKString schemaName();Exception DKException - if a problem is encountered.
Lists all events related to the given item id. Returns a collection of DKEventDefICM objects. Inorder to get those information, user needs to enable itemEventFlag through system administration client. Go to Data Modeling, right click on the select item type bring up properties page select logging, Select one to all check box of Create, Update, Read, Delete as you want.
Parameters:
dkCollection* listEvents(const char* itemId, short maxResults);Exception: DKException if a problem is encountered.
Lists all events related to system administration functions. To list all event informations, user needs to enable the logging through system administration client. Go to library server configuration panel, select Log and Trace. Mark the check box for Allow System Administrator event logging Call retrieveEvent(event code, maxResults) if you want to retrieve a system administration function related event.
Parameters: maxResults - the maximum number of events to retrieve. 0 means no limits.
Returns: a collection of DKEventDefICM objects.
dkCollection* listAdminEvents(short maxResults);Exception: DKException if a problem is encountered.
Retrieves events information for the given event code from the persistent event log. Retrieve records of system administration events logged by server. To retrieve event information, user needs to enable the logging through system administration client Go to library server configuration panel, select Log and Trace Mark the check box for Allow System Administrator event logging Call listAdminEvents(maxResults) if you want to retrieve multiple event codes in the same time
Parameters:
Returns: a collection of DKEventDefICM objects with the information.
dkCollection* retrieveEvent(long eventCode);Exception: DKException if a problem is encountered.
Writes this event information into the persistent event log.
Parameters: aEvent - DKEventDefICM object to be written to the event log.
void writeEvent(DKEventDefICM* aEvent);Exception DKException - if a problem is encountered.
Retrieves the form overlay object
Parameters: name - name of form overlay object.
Returns: form overlay as an XDO object, null if the form overlay does not exist.
dkXDO* retrieveFormOverlay(DKString name);Returns the API version.
Returns: const char*, format is like: 8.3.0.200
public const char* getAPIVersion();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. Similar to the update operation, you need to check out the item prior to calling this method. The default is not to check-in the item. You need to check-in the item explicitly after calling this method. You can only move a root component.
When moving an item to a hierarchical item type, ensure that all constraints of the hierarchical model are met in the destination item type. For example, the destination item must have a single hierarchical parent. If the source item does not have a hierarchical parent, then one must be specified in the destinationDDO. The parent is specified by setting the DKConstantICM.DK_ICM_PROPERTY_PARENT_FOLDER property to the parent DDO. Note that naming and other hierarchical constraints must also be met. For more details on hierarchical constraints, see: DKDatastoreICM::getRootFolder(). Note that when moving an item from or to a hierarchical item type, if that item can also be concurrently modified or its hierarchical links modified, an inconsistency might be introduced into the hierarchical model. For more details, see: DKDatastoreICM::getRootFolder().
Specified by: moveObject in interface dkDatastore
Overrides: moveObject in class dkAbstractDatastore
Parameters
virtual moveObject(dkDataObject* ddo, const char* destinationItemType);Exception DKException - if a problem is encountered
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. Similar to the update operation, you need to check out the item prior to calling this method. After calling this method, you need to check-in the item explicitly, unless you specify the check-in option. You can only move a root component.
When moving an item to a hierarchical item type, ensure that all constraints of the hierarchical model are met in the destination item type. For example, the destination item must have a single hierarchical parent. If the source item does not have a hierarchical parent, then one must be specified in the destinationDDO. The parent is specified by setting the DKConstantICM.DK_ICM_PROPERTY_PARENT_FOLDER property to the parent DDO. Note that naming and other hierarchical constraints must also be met. For more details on hierarchical constraints, see: DKDatastoreICM::getRootFolder(). Note that when moving an item from or to a hierarchical item type, if that item can also be concurrently modified or its hierarchical links modified, an inconsistency might be introduced into the hierarchical model. For more details, see: DKDatastoreICM::getRootFolder().
Specified by: moveObject in interface dkDatastore
Parameters
virtual void moveObject(dkDataObject* sourceDDO, dkDataObject* destinationDDO, long options=0);Exception DKException - if a problem is encountered
Data type Conversion:
| Class library type | IBM Content Manager server data type |
|---|---|
| DKString | VARCHAR |
| DKString | CHAR |
| short | SHORT |
| long | INTEGER |
| DKDecimal | DECIMAL |
| DKDate | DATE |
| DKTime | TIME |
| DKTimestamp | TIMESTAMP |
| DKByteArray | BLOB,DBCLOB |
| DKString | CLOB |
Note that each piece of data is transfered into and out of the IBM Content Manager server as a character string representation of its value. The only exception to this rule is the BLOB data type; this data type is transfered in its native binary mode.
Gets the name value of an item. If the root component type of the item contains the standard name attribute, ICM$NAME, the name value is the value of the ICM$NAME attribute. Otherwise, the name value is generated according to the algorithm described in the following section.
This method will work with any DDO. However, because only item types that have the name attribute (ICM$NAME) can hold a name value, the name value for item types that do not have the name attribute must be generated. The following algorithm is used to generate the name value, in order of precedence:
If the value of the attribute chosen is null, then "[null]" is returned.
A retrieve call for the item can be made if the information needed to generate the name is not in memory. A single retrieve call is acceptable when looking at a single item, but if names are needed for more than one item, a multi-item retrieve call should be made on the items prior to calling this method.
For all hierarchical item types, the standard name attribute, ICM$NAME, is always included in the root component type. Therefore, for a hierarchical item, this method always returns the ICM$NAME value as the name value of the item. For more information about hierarchical item types, see: DKDatastoreICM::getRootFolder().
Parameters: ddo - the item whose name is to be retrieved.
Returns: the name of the item
DKString getName (DKDDO* ddo);Exception DKException - if a problem is encountered.
Gets the default folder that is used if the parent is not specified when adding items to a hierarchical item type. This folder is used only if the system is configured to allow default parents. For more information about configuring your system to allow default parents, see: DKLSCfgDefICM::enableHierarchicalDefaultFolder().
Returns: the system default hierarchical folder
DKDDO* getDefaultFolder();Exception DKException - if a problem occurs, DKException will be thrown if library server is not at release 8.4.3 or higher.
Gets the root folder of all hierarchical items. The root folder belongs to the ICM$FOLDER system-defined item type. This is a predefined item and its item type cannot be updated or deleted.
When creating an item type, you can specify that the item type is hierarchical. This is done by using the method: DKItemTypeDefICM::setHierarchical(boolean). For these hierarchical item types, there are additional constraints and behaviors beyond those of non-hierarchical item types. Hierarchical item types are designed to provide a hierarchy similar to a file system that can easily be used to create applications that provide a hierarchical browse model.
Hierarchical items have the following constraints:
Additionally, hierarchical folders must belong to item types that are marked as hierarchical and folderOnly. Hierarchical folders and documents cannot be mixed in the same item type. To configure an item type to contain only folders, use the method DKItemTypeDefICM::setFoldersOnly(boolean).
The hierarchical folder relationships are modeled in the same way that folder relationships are modeled for other item types. This is done by creating DKFolder relationships. Only DKFolder relationships are subject to the constraints of the hierarchical model. Other link types can still be used without restriction, but these do not form hierarchical links.
Because a parent folder is required in this model, it must be specified when creating an item unless the system is configured to use a default folder. The parent folder is specified during item creation using the DKConstantICM.DK_ICM_PROPERTY_PARENT_FOLDER property.
A convenience method can be used to get the name for an item. If this method is called for a hierarchical item, it will return the value of the ICM$NAME attribute. If this method is called for an item that is not hierarchical, it will generate a name based on the item's attributes. For more information see: DKDatastoreICM::getName(DKDDO).
The system can be configured to allow items to be created in a hierarchical item type without specifying the parent. This is done by setting a flag in the library server configuration using DKLSCfgDefICM::setHierarchicalDefaultFolderEnabled(boolean). If this flag is set, then all items created in a hierarchical item type that do not have a parent specified will be added to the system default folder. To get the system default folder, use the method DKDatastoreICM::getDefaultFolder(). Although the use of the system default folder is discouraged, it can be useful when applications that are not aware of the hierarchical model need to create items in hierarchical item types.
Because a hierarchical parent is required, a method is provided to move an item from one folder to another: DKDatastoreExtICM::moveToFolder(childItem, oldFolder, newFolder). This method allows hierarchical items to be moved without violating the parent constraints. This following method can also be used with non-hierarchical items and provides a means of moving multiple items at the same time: DKDatastoreExtICM::moveToFolder(childItems, oldFolder, newFolder).
The constraints of this model also impact the behavior of existing API operations when these operations are applied to hierarchical items. For reindex (moveObject), if an item is reindexed into a hierarchical item type, it must meet the hierarchical constraints or an exception will be thrown. For example, if an item has no hierarchical parent, one must be specified or the default folder is configured as it is during create. If the item already has a hierarchical parent, then a new parent cannot be specified. Because the name constraint is also enforced on reindex, if there is no existing value for the ICM$NAME attribute, one must be specified. If the name would produce a duplicate in the parent folder, an error will occur. For more details see: DKDatastoreICM::moveObject(dkDataObject, dkDataObject, int).
For updating a hierarchical item, a parent cannot be specified using the DKConstantICM.DK_ICM_PROPERTY_PARENT_FOLDER property because it would result in two parents. Likewise, folder operations are restricted to conform to hierarchical item type constraints. Updates to the ICM$NAME attribute will also enforce the unique name in the parent folder constraint.
When deleting a hierarchical item, the deletion will be prevented unless the item is not a folder or unless the folder has no children. A folder with children cannot be deleted directly because this would cause its children to not have a parent. Delete item does not support deleting all children under a folder (cascade delete); however, you can implement this in your application.
When there are two or more run-time operations that modify the same hierarchical item or its related DKFolder links, inconsistencies can occur. Inconsistencies are most likely to occur if a run-time operation changes the hierarchical state from a non-hierarchical state (or vice versa), adds or removes the folder link (DKFolder link type) from an item, or deletes an item. For example:
These inconsistencies are allowed because items such as the hierarchical parent folder of items in for create and reindex operations and items for link operations are involved in the linking process, but are not required for checking out. Inconsistent hierarchical linking data is tolerated because it is rare and allows high performance on concurrent run-time operations to be achieved. For information on how to find and fix these inconsistencies, see the Application Programming Guide.
Returns: the hierarchical root folder.
DKDDO* getRootFolder();Exception DKException - if a problem occurs, DKException will be thrown if library server is not at release 8.4.3 or higher.
