com.ibm.mm.sdk.server
Class DKDatastoreICM
- java.lang.Object
- com.ibm.mm.sdk.server.dkAbstractDatastore
- com.ibm.mm.sdk.server.DKDatastoreICM
- public class DKDatastoreICM
- extends dkAbstractDatastore
- implements dkDatastoreIntICM
DKDatastoreICM
instances represent a connected session to
a DB2 Content Manager V8 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.
Multi-Threading
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.
Constructor Summary
Constructor and Description |
---|
DKDatastoreICM()
Constructs the datastore and initializes it with
the default configuration.
|
DKDatastoreICM(java.lang.String configuration)
Constructs the datastore and initializes it using the supplied
configuration string.
|
Method Summary
Modifier and Type | Method and Description |
---|---|
|
addExtension(java.lang.String extensionName,dkExtension extensionObj)
Adds a new extension object to this datastore.
|
|
addObject(dkDataObject ddo)
Adds this DDO into the DB2 Content Manager persistent store.
|
|
addObject(dkDataObject ddo,int option)
Adds this DDO into the DB2 Content Manager persistent store, with options.
|
|
addPIDtoRecordIDMappings(dkCollection coll)
Adds instances of DKPIDRecordIDPair contained in collection to persistent datastore.
|
|
adminDomainEnabled()
Returns whether administration domain is enabled for this datastore.
|
|
changePassword(java.lang.String userId,java.lang.String oldPwd,java.lang.String newPwd)
|
|
checkIn(dkDataObject item)
Checks in an item previously checked out from the datastore.
|
|
checkOut(dkDataObject item)
Checks out an item from the datastore.
|
|
clearCache(int option)
Clear cache based on option passed.
|
|
commit()
Commits all persistent changes performed by API calls after an explicit transaction was started with the
startTransaction() method.
|
|
connect(java.lang.String datastore_name,java.lang.String user_name,java.lang.String authentication,java.lang.String connect_string)
Establishes a connection to a DB2 Content Manager datastore.
|
connection()
Gets the connection handle for this datastore.
|
|
createChildDDO(java.lang.String itemTypeViewName,java.lang.String childTypeViewName)
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).
|
|
createDDO(DKPidICM pid)
Deprecated. Replaced by
.
|
|
createDDO(DKPidICM pid,boolean initializeMetadataStructures)
Deprecated. Replaced by
which defaults to the recommended option setting (FALSE).
|
|
createDDO(DKPidICM pid,java.lang.String[] fedAttributeList)
Deprecated. (Federated Connector) Recreate a federated-mapped DDO given the PID
object for an existing component DDO.
|
|
createDDO(java.lang.String pidString)
Deprecated. Replaced by
.
|
|
createDDO(java.lang.String pidString,boolean initializeMetadataStructures)
Deprecated. Replaced by
which defaults to the recommended option setting (FALSE).
|
|
createDDO(java.lang.String itemTypeViewName,int semanticType)
Create a root component DDO for a new item that has not been previously
saved persistently.
|
|
createDDOFromPID(DKPidICM pid)
Same as
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.
|
|
createDDOFromPID(java.lang.String pidString)
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.
|
|
datastoreDef()
Gets the datastore definition object.
|
|
|
datastoreName()
Gets the name of this datastore object.
|
|
datastoreType()
Gets the datastore type for this datastore.
|
|
db2NSEenabled()
Returns whether DB2 NSE text search is enabled.
|
|
db2TSWithCtorEnabled()
Returns whether the new DB2 Text Search feature is enabled.
|
|
deleteObject(dkDataObject ddo)
Deletes this item version from the persistent store.
|
|
deleteObject(dkDataObject ddo,int option)
Deletes this item version from the persistent store.
|
|
deleteObjects(dkCollection ddoCollection)
Deletes item versions contained in a collection from the persistent store.
|
|
deleteObjects(dkCollection ddoCollection,int option)
Deletes item versions contained in a collection from the persistent store.
|
|
deletePIDtoRecordIDMappings(dkCollection coll)
Deletes instances of DKPIDRecordIDPair contained in collection to persistent datastore.
|
|
destroy()
Destroys the datastore object.
|
|
disconnect()
Disconnects from a DB2 Content Manager datastore.
|
|
evaluate(DKCQExpr cqe)
Deprecated. (!) Always construct queries using the recommended query language
and always submit retrieve options (using
)
for performance advantages and optimizations. (!) Use
|
|
evaluate(java.lang.String query,short queryLanguageID,DKNVPair[] queryOptionsDKNVPair)
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).
|
execute(DKCQExpr cqe)
Deprecated. (!) Always construct queries using the recommended query language
and always submit retrieve options (using
)
for performance advantages and optimizations. (!) Use
|
|
execute(java.lang.String query,short queryLanguageID,DKNVPair[] queryOptionsDKNVPair)
Executes query string
command against this datastore and
returns a result set cursor object to provide access to the results.
|
|
|
executeCount(DKCQExpr cqe)
Deprecated. (!) Always construct queries using the recommended query language.
(!) Use .
|
|
executeCount(java.lang.String query,short queryLanguageID,DKNVPair[] queryOptionsDKNVPair)
Gets the count of the number of results found by the specified query
without the extra overhead of returing the list of individual results.
|
|
executeWithCallback(DKCQExpr cqe,dkCallback callbackObj)
Deprecated. (!) Always construct queries using the recommended query language
and always submit retrieve options (using
)
for performance advantages and optimizations. (!) Use
|
|
executeWithCallback(java.lang.String query,short queryLanguageID,DKNVPair[] queryOptionsDKNVPair,dkCallback yourCallbackImpl)
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.
|
|
getAPIVersion()
Returns the API version
|
getDefaultFolder()
Get the default folder used when adding item to hierarchical item
types if the parent is not specified.
|
|
getExtension(java.lang.String extensionName)
Gets the specified extension object from this datastore.
|
|
|
getLogID()
This method returns the logID for use by other classes.
|
|
getLSSessionId()
Returns the librsry server sessionId.
|
|
getLSVersion()
Returns the Library Server version
|
getMapping(java.lang.String mappingName)
Gets the specified schema mapping information registered in this datastore.
|
|
|
getName(DKDDO ddo)
Get the name value for an item.
|
|
getOption(int option)
Gets a datastore option.
|
getRootFolder()
Get the root folder of for all hierarchical items.
|
|
|
getSessionId()
Returns the _session_id.
|
getTextSearchEngine()
Returns the default text search engine type for the database text engine.
|
|
getTextSearchEngineTypes()
Returns a collection of text search engine types or null, if there is no text search engine in
your configuration.
|
|
|
getUserName()
This method returns the currently logged in user.
|
|
getUserTraceLevel()
This method returns the trace level for the currently logged in user.
|
handle(java.lang.String type)
Gets a datastore handle.
|
|
|
isConnected()
Determines if this datastore object has been connected.
|
|
isGlobalCacheEnabled()
return true if global cache is enabled, false otherwise.
|
|
isUserCacheEnabled()
return true if user cache is enabled, false otherwise.
|
|
LDAPEnabled()
Returns whether LDAP is enabled for this datastore.
|
listAdminEvents(short maxResults)
Lists all events related to System Administration functions.
|
|
listContentViewEvents(java.lang.String[] userIds,DKTimestamp from,DKTimestamp to,int maxResults,int startAtRow,int options)
Lists all of the resource manager view events (event code 531) for the specified userids in the
specified time period.
|
|
|
listDataSourceNames()
Lists the names of the available datastores that can
be used to connect with.
|
listDataSources()
Lists the available datastores that can
be used to connect with.
|
|
listEntities()
Gets a list of user defined item type definitions and item type view definitions from a persistent store.
|
|
|
listEntityAttrNames(java.lang.String entityName)
Gets a list of attribute names for a given entity name.
|
listEntityAttrs(java.lang.String entityName)
Gets a list of attributes for a given entity name.
|
|
|
listEntityNames()
Gets a list of user defined item type names and item type view names from a persistent store.
|
listEvents(java.lang.String itemId,short maxResults)
Lists all events related to the given item id.
|
|
|
listExtensionNames()
Gets the list of extension objects' names available in this datastore.
|
|
listMappingNames()
Gets the list of registered mapping information from this datastore.
|
listPIDtoRecordIDMappings(DKPidICM pid)
Retrieves DKPIDRecordIDPair mappings associated with specified PID from persistent datastore.
|
|
listPIDtoRecordIDMappings(long rid)
Retrieves DKPIDRecordIDPair mappings associated with specified recordID from persistent datastore.
|
|
|
moveObject(dkDataObject sourceDDO,dkDataObject destinationDDO,int options)
Moves the data-object from the current item type to another in this datastore.
|
|
moveObject(dkDataObject ddo,java.lang.String destinationItemType)
Moves the data-object from the current item type to another item type in this datastore.
|
|
platform()
Returns the operating system platform upon which the current connected
library server is running.
|
prefetchObjects(dkCollection prefetchColl,DKNVPair[] nvPairs)
Prefetches the objects to the prefetch collection associated to the the itemtype of that item.
|
|
|
registerMapping(DKNVPair sourceMap)
Registers mapping information to this datastore.
|
|
removeExtension(java.lang.String extensionName)
Removes an existing extension object from this datastore.
|
retrieveEvent(int eventCode,short maxResults)
Retrieves events information for the given event code from the persistent event log.
|
|
retrieveFormOverlay(java.lang.String name)
Retrieves the form overlay object.
|
|
|
retrieveObject(dkDataObject ddo)
Deprecated. (!) Always submit retrieve options and always use the
object for specitying options for performance advantages and
optimizations. (!) Use method .
|
|
retrieveObject(dkDataObject ddo,DKNVPair[] optionsDKNVPair)
Single-Item Retrieve (Important details described below).
|
|
retrieveObject(dkDataObject ddo,int bitwiseRetrieveOptionsInt)
Deprecated. (!) Always submit retrieve options and always use the
object for specitying options for performance advantages and
optimizations. (!) Use method
|
|
retrieveObjects(dkCollection ddoColl)
Deprecated. (!) Always submit retrieve options and always use the
object for specitying options for performance advantages and
optimizations. (!) Use method
|
|
retrieveObjects(dkCollection ddoColl,DKNVPair[] optionsDKNVPair)
Optimized Multi-Item Retrieve (Important details described below).
|
|
retrieveObjects(dkCollection ddoColl,int bitwiseRetrieveOptionsInt)
Deprecated. (!) Always submit retrieve options and always use the
object for specitying options for performance advantages and
optimizations. (!) Use method
|
|
rollback()
Rolls back all persistent changes performed by API calls after an explicit transaction was started with the
startTransaction() method.
|
|
schemaName()
Returns the schema Name
|
|
setOption(int option,java.lang.Object value)
Sets a datastore option.
|
|
startTransaction()
Starts an explicit transaction.
|
|
textSearchEnabled()
Returns whether text search is enabled for this datastore.
|
|
unRegisterMapping(java.lang.String mappingName)
Unregisters mapping information from this datastore.
|
|
updateObject(dkDataObject ddo)
Updates this item version in the persistent store.
|
|
updateObject(dkDataObject ddo,int option)
Updates this item version in the persistent store.
|
|
userName()
Gets the user name for this datastore.
|
|
validateConnection()
validate the database connection.
|
|
writeEvent(DKEventDefICM aEvent)
Writes this event information to the persistent event log.
|
Methods inherited from class com.ibm.mm.sdk.server.dkAbstractDatastore |
---|
addObject, addObjects, addObjects, addObjects, clearCache, connectWithCredential, createQuery, createQuery, deleteObject, deleteObjects, evaluate, evaluate, execute, execute, executeWithCallback, executeWithCallback, listAvailableServices, listSchema, listSchemaAttributes, listSearchableEntities, listSearchableEntityNames, listSearchTemplateNames, listSearchTemplateNames, listSearchTemplates, listServers, serviceMgr, updateObject, updateObjects, updateObjects, updateObjects |
Methods inherited from class java.lang.Object |
---|
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Methods inherited from interface com.ibm.mm.sdk.common.dkDatastoreIntICM |
---|
informationMiningEnabled, workflowEnabled |
Methods inherited from interface com.ibm.mm.sdk.common.dkDatastore |
---|
addObject, addObjects, addObjects, addObjects, clearCache, connectWithCredential, createQuery, createQuery, deleteObject, deleteObjects, evaluate, evaluate, execute, execute, executeWithCallback, executeWithCallback, listAvailableServices, listSchema, listSchemaAttributes, listSearchableEntities, listSearchableEntityNames, listSearchTemplateNames, listSearchTemplates, listServers, serviceMgr, updateObject, updateObjects, updateObjects, updateObjects |
Constructor Detail
DKDatastoreICM
- public DKDatastoreICM()
- throws DKException
- java.lang.Exception
DKDatastoreICM
- public DKDatastoreICM(java.lang.String configuration)
- throws DKException
- java.lang.Exception
configuration
- configuration string used for initialization.
Configuration string is a sequence of name/value pairs separated by
semi colons.
Valid name/value pairs are:
- DSNAME=<datastore_name> Supplies the datastore name. Optional
- DBAUTH=<SERVER | CLIENT> Database authentication information. If SERVER is supplied the database userid and password will be supplied to the server. If CLIENT is supplied no database userid and password will be supplied to the server. The default is SERVER. Optional
- LDAPORG=<(LDAP organization)> Specifies the LDAP organization providing the directory information. This can be used when the list of datasources is in IBM Secure Way. Optional
- ICMSERVERSFILE=<(datasource information file location)> Specifies the file location of the datasource information. Optional
- ICMSERVERSURL=<(datasource information url location)> Specifies the url location of the datasource information. Optional
- ICMENVFILE=<(database connection information file location)> Specifies the file location of the database connection information. Optional
- ICMENVURL=<(database connection information url location)> Specifies the url location of the database connection information. Optional
- CHKDBPOOL=<YES | NO> Check for database pooling. The default is YES. Optional
DKException
- if a problem is encountered. java.lang.Exception
Method Detail
addPIDtoRecordIDMappings
- public void addPIDtoRecordIDMappings( dkCollection coll)
- throws DKException
- java.lang.Exception
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);
coll
- a dkCollection of DKPIDRecordIDPair objects. DKUsageError
- with error code DK_CM_MSG_INVPARM if input parameter 'coll' is NULL. DKUsageError
- with error code DK_ICM_MSG_INVALID_ICMPID if given PID is invalid DKUsageError
- with error code DK_ICM_MSG_PIDRECORDIDPAIR_DUPLICATE if PID and RecordID combination already exists. DKUsageError
- with error code DK_ICM_MSG_PID_NOT_FOUND if PID does not reference a item in datastore. DKUsageError
- with error code DK_ICM_MSG_FEATURE_NOT_SUPPORTED_IN_RELEASE if this method is called against a Library Server version lower than 8.3.0.3. DKException
- with error code DK_ICM_MSG_INTERNAL_ERROR if internal server error occurs. java.lang.Exception
deletePIDtoRecordIDMappings
- public void deletePIDtoRecordIDMappings( dkCollection coll)
- throws DKException
- java.lang.Exception
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);
coll
- a dkCollection of DKPIDRecordIDPair objects. DKUsageError
- with error code DK_CM_MSG_INVPARM if input parameter 'coll' is NULL. DKUsageError
- with error code DK_ICM_MSG_INVALID_ICMPID if given PID is invalid DKUsageError
- with error code DK_ICM_MSG_PIDRECORDIDPAIR_NOTFOUND if PID and RecordID combination does not exist in datastore. DKUsageError
- with error code DK_ICM_MSG_FEATURE_NOT_SUPPORTED_IN_RELEASE if this method is called against a Library Server version lower than 8.3.0.3. DKException
- with error code DK_ICM_MSG_INTERNAL_ERROR if internal server error occurs. java.lang.Exception
listPIDtoRecordIDMappings
- public dkCollection listPIDtoRecordIDMappings( long rid)
- throws DKException
- java.lang.Exception
rid
- The record id to search for. DKUsageError
- with error code DK_ICM_MSG_FEATURE_NOT_SUPPORTED_IN_RELEASE if this method is called against a Library Server version lower than 8.3.0.3. DKException
- with error code DK_ICM_MSG_INTERNAL_ERROR if internal server error occurs. java.lang.Exception
listPIDtoRecordIDMappings
- public dkCollection listPIDtoRecordIDMappings( DKPidICM pid)
- throws DKException
- java.lang.Exception
pid
- The pid to search for. DKUsageError
- with error code DK_CM_MSG_INVPARM if input parameter 'coll' is NULL. DKUsageError
- with error code DK_ICM_MSG_INVALID_ICMPID if given PID is invalid DKUsageError
- with error code DK_ICM_MSG_FEATURE_NOT_SUPPORTED_IN_RELEASE if this method is called against a Library Server version lower than 8.3.0.3. DKException
- with error code DK_ICM_MSG_INTERNAL_ERROR if internal server error occurs. java.lang.Exception
connect
- public void connect(java.lang.String datastore_name,
- java.lang.String user_name,
- java.lang.String authentication,
- java.lang.String connect_string)
- throws DKException
- java.lang.Exception
datastore_name
- the datastore name to connect with user_name
- the user name for establishing the connection authentication
- user's password connect_string
- the connect string used for initializing
connection options.
Connect string is a sequence of name/value pairs separated by
semi-colons.
Note: Options below will override similar values that are in
cmbicmsrvs.ini.
Valid name/value pairs are listed below:
- SQLUID=<database userid> userid for the underlying database. Optional
- SQLPWD=<database password> user's password for the undelying database. Optional
- SSO=<TRUE | FALSE> Single signon information. If set to TRUE DBAUTH must be set to CLIENT, no user_name and no authentication should be supplied to this connect method. Optional
- DBAUTH=<SERVER | CLIENT> Database authentication information. If SERVER is supplied the database userid and password will be supplied to the server. If CLIENT is supplied no database userid and password will be supplied to the server. The default is SERVER. Optional
- SCHEMA=<database schema> database schema name to use. Optional
- HOSTNAME=<host name> library server host name. Optional
- REMOTEDB=<remote database name> library server remote database name. DB2 only. Optional
- PORT=<remote database port> library server remote database port. DB2 only. Optional
- REMOTE=<TRUE | FALSE> library server remote database indicator. DB2 only. Optional
- APPLNAME=<application name> Specifies the application name you are running. It is used to identify trace and log information. Optional
- NPWD=<new password for userid> Changes user's password to this new value. Only valid if userid is not a system userid. If the user wishes to use characters like single/double quotes, semi colons or equals they can enclose the new password in single quotes. If there are any single quotes in the new password those single quotes should become 2 single quotes. For example 'abc;=' would become NPWD='''abc;='''. Optional
- LANG=<database language> Server language. See "Content Manager System Administration" Manual for all the possible values. Optional
- REPTYPE=<DB2CON> Use the database connection id first to logon to the database. Optional
- TRACESERVERLEVEL=<trace level> Trace level for the server.
Optional
- The default trace level for the server is 0.
- ICM trace flags
- 0 ICMTRACE_OFF
- 1 ICMTRACE_BASIC
- 2 ICMTRACE_DETAILED
- 4 ICMTRACE_DATA
- 8 ICMTRACE_PERFORMANCE
- 16 ICMTRACE_PARSEBUILD
- 32 ICMTRACE_MEMDEBUG
- 256 ICMTRACE_CACHE_TRACE
- 512 ICMTRACE_CACHE_ALLOC
- 1024 ICMTRACE_CACHE_MGT
- Trace level is constructed by adding the numbers above. For example, a common tracing level is 15 (calculated by adding up 1 (ICMTRACE_BASIC), 2 (ICMTRACE_DETAILED), 4 (ICMTRACE_DATA), and 8 (ICMTRACE_PERFORMANCE)).
- ITEM_EXITS=<Class Name> Optional. Register a DB2 Content Manager v8 Connecor Exits Implementation that extends extending a supported Exit Interface such as DKItemExitsICM or supported subclass. For more information, refer to the DKItemExitsICM class documentation.
- TRUSTEDUSERLOGON=<TRUE | FALSE> Trusted user logon indicator. If set to FALSE, ignore trusted user logon privilege. The default is TRUE. Optional
- DYNAMICTABLESPACEINFO=<TRUE | FALSE> Return dynamic table space information when retrieving item type, component type or component type index from the library server. Default is FALSE (return static table space information). Optional. Note: This is an administrative option. Setting this option to TRUE may impact performance during runtime. If the library server configuration option to disable retrieving of dynamic table space information is turned on, this connect string option set to TRUE will be overridden.
- JDBCDRIVER=< JDBC Driver Class Name> Optional. The name of JDBC driver class used to access the database. IBM DB2 Driver for JDBC and SQLJ (com.ibm.db2.jcc.DB2Driver) Type 4 driver is used as default driver for access to DB2 except on iSeries. On iSeries DB2 JDBC Type 2 Driver (com.ibm.db2.jdbc.app.DB2Driver) is used as the default driver. ClassNotFoundException is thrown when this method is unable to load the driver class. This is option applicable only for DB2.
- JDBCURL=< a database URL of the form jdbc:subprotocol:subname> Optional. The database URL is used to establish a connection to the given database. If this parameter is not passed, the method builds a JDBC URL using the information in cmbicmsrvs.ini file. The properties in the cmbicmsrvs.ini file used to build the URL are ICMREMOTEDB, ICMHOSTNAME and ICMPORT. If these proprties are available in cmbicmsrvs.ini file for the datastore name passed, Type 4 driver will be used to connect to the database. Otherwise Type 2 driver will be used. This option is applicable for both DB2 and Oracle.
- DKLogPriority=< API log level for default logger only>, or DKAPIJavaLogLevel=< API log level for log4j logger only>
Optional.
This is to override log level specified in the cmblogconfig.properties file. API log levels are:
- DISABLE (Disables logging)
- FATAL (Logs FATAL messages)
- ERROR (Logs FATAL + ERROR messages)
- PERF (Logs FATAL + ERROR + PERFORMANCE messages, default logger only)
- INFO (Logs FATAL + ERROR + PERFORMANCE + INFO messages)
- TRACE_NATIVE_API (Logs FATAL + ERROR + PERFORMANCE + INFO + TRACE_NATIVE_API messages)
- TRACE_ENTRY_EXIT (Logs FATAL + ERROR + PERFORMANCE + INFO + TRACE_NATIVE_API + TRACE_ENTRY_EXIT messages)
- TRACE (Logs FATAL + ERROR + PERFORMANCE + INFO + TRACE_NATIVE_API + TRACE_ENTRY_EXIT + TRACE messages)
- DEBUG (Logs FATAL + ERROR + PERFORMANCE + INFO + TRACE_NATIVE_API + TRACE_ENTRY_EXIT + TRACE + DEBUG messages)
- GMTSYSATTRTS=<TRUE | FALSE> Get the following system attribute timestamps in GMT. SYSROOTATTRS.CREATETS, SYSROOTATTRS.LASTCHANGEDTS, SYSROOTATTRS.CHKOUTTIMESTAMP, ICM$RETENTIONDATE and ICM$AUTODELETEDATE. If set to TRUE, get above system attributes in GMT. The default is FALSE. Optional Option in cmbicmsrvs.ini file is ICMGMTSYSATTRTS=<TRUE | FALSE>
- GMTSYSATTRDATE=<TRUE | FALSE> Get the following system attributes dates in GMT. SYSROOTATTRS.EXPIRATIONDATE If set to TRUE, get above system attributes in GMT. The default is FALSE. Optional Option in cmbicmsrvs.ini file is ICMGMTSYSATTRDATE=<TRUE | FALSE>
- GMTDOCROUTINGATTRTS=<TRUE | FALSE> Get the following document routing attribute timestamps in GMT. ICMUT00204001.LASTACCTIME, ICMUT00204001.RESUMETIME, ICMUT00204001.NOTIFYTIME and ICMUT00204001.ICMPRNOTIFYTIME. If set to TRUE, get above document routing attributes in GMT. The default is FALSE. Optional Option in cmbicmsrvs.ini file is ICMGMTDOCROUTINGATTRTS=<TRUE | FALSE>
- GMTUSERATTRTS=<TRUE | FALSE> Get user attribute timestamps in GMT. If set to TRUE, get user attribute timestamps in GMT. The default is FALSE. Optional Option in cmbicmsrvs.ini file is ICMGMTUSERATTRTS=<TRUE | FALSE>
- GMTUSERATTRDATE=<TRUE | FALSE> Get user attribute dates in GMT. If set to TRUE, get user attribute dates in GMT. The default is FALSE. Optional Option in cmbicmsrvs.ini file is ICMGMTUSERATTRDATE=<TRUE | FALSE>
- GMTUSERATTRTIME=<TRUE | FALSE> Get user attribute times in GMT. If set to TRUE, get user attribute times in GMT. The default is FALSE. Optional Option in cmbicmsrvs.ini file is ICMGMTUSERATTRTIME=<TRUE | FALSE>
- JDBCPOOLCFG=<TRUE | FALSE> JDBC pool configuration indicator. If TRUE then use jdbc pool configuration options instead of cmbpool.ini. If FALSE the use cmbpool.ini for jdbc pool configuration. The default is FALSE. Optional
- JDBCPOOLTYPE=<jdbc pool type> JDBC pool type. Valid values are: DKPoolWAS - use the WebSphere connection pooling no value - no pool, connection owned by each datastore Optional
- JDBCPOOLSUBTYPE=<jdbc pool sub type> JDBC pool sub type. Valid values are: Liberty - WebSphere Liberty pool sub type Note: JDBCPOOLTYPE should be set to DKPoolWAS otherwise this option is ignored. no value - no pool sub type specified Optional
- JDBCPOOLPREFIX=<jdbc pool prefix> JDBC pool prefix. Examples of jdbc pool prefix for JNDI look up: java:comp/env/jdbc/ jdbc/ Optional
- TRUSTWASAUTH=<TRUE | FALSE> Trust WebSphere authentication indicator for connection with credential. If TRUE then trust WebSphere authentication of the LTPA token . If the principal is missing from the LTPA token, the token will be validated. If FALSE then validate the LTPA token with WebSphere. The default is FALSE. Optional
- ALLOWADMINIDFORDBPOOL=<TRUE | FALSE> Allow administrative user to logon and disable database connection pooling for this datastore instance while the database pool is using a database connect id and the representation type is DB2CON or ORACON. If set to TRUE, Allow this feature. The default is FALSE. Optional
- RMCOMMTYPE=<HTTPS_AVAILABLE | HTTPS_ONLY | HTTP> Resource
manager communication type.
- HTTPS_AVAILABLE Use Resource Manager HTTPS communication if available.
- HTTPS_ONLY Use Resource Manager HTTPS communication only.
- HTTP Use Resource Manager HTTP communication. (Default)
- RMSSLTRUSTSTORE=<resource manager SSL trust store> Resource manager SSL trust store. Optional
- RMSSLTRUSTSTOREPWD=<resource mgr SSL trust store password> Resource manager SSL trust store password. Optional
- RMSSLTRUSTSTORETYPE=<resource manager SSL trust store type> Resource manager SSL trust store type. Optional
- RMSSLTRUSTSTOREPROVIDERNAME=<resource manager SSL trust store provider name> Resource manager SSL trust store provider name. If this value is set, this option is only used if the trust store type option is specified. Optional
- RMSSLTRUSTMGRALGORITHM=<resource manager SSL trust manager algorithm> Resource manager SSL trust manager algorithm. If this value is not set a default value of IbmX509 will be used Optional
- RMSSLTRUSTMGRPROVIDERNAME=<resource manager SSL trust manager provider name> Resource manager SSL trust manager provider name. If this value is set, this option is only used if the trust manager algorithm option is specified. Optional
- RMSSLKEYSTORE=<resource manager SSL key store> Resource manager SSL key store. If this value is not set a default value of java.home System Property file separator lib file separator security file separator cacerts will be used if the resource manager communication type is HTTPS_AVAILABLE or HTTPS_ONLY. Optional
- RMSSLKEYSTOREPWD=<resource mgr SSL key store password> Resource manager SSL key store password. Optional
- RMSSLKEYSTORETYPE=<resource manager SSL key store type> Resource manager SSL key store type. If this value is not set a default value of JKS will be used if the resource manager communication type is HTTPS_AVAILABLE or HTTPS_ONLY. Optional
- RMSSLKEYSTOREPROVIDERNAME=<resource manager SSL key store provider name> Resource manager SSL key store provider name. If this value is set, this option is only used if the key store type option is specified.
- RMSSLKEYMGRALGORITHM=<resource manager SSL key manager algorithm> Resource manager SSL key manager algorithm. If this value is not set a default value of IbmX509 will be used Optional
- RMSSLKEYMGRPROVIDERNAME=<resource manager SSL key manager provider name> Resource manager SSL key manager provider name. If this value is set, this option is only used if the key manager algorithm option is specified. Optional
- RMSSLCERTIFICATELABEL=<resource mgr SSL keystore certificate label> Resource manager SSL key store certificate label for a certificate. This option is ignored if the resource manager SSL certificate authentication is FALSE. Note: If the resource manager SSL certificate authentication is TRUE and the keystore certificate label is specified, a check will be performed to see if the certificate associated with the specified label is found in the keystore. If the certificate is not found a DKUsageError will be thrown. Optional
- RMSSLCERTIFICATEAUTH=<TRUE | FALSE> Resource manager SSL certificate authentication. If TRUE then use SSL certificate authentication. If FALSE anonymous SSL resource manager communication. The default is FALSE. Optional
- RMSSLCBCPROTECTION=<TRUE | FALSE> Resource manager SSL cbc protection enabled indicator. If TRUE then enable SSL cbc protection. If FALSE do not enable SSL cbc protection. The default is TRUE. Optional
- RMSSLPROTOCOLMINTLS12=<TRUE | FALSE> Resource manager SSL protocol minimum is TLS 1.2. If TRUE then SSL protocol minimum is TLS 1.2. If FALSE then TLS 1.2 is not the minimum protocol. The default is FALSE. Optional
- RMSSLCIPHERSUITEFILTERING=<TRUE | FALSE> Resource manager SSL cipher suite filtering enabled If TRUE then SSL cipher Suites that contain the following words will be filtered out. NULL, _anon_, _40_, _DES_, _MD5, DES40 If FALSE then no filtering of cipher suites The default is FALSE. Optional
- RMSSLCONTEXTPROTOCOL=<resource manager SSL Context protocol> Resource manager SSL Context Protocol. The default is SSL Optional
- RMSSLRNGALGORITHM=<resource manager SSL Random Number Generator Algorithm> Resource manager SSL Random Number Generator Algorithm for SSLContext. If not specified this will not be used to initialize the SSLContext. Optional
- RMSSLCIPHERSUITES=<resource manager SSL cipher suites> Resource manager SSL cipher suites. Optional
- RMSSLALLOWABLEPROTOCOLS=<resource manager SSL allowable protocols> Resource manager SSL allowable protocols. Optional
- RMUSESSLFORURLBASEDRETRIEVES=<TRUE|FALSE> Use SSL for URL based retrieves to the Resource Manager. If TRUE then use SSL for URL based retrieves to the Resource Manager. If FALSE do not use SSL for URL base retrieves to the Resource Manager. The default is FALSE. Optional Note: If resource manager communication type option is set to HTTPS_AVAILABLE or HTTPS_ONLY this option will be ignored. Note: If this is option is set the cmbrm.ini file will not be used.
- RMCONNTIMEOUT=<resource manager connection timeout> Resource manager connection timeout. Timeout value is in milliseconds. If value is less than 0 or not set, timeout is disabled. If value is 0 then default value of 5000 is used. Optional Note: If this is option is set the cmbrm.ini file will not be used.
- RMCONNPOLLINTERVAL=<resource manager connection poll interval> Resource manager connection will be polled every interval until the connection is established or reosurce manager connection timeout is out. Interval value is in milliseconds. This value only takes effect if resource manager connection timeout is set. If value is less than 0 or not set, timeout is disabled. If value is equal to 0 then default value which is 5 is used. If value is greater than 2000 then DKUsageError exception is thrown. If value is greater than resource manager connection timeout (wrong settings) then DKUsageError exception is thrown. Optional Note: If this is option is set the cmbrm.ini file will not be used.
- RMCONNREADTIMEOUT=<resource manager connection read timeout> Resource manager connection read timeout. Read timeout value is in milliseconds. If value is less than 0 or not set, read timeout is disabled If value is 0 then default value of 5000 is used. Optional Note: If this is option is set the cmbrm.ini file will not be used.
- DBSSL=<TRUE | FALSE> SSL Database connection indicator The default is FALSE. Optional
- DBSSLPORT=<database SSL port number> Database SSL port DB2 Only. Optional
- DBSSLTRUSTSTORE=<database SSL trust store> database SSL trust store. Oracle Only. Optional
- DBSSLTRUSTSTOREPWD=<database SSL trust store password> database SSL trust store password. Note: Must be supplied if database SSL trust store is supplied by connect string or ini file. Oracle Only. Optional
- DBSSLTRUSTSTORETYPE=<database SSL trust store type> database SSL trust store type. Oracle Only. Optional
- DBSSLKEYSTORE=<database SSL key store> database SSL key store. Oracle Only. Optional
- DBSSLKEYSTOREPWD=<database SSL key store password> database SSL key store password. Note: Must be supplied if database SSL key store is supplied by connect string or ini file. Oracle Only. Optional
- DBSSLKEYSTORETYPE=<database SSL key store type> database SSL key store type. Oracle Only. Optional
- DBSSLVERSION=<database SSL version> database SSL version. Oracle Only. Optional
- DBSSLCIPHERSUITES=<database SSL cipher suites> database SSL cipher suites. Oracle Only. Optional
- DBSSLDISTINGUISHEDNAMEMATCH=<TRUE | FALSE> database SSL distinguished name match. The default is FALSE. Oracle Only. Optional
- INITACLCACHESIZE=<size> Set the national language string keyword access control list name initial cache size. If size is set to 1 , then only that acl name requested will be put into the acl name cache initially. If more acl names are required they will be added to the cache as requested. If the size is greater than 1 then that many acl names will be cached initially. Any additional acl names that are required will be added to the cache as requested. The default is 0 which means initially cache all acl names. Optional Option in cmbicmsrvs.ini file is ICMINITACLCACHESIZE=<size>
- IGNOREINIFILES=<TRUE | FALSE> Ignore ini files for connector information. If this option is used, make sure to supply all connector connection information with the connection string including SQLUID and SQLPWD. Ignored ini files: cmbicmsrvs.ini, cmbicmenv.ini, cmbrm.ini The default is FALSE. Optional
- SYSATTRTSASJAVASQLTS=<TRUE | FALSE> Get the following system attribute timestamps as java.sql.Timestamp instead of DKTimestamp for SYSROOTATTRS.CREATETS, SYSROOTATTRS.LASTCHANGEDTS and SYSROOTATTRS.CHKOUTTIMESTAMP. If set to TRUE, get above system attributes as java.sql.Timestamp instead of DKTimestamp. The default is FALSE. Optional Option in cmbicmsrvs.ini file is ICMSYSATTRTSASJAVASQLTS=<TRUE | FALSE>
- GMTSYSTS=<TRUE | FALSE> Get the following system timestamps in GMT. Event subscription created and updated timestamps, Event created timestamps If set to TRUE, get above system timestamps in GMT. The default is FALSE. Optional Option in cmbicmsrvs.ini file is ICMGMTSYSTS=<TRUE | FALSE>
DKException
- if a problem is encountered. java.lang.Exception
disconnect
- public void disconnect()
- throws DKException
- java.lang.Exception
disconnect
in interface dkDatastore
disconnect
in class dkAbstractDatastore
getOption
- public java.lang.Object getOption( int option)
- throws DKException
- java.lang.Exception
option
- The option identifier.
- DK_CM_OPT_CACHE: Enabled/disabled cache.
- DK_ICM_OPT_LAN_CACHE: Enabled/disabled lan cache.
- DK_CM_OPT_CACHE: Enable/disable cache. Values are: DK_CM_TRUE (default), DK_CM_FALSE
- DK_ICM_OPT_LAN_CACHE: Enable/disable lan cache. Values are: DK_CM_TRUE (default), DK_CM_FALSE
DKException
- if a problem is encountered. java.lang.Exception
setOption
- public void setOption(int option,
- java.lang.Object value)
- throws DKException
- java.lang.Exception
option
- the option identifier.
- DK_CM_OPT_CACHE: Enable/disable cache. Values are: DK_CM_TRUE (default), DK_CM_FALSE
- DK_ICM_OPT_LAN_CACHE: Enable/disable lan cache. Values are: DK_CM_TRUE (default), DK_CM_FALSE
value
- the option value. DKException
- if a problem is encountered. java.lang.Exception
evaluate
- public java.lang.Object evaluate( java.lang.String query,
- short queryLanguageID,
- DKNVPair[] queryOptionsDKNVPair)
- throws DKException
- java.lang.Exception
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.
Recommended Reading
For information on constructing query strings, performing queries, and processing results, refer to:
SSearchICM
API education sample (includes detailed reference documentation)- Application Programming Guide
-
Multi-Item Retrieve
detailed reference documentation and options SItemRetrievalICM
API education sample
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 (STRONGLY RECOMMENDED)
"
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() + ")"); }
evaluate
in interface dkDatastore
evaluate
in interface dkQueryEvaluator
evaluate
in class dkAbstractDatastore
query
- Query to perform. For example,
"/Book[@title="APG"]
returns all books with title "APG". See sample
SSearchICM
and the Application Programming Guide
for more information on query syntax.
queryLanguageID
- Always
DKConstant.DK_CM_XQPE_QL_TYPE
.
Only the XQPE query language is supported.
queryOptionsDKNVPair
- Always specify retrieve options within your
query options at a minimum for optimal performance and
control. Explained in detail in the " Retrieve Options (STRONGLY RECOMMENDED)
"
section of method DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions)
and above.
See
queryOptionsDKNVPair
in DKDatastoreICM::execute(String,short,DKNVPair[])
Deprecated Values
Note that some values accepted by this interface are now deprecated. See
queryOptionsDKNVPair
in execute(String,short,DKNVPair[])
documentation referenced above.
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.
DKException
- See
DKDatastoreICM::execute(String queryString, short queryLangID, DKNVPair[] queryOptions)
java.lang.Exception
- See
DKDatastoreICM::execute(String queryString, short queryLangID, DKNVPair[] queryOptions)
evaluate
- public java.lang.Object evaluate( DKCQExpr cqe)
- throws DKException
- java.lang.Exception
DKRetrieveOptionsICM
)
for performance advantages and optimizations. (!) Use
DKDatastoreICM::evaluate(String queryString, short queryLangID, DKNVPair[] queryOptions)
cqe
)
against this datastore and returns the results in a collection.
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.
cqe
- a combined query expression object
DKException
- See
DKDatastoreICM::evaluate(String queryString, short queryLangID, DKNVPair[] queryOptions)
java.lang.Exception
- See
DKDatastoreICM::evaluate(String queryString, short queryLangID, DKNVPair[] queryOptions)
execute
- public dkResultSetCursor execute( java.lang.String query,
- short queryLanguageID,
- DKNVPair[] queryOptionsDKNVPair)
- throws DKException
- java.lang.Exception
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.
Recommended Reading
For information on constructing query strings, performing queries, and processing results, refer to:
SSearchICM
API education sample (includes detailed reference documentation)- Application Programming Guide
-
Multi-Item Retrieve
detailed reference documentation and options SItemRetrievalICM
API education sample
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 (STRONGLY RECOMMENDED)
"
section of multi-item retrieve
reference documentation.
Important Notes About Using a Result Set Cursor
Be sure to close and destroy the result set cursor once you have finished using it to free the open connection and resources. To close and destroy the result set cursor, call the following methods:
All open result set cursors are automatically closed when either of the following are called on the
DKDatastoreICM
session instance that originated the query.
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 }
query
- Query to perform. For example,
"/Book[@title="APG"]
returns all books with title "APG". See sample
SSearchICM
and the Application Programming Guide
for more information on query syntax.
queryLanguageID
- Always
DKConstant.DK_CM_XQPE_QL_TYPE
.
Only the XQPE query language is supported.
queryOptionsDKNVPair
- Always specify retrieve options within your query options at a minimum for optimal performance and control. Explained in detail in the "
Retrieve Options (STRONGLY RECOMMENDED)
"
section of method DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions)
and above.
See the
SSearchICM
sample for examples
creating query option DKNVPair[] instances.
DKNVPair[] Details
The
DKNVPair[]
should contain
DKNVPair
with supported name-value pairs described below.
DKConstant.DK_CM_PARM_RETRIEVE = <
DKRetrieveOptionsICM
instance>
[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 theDKRetrieveOptionsICM
DKRetrieveOptionsICM
- See the "
Retrieve Options
" section of(STRONGLY RECOMMENDED)
multi-item retrieve
. - See detailed
DKRetrieveOptionsICM)
You can perform an "IDONLY" (nothing selected to retrieve beyond the PID) query by submitting aDKRetrieveOptionsICM
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 callmulti-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.
- See the "
- (deprecated)
DKConstant.DK_CM_PARM_RETRIEVE = <Integer instance>
[Deprecated and not recommended]. UseDKRetrieveOptionsICM
DKRetrieveOptionsICM
int
' options. This setting accepts deprecated bitwiseint
option values in anInteger
object. All bitwise 'int
' retrieve options are deprecated and not recommended. For deprecated bitwise values, seeDKDatastoreICM::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
' optionDKConstant.DK_CM_CONTENT_ATTRONLY
. However, it is always better to clearly indicate your intent with retrieve options.
- (deprecated)
DKConstant.DK_CM_PARM_CONTENT = <String instance>
[Deprecated and not recommended]. Use "Retrieve Options" (DKConstant.DK_CM_PARM_RETRIEVE = <
) instead of "Content Options". Always use retrieve options and value typeDKRetrieveOptionsICM
instance>DKRetrieveOptionsICM
DKRetrieveOptionsICM
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 asString
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, seeDKDatastoreICM::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)
DKConstant.DK_CM_PARM_PROJECTION_LIST = <DKNVPair[] instance>
[Deprecated and not recommended]. Use integratedDKProjectionListICM
DKRetrieveOptionsICM::attributeFilters(DKProjectionListICM)
DKNVPair[]
form of a projection list.
DKConstant.DK_CM_PARM_MAX_RESULTS = <String instance>
(containing integer)
[Recommended] Specify a maximum number of results desired as a non-negative integer formatted in aString
. 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 onITEMID
, you can issue another query with a condition on all returned values such that the value (such asITEMID
) is greater than the value contained in the last DDO in the set. This effectively allows you to resume where you left off.
Example:options[0] = new DKNVPair(DKConstant.DK_CM_PARM_MAX_RESULTS, "50");
DKConstant.DK_CM_PARM_PREFETCH_SIZE = <Integer instance>
The integer value of this option indicates the desired 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 valueN
allows for faster display of the firstN
results, but will increase the overall retrieval time for the whole result set. Retrieving all results in one block (effectively anevaluate()
If not specified, an unspecified default block size managed by the system is used which is typically reasonable for the majority of applications.
DKConstant.DK_CM_PREPARE_QUERY = null
(no value required)
If this option is specified, the query is only prepared, but the cursor is not opened and the query is not actually executed. Use the result set cursor'sdkResultSetCursor::open()
DKConstant.DK_CM_SQL_TIMEOUT = <Integer instance>
(milliseconds)
Specify a timeout (in milliseconds) for the maximum amount of time that the query should be allowed to run before it is automatically terminated (or canceled). Upon expiration of the timeout period, the system will attempt to cancel the processing of the query as soon as possible. The exact time of cancellation cannot be guaranteed, but aDKException
will be thrown from this method to the caller as soon as the cancellation attempt has initiated. The query on the server cannot necessarily be immediately terminated and the server database might continue to run the query until it reaches a point where the query can be interrupted.
If this option is not specified, the API will wait indefinitely for the query to finish. The timeout query function is supported if both the DBMS and driver support aborting an SQL statement.
Error handling. The timeout value must be a positive integer. A zero value is equivalent to not specifying the timeout at all, and the API will wait until the query finishes. A negative timeout value will result in aDKException
.
To use this feature on a z/OS system DB2 database, the z/OS system DB2 database needs to be catalogued in DB2 UDB using the following set of commands. In the example, suppose that the DB2 SSID is "SGE1", the remote z/OS host (which DDF is running on port 5111) is "ihsap3", and the remote location (which can be queried on z/OS with DISPLAY DDF) is "SGE1".
db2 catalog dcs database SGE1 as SGE1 PARMS \",,INTERRUPT_ENABLED\"
db2 catalog tcpip node SGE1SAP3 remote IHSAP3 server 5111
db2 catalog database SGE1 at node SGE1SAP3 authentication server
Note that parameter valueINTERRUPT_ENABLED
above is important because it enables the canceling of DB2 threads on the z/OS host.
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.
Important
As explained in the "Important Notes About Using a Result Set Cursor" section (above), be sure to close and destroy the cursor when you are done as well as in a
finally{}
block following a try{}
block wrapping your operations.
See section "Important Notes About Using a Result Set Cursor" (above).
DKException
- Exceptions are reported if errors are detected. For some information on specific retrieve-related exceptions, see
DKRetrieveOptionsICM
documentation.
java.lang.Exception
- A few
java.lang.Exception
objects can be
propagated in rare cases from other libraries. However,
DB2 Content Manager V8 does not throw new exceptions
that are not at least of subclass DKException
and catches most java.lang.Exception
errors
and rethrows as DKException
instances. executeCount
- public long executeCount(java.lang.String query,
- short queryLanguageID,
- DKNVPair[] queryOptionsDKNVPair)
- throws DKException
- java.lang.Exception
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:
- Retrieve option
DKRetrieveOptionsICM::functionVersionLatest()
DKConstant.DK_CM_PARM_RETRIEVE = <
.DKRetrieveOptionsICM
instance> - (deprecated) bitwise retrieve option
DKConstant.DK_CM_VERSION_LATEST
submitted through query optionDKConstant.DK_CM_PARM_RETRIEVE = (deprecated) <Integer instance>
.
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);
queryLanguageID
- See
DKDatastoreICM::execute(String queryString, short queryLangID, DKNVPair[] queryOptions)
queryOptionsDKNVPair
- See
DKDatastoreICM::execute(String queryString, short queryLangID, DKNVPair[] queryOptions)
.However, as noted above, most options do not apply to
executeCount()
and are ignored and do not
affect the count of results except for the few listed
above.
DKException
- See
DKDatastoreICM::execute(String queryString, short queryLangID, DKNVPair[] queryOptions)
java.lang.Exception
- See
DKDatastoreICM::execute(String queryString, short queryLangID, DKNVPair[] queryOptions)
execute
- public dkResultSetCursor execute( DKCQExpr cqe)
- throws DKException
- java.lang.Exception
DKRetrieveOptionsICM
)
for performance advantages and optimizations. (!) Use
DKDatastoreICM::execute(String queryString, short queryLangID, DKNVPair[] queryOptions)
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.
cqe
- a combined query expression object
DKException
- See
DKDatastoreICM::execute(String queryString, short queryLangID, DKNVPair[] queryOptions)
java.lang.Exception
- See
DKDatastoreICM::execute(String queryString, short queryLangID, DKNVPair[] queryOptions)
executeCount
- public long executeCount(DKCQExpr cqe)
- throws DKException
- java.lang.Exception
(!) Use
DKDatastoreICM::executeCount(String queryString,short,DKNVPair[] queryOptions)
.
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.
cqe
- a combined query expression object.
DKDatastoreICM::executeCount(String queryString, short queryLangID, DKNVPair[] queryOptions)
.
DKException
- See Use
DKDatastoreICM::executeCount(String queryString, short queryLangID, DKNVPair[] queryOptions)
.
java.lang.Exception
- See Use
DKDatastoreICM::executeCount(String queryString, short queryLangID, DKNVPair[] queryOptions)
. executeWithCallback
- public void executeWithCallback( java.lang.String query,
- short queryLanguageID,
- DKNVPair[] queryOptionsDKNVPair,
- dkCallback yourCallbackImpl)
- throws DKException
- java.lang.Exception
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 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); } }
executeWithCallback
in interface dkDatastore
executeWithCallback
in class dkAbstractDatastore
queryLanguageID
- See
DKDatastoreICM::execute(String queryString, short queryLangID, DKNVPair[] queryOptions)
queryOptionsDKNVPair
- See
DKDatastoreICM::execute(String queryString, short queryLangID, DKNVPair[] queryOptions)
yourCallbackImpl
- Any object implementing the
dkCallback
interface. Typically this is a class you wrote and
compiled. Query will report results by calling methods
on this object instance for every block of results.
DKException
- See
DKDatastoreICM::execute(String queryString, short queryLangID, DKNVPair[] queryOptions)
java.lang.Exception
- See
DKDatastoreICM::execute(String queryString, short queryLangID, DKNVPair[] queryOptions)
executeWithCallback
- public void executeWithCallback( DKCQExpr cqe,
- dkCallback callbackObj)
- throws DKException
- java.lang.Exception
DKRetrieveOptionsICM
)
for performance advantages and optimizations. (!) Use
DKDatastoreICM::executeWithCallback(String queryString,short,DKNVPair[],dkCallback)
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 (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.
executeWithCallback
in interface dkDatastore
executeWithCallback
in class dkAbstractDatastore
cqe
- a combined query expression object.
callbackObj
- See
DKDatastoreICM::executeWithCallback(String queryString,short,DKNVPair[],dkCallback)
DKException
- See
DKDatastoreICM::executeWithCallback(String queryString,short,DKNVPair[],dkCallback)
java.lang.Exception
- See
DKDatastoreICM::executeWithCallback(String queryString,short,DKNVPair[],dkCallback)
addObject
- public void addObject(dkDataObject ddo)
- throws DKException
- java.lang.Exception
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);
ddo
- Data object for the root component of the item to be added. DKException
- if a problem is encountered.
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 details 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 details on this, see:
.
DKDatastoreICM::getRootFolder()
java.lang.Exception
addObject
- public void addObject(dkDataObject ddo,
- int option)
- throws DKException
- java.lang.Exception
-
DKConstant.DK_CM_CHECKOUT
Use this option to check the item out after creation. The default is not to check-out the item. - DK_CM_CHECKIN or 0 (default) Check in (unlock) the item.
- DK_CM_CHECKOUT Check out (lock) the item.
ddo
- Data object for the root component of the item to be added. option
- Options for add.
- DK_CM_CHECKIN (8196)(default): Check in (unlock) the item.
- DK_CM_CHECKOUT (8): Check out (lock) the item.
- 0 (default): Uses option DK_CM_CHECKIN.
DK_ICM_NO_LINKS_MEMORY_CURRENCY (32)
: This option tells the API not to update referenced DDOs, in memory, to reflect newly added links. This option is very useful when adding a large number of links. Without this option, newly added links will be made persistent and the API will reflect these links in all referenced DDOs. With this option the links are still made persistent, however referenced DDOs are not updated to include this new link information. This option may be used to improve performance when an application does not require the information in the referenced DDOs to be updated. Even though this information will not be reflected in the referenced DDOs, the application can still call retrieve on these DDOs to get the latest links information when/if it is needed.DK_ICM_NO_ERROR_FOR_DUP_OR_NOT_FOUND_LINKS (64)
: Ignore any duplicate links (or folder relationships) added for any links that already exist in the system and ignore any delete link requests for links that have already been deleted. This allows you to add as many links as you desire without the need to retrieve and compare against the current links in memory and save the item with the intent that the submitted links should exist in the system. Similarly you can remove links without the need to verify that it was not already deleted by another request. For more details, refer to the documentation provided with constantDKConstantICM.DK_ICM_NO_ERROR_FOR_DUP_OR_NOT_FOUND_LINKS
.
DKException
- if a problem is encountered java.lang.Exception
- if a problem is encountered retrieveObject
- public void retrieveObject(dkDataObject ddo)
- throws DKException
- java.lang.Exception
DKRetrieveOptionsICM
object for specitying options for performance advantages and
optimizations. (!) Use method
DKDatastoreICM::retrieveObject(dkDataObject ddo,DKNVPair[] retrieveOptions)
.
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 (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.
retrieveObject
in interface dkDatastore
retrieveObject
in class dkAbstractDatastore
ddo
- See
ddo
parameter in
DKDatastoreICM::retrieveObject(dkDataObject ddo,DKNVPair[] retrieveOptions)
java.lang.Exception
- See
DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions)
retrieveObject
- public void retrieveObject(dkDataObject ddo,
- int bitwiseRetrieveOptionsInt)
- throws DKException
- java.lang.Exception
DKRetrieveOptionsICM
object for specitying options for performance advantages and
optimizations. (!) Use method
DKDatastoreICM::retrieveObject(dkDataObject ddo,DKNVPair[] retrieveOptions)
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 (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.
retrieveObject
in interface dkDatastore
retrieveObject
in class dkAbstractDatastore
ddo
- See
ddo
parameter in
DKDatastoreICM::retrieveObject(dkDataObject ddo,DKNVPair[] retrieveOptions)
bitwiseRetrieveOptionsInt
- (deprecated) 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)
.
Deprecated '
int
' Retrive OptionsAll 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
java.lang.Exception
- See
DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions)
retrieveObjects
- public void retrieveObjects(dkCollection ddoColl)
- throws DKException
- java.lang.Exception
DKRetrieveOptionsICM
object for specitying options for performance advantages and
optimizations. (!) Use method
DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions)
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 (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.
retrieveObjects
in interface dkDatastore
retrieveObjects
in class dkAbstractDatastore
ddoColl
- See
ddoColl
parameter in
DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions)
java.lang.Exception
- See
DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions)
retrieveObjects
- public void retrieveObjects(dkCollection ddoColl,
- int bitwiseRetrieveOptionsInt)
- throws DKException
- java.lang.Exception
DKRetrieveOptionsICM
object for specitying options for performance advantages and
optimizations. (!) Use method
DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions)
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 (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.
retrieveObjects
in interface dkDatastore
retrieveObjects
in class dkAbstractDatastore
ddoColl
- See
ddoColl
parameter in
DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions)
bitwiseRetrieveOptionsInt
- (deprecated) 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)
.
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:
-
Meta-Data Options:
- (deprecated)
DKConstant.DK_CM_CONTENT_ATTRONLY
[Recommded] (Recommended starting point for considering options.) This option retrieves user and system attributes for DDOs directly submitted to retrieve. This option has unique behavior such that it overrides automatic single-item retrieve behavior that otherwise can include resource content, one level of children, and document parts listing (TOC) if anything other thanDK_CM_CONTENT_ATTRONLY
is used. Always use this option to eliminate automatically included data if not needed. This is one of the fastest options among the bitwise retrieve options. - (deprecated)
DKConstant.DK_CM_CONTENT_RETRIEVE_IGNORE_CHECKEDOUT_INFO
[Recommended] If you do not need the checked out user ID and timestamp status for the item, save some performance by not fetching this data. In addition to any other option specified (or defaults if no other options), this option excludes fetching values for DDO properties"Checked_Out_UserID"
(DKConstantICM.DK_ICM_PROPERTY_CHECKEDOUTUSERID
) and"Checked_Out_TS"
(DKConstantICM.DK_ICM_PROPERTY_CHECKEDOUTTIMESTAMP
). while the value for the properties are returned as null. With this option, the property is still listed when iterationg through properties in the DDO, but the value is returned as 'null'. Note that 'null' is also returned if the item is not currently checked out. 'null' means either not currently checked out or not fetched. UseDKRetrieveOptionsICM::basePropertyCheckedOutDetails(false)
- (deprecated)
DKConstant.DK_CM_CONTENT_RETRIEVE_IGNORE_ACL_NAME
[Recommended] If you do not need the ACL name retrieved for the item, save some performance by not fetching this data. In addition to any other option specified (or defaults if no other options), this option excludes fetching value for DDO property"SYSROOTATTRS.ACLCODE"
(DKConstantICM.DK_ICM_PROPERTY_ACL
) while the value for the properties are returned as an empty string (""
). With this option, the property is still listed when iterationg through properties in the DDO, but the value is returned as""
. UseDKRetrieveOptionsICM::basePropertyAclName(false)
- (deprecated)
DKConstant.DK_CM_CONTENT_CHILDREN
Retrieves the list of child DDOs under any parent DDO submitted to retrieve. The child DDOs are populated within child collections and have completed PID information. No attributes of the children are retrieved. (This option is subject to automatic inclusions when using single-item retrieve depending on the retrieve method used, which can include document parts listing, parts attributes, and resource content (loaded in memory).) - (deprecated)
DKConstant.DK_CM_CONTENT_ONELEVEL
Similar (but not identical) to(DK_CM_CONTENT_ATTRONLY | DK_CM_CONTENT_CHILDREN)
such that it retrieves the attributes for DDOs submitted directly to retrieve and lists the child component DDOs (without attributes of the children). However, it is not equivalent such that it does not have the excluding behavior ofDK_CM_CONTENT_ATTRONLY
that prohibits resource content and document parts listing (TOC). Consider using(DK_CM_CONTENT_ATTRONLY | DK_CM_CONTENT_CHILDREN)
instead if you do not need the resource content or parts TOC during single-item retrieve calls. (This option is subject to automatic inclusions when using single-item retrieve depending on the retrieve method used, which can include document parts listing, parts attributes, and resource content (loaded in memory).) - (deprecated)
DKConstant.DK_CM_CONTENT_LINKS_INBOUND
In addition to any other option specified or defaults, also retrieve one level of inbound links. Populates link collections with link objects. For inbound links, the source DDO is the other item linking to the item submitted to retrieve. The source DDO will be "listed" simply with completed PID information. No attributes or other meta-data is retrieved for the linked DDO. This requires one additional server call per DDO submitted to retrieve for inbound link information. (This option is subject to automatic inclusions when using single-item retrieve depending on the retrieve method used, which can include document parts listing, parts attributes, and resource content (loaded in memory).) - (deprecated)
DKConstant.DK_CM_CONTENT_LINKS_OUTBOUND
In addition to any other option specified or defaults, also retrieve one level of outbound links (and folder relationships. Populates link collections with link objects and folder collections with DDOs for the folder contents. For outbound links, the target DDO is the other item linking to the item submitted to retrieve. The target DDO will be "listed" simply with completed PID information. No attributes or other meta-data is retrieved for the linked DDO. This requires one additional server call per DDO submitted to retrieve for outbound link information. (This option is subject to automatic inclusions when using single-item retrieve depending on the retrieve method used, which can include document parts listing, parts attributes, and resource content (loaded in memory).) - (deprecated)
DKConstant.DK_CM_CONTENT_LINKS_LEVELTWO_COUNT
Along with the first level of links, retrieve the count of the second level of links as well. All items linked under ddos submitted will have the count of their links retrieved. The count is stored as a property in the respective DDO. The property named with constantDKConstant.DK_CM_PROPERTY_LINKS_OUTBOUND_SELECTED_COUNT
contains the count of the number of outbound links of the link type(s) selected for retrieval. The property names with constantDKConstant.DK_CM_PROPERTY_LINKS_INBOUND_SELECTED_COUNT
contains the count of the number of inbound links of the link type(s) selected for retrieval. This option only applies if the first level of links is also requested through optionsDK_CM_CONTENT_LINKS_INBOUND
orDK_CM_CONTENT_LINKS_OUTBOUND
or this option is otherwise ignored. (This option is subject to automatic inclusions when using single-item retrieve depending on the retrieve method used, which can include document parts listing, parts attributes, and resource content (loaded in memory).) - (deprecated)
DKConstant.DK_CM_CONTENT_ITEMTREE_NO_LINKS
Retrieves the whole tree of components from the components submitted to retrieve through the full child hierarchy (beyond just one level) and includes attributes on all DDOs (including children). If you must retrieve the full hierarchy with attributes, this is the fastest option. No link or folder relationship information is retrieved. (This option is subject to automatic inclusions when using single-item retrieve depending on the retrieve method used, which can include document parts listing, parts attributes, and resource content (loaded in memory).) - (deprecated)
DKConstant.DK_CM_CONTENT_ITEMTREE
[Not Recommended] Equivalent to(DK_CM_CONTENT_ITEMTREE_NO_LINKS | DK_CM_CONTENT_LINKS_OUTBOUND | DK_CM_CONTENT_LINKS_INBOUND)
. Same asDK_CM_CONTENT_ITEMTREE_NO_LINKS
except that this method also includes inbound and outbound links (including folder relationships). Avoid using this option unless necessary. Selecting everything typically leads to sub-optimal retrieve option usage and unnecessary performance costs. Instead, use options wisely to retrieve only data that you need for the fastest possible performance. See retrieve option information inDKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions)
- (deprecated)
DKConstant.DK_CM_CONTENT_IDONLY
[(!) APPLIES TO QUERY METHODS ONLY (!)] When used with query/search (evaluate()
execute()
executeWithCallback()
int
retrieve option defaults. Submitting aDKConstant.DK_CM_CONTENT_IDONLY
request to retrieve (not through query) actually results in far more data retrieved than you might expect by submitting this option since it is ignored. For example, the "IDONLY" request actually is behaves as aDKConstant.DK_CM_CONTENT_ONELEVEL
request (or much more) for many retrieve methods by default. For modelling a true "nothing selected" request, use aDKRetrieveOptionsICM
- (deprecated)
-
Resource Content Options:
- (deprecated)
DKConstant.DK_CM_CONTENT_YES
[Use Carefully] In addition to other retrieve options submitted (or defaults if no other option submitted), when retreive called directly on aDKLobICM
(or subclass) object's single-item retrieve methods, retrieves the resource content for both any "resource" or "document part" classified item submitted to retrieve and any document parts listed under documents submitted directly to retrieve. Also includes document parts listing and parts attributes. When used with multi-item retrieve or other single-item retrieve methods, does not retrieve any resource content, but does retreive the parts listing (TOC) for all documents (but no parts attributes). Retrieving resource content has significant performance considerations. use carefully. - (deprecated)
DKConstant.DK_CM_CONTENT_ONLY
[Use Carefully] Applies only when used with a retrieve method directly on aDKLobICM
(or subclass) object. Ignored by all other retrieve methods. By default, every time resource content is retrieved, the meta-data is refreshed with new attrubtes (or any default if no other meta-data options specified) to refresh the system resource attributes identifying the current details of the resource content. However, if you can guarantee that the object has not changed (by any session), this option provides an optmization that skips the meta-data refresh if the system attributes have already been retrieved. For example, perhaps you previously retrieved the item through any retrieve option withDK_CM_CONTENT_ATTRONLY
, this will trust the original values retrieved last time. However, you accept the reprecussions and errors if the object has in fact changed. This option is ignored by non-resource items and is ignored if meta-data has not been previously retrieved. If the system attributes are missing, the meta data will still be refreshed. - (deprecated)
DKConstant.DK_CM_CONTENT_NO
UseDKConstant.DK_CM_CONTENT_ATTRONLY
instead, which restricts resource content retrieve processing further thanDKConstant.DK_CM_CONTENT_NO
. This option does perform some resource-related retrieve processing, but does not retrieve resource content.DKConstant.DK_CM_CONTENT_ATTRONLY
also prohibits resource content as well as additional resource-related processing.
- (deprecated)
-
Other Options:
- (deprecated)
DKConstant.DK_CM_CHECKOUT
In addition to other retrieve options (or defaults if no other options), also checks out (locks) the items submitted to retrieve. Checkout only applies to root components of items and not to children or document parts. This is a faster solution to checkout many items in one optimized call if used with multi-item retrieve compared to checking out items individually. (This option is subject to automatic inclusions when using single-item retrieve depending on the retrieve method used, which can include document parts listing, parts attributes, and resource content (loaded in memory).) - (deprecated)
DKConstant.DK_CM_VERSION_LATEST
In addition to other retrieve options (or defaults if no other options), also updates the PID to the latest version and retrieves the latest version instead of the version indicated by the original PID. (This option is subject to automatic inclusions when using single-item retrieve depending on the retrieve method used, which can include document parts listing, parts attributes, and resource content (loaded in memory).) - (deprecated)
DKConstant.DK_CM_CONTENT_RETRIEVE_USING_COMMITTED_READ
[Not Recommended] In addition to other retrieve options (or defaults if no other options), use committed read for retrieving attributes and children. The default is to use uncommitted read when using DB2. This does not apply to parts listed, parts attributes, links listing, or resource content. Using this option can signfiicantly slow performance and introduce deadlocks and "-911" SQL errors. (This option is subject to automatic inclusions when using single-item retrieve depending on the retrieve method used, which can include document parts listing, parts attributes, and resource content (loaded in memory).)
- (deprecated)
java.lang.Exception
- See
DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions)
retrieveObject
- public void retrieveObject(dkDataObject ddo,
- DKNVPair[] optionsDKNVPair)
- throws java.lang.Exception
See
DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions)
Beyond the
retrieve documentation
referenced above...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.
retrieveObject
in interface dkDatastore
retrieveObject
in class dkAbstractDatastore
ddo
- Any valid DB2 Content Manager V8 DDO representing a root component, child component, or document part.
Valid DDO instances are typically obtained through the following sources.
- Returned through query or search (
evaluate()
execute()
- Retrieved under other valid DDOs through previous retrieve calls.
- Created using
DKDatastoreICM::createDDO(
...)
methods (createDDOFromPID(DKPidICM)
createDDOFromPID(pidString)
createDDO(itemType,semanticType)
createChildDDO(itemType,childType)
optionsDKNVPair
- 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)
(above).
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 referenced above.
java.lang.Exception
- See
DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions)
retrieveObjects
- public void retrieveObjects(dkCollection ddoColl,
- DKNVPair[] optionsDKNVPair)
- throws java.lang.Exception
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 retreive 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.
Multi-Item Retrieve
(RECOMMENDED)
Indirectly Uses Multi-Item Retrieve
DKDatastoreICM::evaluate(String queryString, short queryLanguageID, DKNVPair[] queryOptions)
DKDatastoreICM::execute(String queryString, short queryLanguageID, DKNVPair[] queryOptions)
DKDatastoreICM::executeWithCallback(String queryString, short queryLanguageID, DKNVPair[] queryOptions)
DKDatastoreICM::retrieveObject(DKDDO,DKNVPair[] retrieveOptions
DKDDO::retrieve(DKNVPair[] retrieveOptions)
DKLobICM::retrieve(DKNVPair[] retrieveOptions)
- ...and other
DKDDO
DKLobICM
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 desired. 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 communiccation, 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
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 varients 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.
- Create an instance using
DKRetrieveOptionsICM.createInstance()
createInstance()
- Pass an instance using
DKRetrieveOptionsICM.dkNVPair()
dkNVPair()
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 undesired options to 'false' since 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 varients. 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 optoins,
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
SItemRetrievalICM
SResourceItemRetrievalICM
SDocModelItemICM
SSearchICM
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 succees 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.
retrieveObjects
in interface dkDatastore
retrieveObjects
in class dkAbstractDatastore
ddoColl
- Collection of DDOs to be retrieved. Any collection implementing the
dkCollection
interface is accepted, provided it contains valid
DKDDO
instances
for DB2 Content Manager V8. 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
. provided or your
Valid DDO instances are typically obtained through the following sources.
- Returned through query (or search).
- Retrieved under other valid DDOs through previous retrieve calls.
- Created using
DKDatastoreICM::createDDO(
...)
methods.
optionsDKNVPair
- 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)
(above).
It is easy to create and pass a
DKRetrieveOptionsICM
instance to any retrieve method supporting the DKNVPair
[]
retrieve option interface.
- Create an instance using
DKRetrieveOptionsICM.createInstance()
createInstance()
- Pass an instance using
DKRetrieveOptionsICM.dkNVPair()
dkNVPair()
An example is provided in the "
Retrieve Options (STRONGLY RECOMMENDED)
"
section mentioned above.
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 supported name-value pairs described below.
DKConstant.DK_CM_PARM_RETRIEVE = <
DKRetrieveOptionsICM
instance>
[Recommended] Already described above.
- (deprecated)
DKConstant.DK_CM_PARM_RETRIEVE = <Integer instance>
[Deprecated and not recommended]. UseDKRetrieveOptionsICM
DKRetrieveOptionsICM
Retrieve Options
" section of method(STRONGLY RECOMMENDED)
DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] retrieveOptions)
int
option values in anInteger
object. For deprecated bitwise values, seeDKDatastoreICM::retrieveObjects(dkCollection,int bitwiseRetrieveOptionsInt
- (deprecated)
DKConstant.DK_CM_PARM_PROJECTION_LIST = <DKNVPair[] instance>
[Deprecated and not recommended]. Use integratedDKProjectionListICM
DKRetrieveOptionsICM::attributeFilters(DKProjectionListICM)
DKNVPair[]
form of a projection list.
DeprecatedDKNVPair[]
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 aDKNVPair
where theDKNVPair
name is the name of the item type and the value is adkCollection
ofString
objects contianing the "qualified" attribute names (including child component type steps) projected for that item type. All item type projections are combined into oneDKNVPair[]
to be passed as the value to the retrieve optionsDKNVPair[]
.
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 methodDKAttrDefICM.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:DKConstantICM.DK_ICM_ALL_ATTRS
Include all attributes (both system-defined and user-defined) should be returned for the component type identified by the preceding "qualified" type information.DKCosntantICM.DK_ICM_SYSTEM_ATTRS
Only system attributes (or properties) should be returned for the component type identified by the preceding "qualified" type information.
Restrictions:- No holes in the projection list are allowed.
- You must specify projections in terms of the root item type, regardless of what child component is to be retrieved.
Projection lists are significantly improved through the integratedDKProjectionListICM
DKRetrieveOptionsICM::attributeFilters(DKProjectionListICM)
DKException
- Exceptions are reported if errors are detected. For some information on specific exceptions, see
DKRetrieveOptionsICM
documentation.
java.lang.Exception
- A few
java.lang.Exception
objects can be
propagated in rare cases from other libraries. However,
DB2 Content Manager V8 does not throw new exceptions
that are not at least of subclass DKException
and catches most java.lang.Exception
errors
and rethrows as DKException
instances. updateObject
- public void updateObject(dkDataObject ddo)
- throws DKException
- java.lang.Exception
Note that the DKConstantICM.DK_ICM_PROPERTY_PARENT_FOLDER
property
may not be modified or added to a DDO before calling updateObject(). If this property is modified or added,
an exception will be thrown. To change the parent of an item, use the
method.
DKDatastoreExtICM::moveToFolder(childItem, oldFolder, newFolder)
updateObject
in interface dkDatastore
updateObject
in class dkAbstractDatastore
ddo
- Root component DDO for the item version to be updated. DKException
- if a problem is encountered. java.lang.Exception
updateObject
- public void updateObject(dkDataObject ddo,
- int option)
- throws DKException
- java.lang.Exception
Note that the DKConstantICM.DK_ICM_PROPERTY_PARENT_FOLDER
property
may not be modified or added to a DDO before calling updateObject(). If this property is modified or added,
an exception will be thrown. To change the parent of an item, use the
method.
DKDatastoreExtICM::moveToFolder(childItem, oldFolder, newFolder)
updateObject
in interface dkDatastore
updateObject
in class dkAbstractDatastore
ddo
- Root component DDO for the item version to be updated. option
- -
The update options. Valid values are:
-
DK_CM_CHECKIN (8192)
:
check the item in after update. The default is not to check in the item. -
DK_CM_VERSION_LATEST (256)
:
update the latest version rather than the specific version identified in the PID that the current DKDDO represents. -
DK_CM_VERSION_NEW (2)
:
create a new version of this item. This is applicable only if the version control on the item type is set to version the item or to application controlled. If this is not the case, the item is updated and no error is returned but a new version is not created. -
DK_ICM_NO_LINKS_MEMORY_CURRENCY (32)
:
This option tells the API not to update referenced DDOs, in memory, to reflect newly added links. This option is very useful when adding a large number of links. Without this option, newly added links will be made persistent and the API will reflect these links in all referenced DDOs. With this option the links are still made persistent, however referenced DDOs are not updated to include this new link information. This option may be used to improve performance when an application does not require the information in the referenced DDOs to be updated. Even though this information will not be reflected in the referenced DDOs, the application can still call retrieve on these DDOs to get the latest links information when/if it is needed. -
DK_ICM_NO_ERROR_FOR_DUP_OR_NOT_FOUND_LINKS (64)
: Ignore any duplicate links (or folder relationships) added for any links that already exist in the system and ignore any delete link requests for links that have already been deleted. This allows you to add as many links as you desire without the need to retrieve and compare against the current links in memory and save the item with the intent that the submitted links should exist in the system. Similarly you can remove links without the need to verify that it was not already deleted by another request. For more details, refer to the documentation provided with constantDKConstantICM.DK_ICM_NO_ERROR_FOR_DUP_OR_NOT_FOUND_LINKS
.
DKException
- if a problem is encountered java.lang.Exception
- if a problem is encountered deleteObject
- public void deleteObject(dkDataObject ddo)
- throws DKException
- java.lang.Exception
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 on this, see:
.
DKDatastoreICM::getRootFolder()
deleteObject
in interface dkDatastore
deleteObject
in class dkAbstractDatastore
ddo
- the root component DDO for the item version to be deleted from this datastore. DKException
- if a problem is encountered. java.lang.Exception
deleteObject
- public void deleteObject(dkDataObject ddo,
- int option)
- throws DKException
- java.lang.Exception
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 on this, see:
.
DKDatastoreICM::getRootFolder()
deleteObject
in interface dkDatastore
deleteObject
in class dkAbstractDatastore
ddo
- the root component DDO for the item version to be deleted from this datastore. option
- delete option:
-
0
(zero) default - Perform a regular delete, deleting the item version represented by this DDO. -
DKConstantICM.DK_ICM_DELETE_ALL_VERSIONS
- Delete all versions of the item. -
DKConstant.DK_CM_DESTROY_DELETE
- Irrecoverably destroy associated content while deleting it. This option is presently only supported for the ICM connector -
DKConstantICM.DK_ICM_DESTROY_ALL_VERSIONS
- Irrecoverably destroy associated content for all versions while deleting it. This option is presently only supported for the ICM connector DK_ICM_NO_LINKS_MEMORY_CURRENCY ( 32):
This option tells the API not to update referenced DDOs, in memory, to reflect newly deleted links. This option is very useful when deleting a large number of links. Without this option, newly deleted links will not be reflected these links in all referenced DDOs. even those links have been removed from the persistent datastore. This option may be used to improve performance when an application does not require the information in the referenced DDOs to be updated. Even though this information will not be reflected in the referenced DDOs, the application can still call retrieve on these DDOs to get the latest links information when/if it is needed.DK_ICM_NO_ERROR_FOR_DUP_OR_NOT_FOUND_LINKS (64)
: Ignore any duplicate links (or folder relationships) added for any links that already exist in the system and ignore any delete link requests for links that have already been deleted. This allows you to add as many links as you desire without the need to retrieve and compare against the current links in memory and save the item with the intent that the submitted links should exist in the system. Similarly you can remove links without the need to verify that it was not already deleted by another request. For more details, refer to the documentation provided with constantDKConstantICM.DK_ICM_NO_ERROR_FOR_DUP_OR_NOT_FOUND_LINKS
.
DKException
- if a problem is encountered. java.lang.Exception
deleteObjects
- public void deleteObjects(dkCollection ddoCollection)
- throws DKException
- java.lang.Exception
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 on this, see:
.
DKDatastoreICM::getRootFolder()
deleteObjects
in interface dkDatastore
deleteObjects
in class dkAbstractDatastore
ddoCollection
- - 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. DKException
- if a problem is encountered. java.lang.Exception
deleteObjects
- public void deleteObjects(dkCollection ddoCollection,
- int option)
- throws DKException
- java.lang.Exception
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 on this, see:
.
DKDatastoreICM::getRootFolder()
deleteObjects
in interface dkDatastore
deleteObjects
in class dkAbstractDatastore
ddoCollection
- - 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. option
- delete option:
-
0
(zero) default - Perform a regular delete, deleting the item version represented by this DDO. -
DKConstantICM.DK_ICM_DELETE_ALL_VERSIONS
- Delete all versions of the item. -
DKConstant.DK_CM_DESTROY_DELETE
- Irrecoverably destroy associated content while deleting it. This option is presently only supported for the ICM connector
DKException
- if a problem is encountered. java.lang.Exception
moveObject
- public void moveObject(dkDataObject ddo,
- java.lang.String destinationItemType)
- throws DKException
- java.lang.Exception
When moving an item to a hierarchical item type, we must 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 already 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()
.
WARNING:
- In the current implementation, the source data object and all of its versions will be deleted after a successful move.
- Since child component names are unique under a given schema instance, this method can not move the child components associated with this root, if any. Therefore, when the source item is deleted at the end of a successful move, all its child components will be deleted too.
moveObject
in interface dkDatastoreIntICM
ddo
- the data-object to be moved destinationItemType
- the destination item type to move this data-object to. DKException
- if a problem is encountered java.lang.Exception
- if a problem is encountered moveObject
- public void moveObject(dkDataObject sourceDDO,
- dkDataObject destinationDDO,
- int options)
- throws DKException
- java.lang.Exception
When moving an item to a hierarchical item type, we must 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 already 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()
.
WARNING:
- In the current implementation, the source data object and all of its versions will be deleted after a successful move.
- Since child component names are unique under a given schema instance, this method can not move the child components associated with this root, if any. Therefore, when the source item is deleted at the end of a successful move, all its child components will be deleted too.
moveObject
in interface dkDatastoreIntICM
sourceDDO
- the data-object to be moved destinationDDO
- the template of destination data-object options
- valid options are
- DK_CM_CHECKIN : the default is not to checkin the item.
- DK_CM_VERSION_NEW : the default is not to create a new version. This option has some limitations, it is applicable to non resource item only. If specified, the version number of the item will be incremented by one, regardless of the version control of the item type.
- DK_CM_KEEP_IN_AUTOFOLDER : the default is to remove from the current auto folder.
DKException
- if a problem is encountered java.lang.Exception
- if a problem is encountered commit
- public void commit()
- throws DKException
- java.lang.Exception
rollback
- public void rollback()
- throws DKException
- java.lang.Exception
isConnected
- public boolean isConnected()
isConnected
in interface dkDatastore
isConnected
in class dkAbstractDatastore
datastoreName
- public java.lang.String datastoreName( )
- throws java.lang.Exception
datastoreName
in interface dkDatastore
datastoreName
in class dkAbstractDatastore
java.lang.Exception
datastoreType
- public java.lang.String datastoreType( )
- throws java.lang.Exception
datastoreType
in interface dkDatastore
datastoreType
in class dkAbstractDatastore
java.lang.Exception
connection
- public DKHandle connection()
- throws java.lang.Exception
connection
in interface dkDatastore
connection
in class dkAbstractDatastore
java.lang.Exception
handle
- public DKHandle handle(java.lang.String type)
- throws java.lang.Exception
type
- type of datastore handle wanted.
Hande Types DK_ICM_CONNECT_HANDLE
java.lang.Exception
userName
- public java.lang.String userName( )
- throws java.lang.Exception
java.lang.Exception
listDataSources
- public dkCollection listDataSources( )
- throws DKException
- java.lang.Exception
listDataSources
in interface dkDatastore
listDataSources
in class dkAbstractDatastore
DKException
- if a problem is encountered. java.lang.Exception
listDataSourceNames
- public java.lang.String[] listDataSourceNames( )
- throws DKException
- java.lang.Exception
listDataSourceNames
in interface dkDatastore
listDataSourceNames
in class dkAbstractDatastore
DKException
- if a problem is encountered. java.lang.Exception
listEntities
- public dkCollection listEntities( )
- throws DKException
- java.lang.Exception
listEntities
in interface dkDatastore
listEntities
in class dkAbstractDatastore
DKException
- if an error occurs. java.lang.Exception
listEntityNames
- public java.lang.String[] listEntityNames( )
- throws DKException
- java.lang.Exception
listEntityNames
in interface dkDatastore
listEntityNames
in class dkAbstractDatastore
DKException
- if an error occurs. java.lang.Exception
listEntityAttrs
- public dkCollection listEntityAttrs( java.lang.String entityName)
- throws DKException
- java.lang.Exception
listEntityAttrs
in interface dkDatastore
listEntityAttrs
in class dkAbstractDatastore
entityName
- the name of the entity that owns the attributes. DKException
- if the entity name does not exist. java.lang.Exception
listEntityAttrNames
- public java.lang.String[] listEntityAttrNames( java.lang.String entityName)
- throws DKException
- java.lang.Exception
listEntityAttrNames
in interface dkDatastore
listEntityAttrNames
in class dkAbstractDatastore
entityName
- name of the entity that owns the attributes. DKException
- if the entity name does not exist. java.lang.Exception
datastoreDef
- public dkDatastoreDef datastoreDef( )
- throws DKException
- java.lang.Exception
datastoreDef
in interface dkDatastore
datastoreDef
in class dkAbstractDatastore
DKException
- if a problem is encountered. java.lang.Exception
registerMapping
- public java.lang.String registerMapping( DKNVPair sourceMap)
- throws DKException
- java.lang.Exception
registerMapping
in interface dkDatastore
registerMapping
in class dkAbstractDatastore
sourceMap
- - source name and mapping information. The name part of the NVPair specifies the source of mapping information. A string literal "SCHEMA" indicates that the mapping informaiton is provided in the value part in form of schema mapping object. DKException
- if a problem is encountered. java.lang.Exception
unRegisterMapping
- public void unRegisterMapping(java.lang.String mappingName)
- throws DKException
- java.lang.Exception
unRegisterMapping
in interface dkDatastore
unRegisterMapping
in class dkAbstractDatastore
mappingName
- - the name of the mapping information. DKException
- if a problem is encountered. java.lang.Exception
listMappingNames
- public java.lang.String[] listMappingNames( )
- throws DKException
- java.lang.Exception
listMappingNames
in interface dkDatastore
listMappingNames
in class dkAbstractDatastore
DKException
- if a problem is encountered. java.lang.Exception
getMapping
- public dkSchemaMapping getMapping( java.lang.String mappingName)
- throws DKException
- java.lang.Exception
getMapping
in interface dkDatastore
getMapping
in class dkAbstractDatastore
mappingName
- - the name of the schema mapping information. DKException
- if a problem is encountered. java.lang.Exception
getExtension
- public dkExtension getExtension( java.lang.String extensionName)
- throws DKException
- java.lang.Exception
DKDatastoreExtICM dsExtICM = (DKDatastoreExtICM) dsICM.getExtension (DK_CM_DATASTORE_EXT);
getExtension
in interface dkDatastore
getExtension
in class dkAbstractDatastore
extensionName
- Name of the extension object to be retrieved. For the DKDatastoreExtICM object, use DK_CM_DATASTORE_EXT. DKException
- if a problem is encountered. java.lang.Exception
extension methods]
addExtension
- public void addExtension(java.lang.String extensionName,
- dkExtension extensionObj)
- throws DKException
- java.lang.Exception
addExtension
in interface dkDatastore
addExtension
in class dkAbstractDatastore
extensionName
- - the name of new extension object. extensionObj
- - the extension object to be added. DKException
- if a problem is encountered. java.lang.Exception
extension methods]
removeExtension
- public void removeExtension(java.lang.String extensionName)
- throws DKException
- java.lang.Exception
removeExtension
in interface dkDatastore
removeExtension
in class dkAbstractDatastore
extensionName
- - name of extension object to be removed. DKException
- if a problem is encountered. java.lang.Exception
extension methods]
listExtensionNames
- public java.lang.String[] listExtensionNames( )
- throws DKException
- java.lang.Exception
listExtensionNames
in interface dkDatastore
listExtensionNames
in class dkAbstractDatastore
DKException
- if a problem is encountered. java.lang.Exception
extension methods]
createDDO
- public DKDDO createDDO(java.lang.String itemTypeViewName,
- int semanticType)
- throws DKException
- java.lang.Exception
DKDDO
structure, which allows for easier and greater functionality,
such as Resources, DB2 Content Manager document model, and folders. The DDO
returned will have the appropriate properties and attributes setup 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.
- DKDDO properties, including but not limited to "semantic type" and "item type property".
- DKDDO data items for attributes (initialized with NULL or default value if exists)
- Creation of empty child collections for all sub-entity types.
- Creation of empty DKParts coll for "document" classified item types.
- Creation of empty DKFolder coll for root components specified with semantic type "Folder".
Resource Items
The Item Type Definition determines what type of DDO is created. If it is a resource, the correct XDO will be returned, depending on the XDO Class specified in the Item Type Definition. The returned DDO may be cast to the correct structure, since will be setup correctly according to the Item Type Definition. For more information, please refer to the "Returns" documentation.
Item Property Types
An Item or DDO must have a generic "type" property associated with it. This generic type of the DDO is Document, Folder, or Item. When creating Items, the Item Property is specified through the second parameter of the datastore's createDDO function mixed in with the semantic type. 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.
This 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 which fully describes the item structure and settings.
Available Item Property Types: Item Property Constant Definition ------------- -------------- ------------------------------------------------------ Document DK_CM_DOCUMENT Item generically represents a document. This can be considered a "common document" since it does not rigidly mean an implementation of a specific document model. This does not necessarily mean a document with parts using the DB2 Content Manager V8 "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 utilizing the DKFolder mechanism. However, this value does not necessarily mean that a solution utilizes 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. -------------------------------------------------------------------------------------- Note: Constants available in com.ibm.mm.sdk.common.DKConstant.Semantic Type
When creating items, a semantic type can be specified as the second parameter of the datastore's createDDO function. A semantic type in general is a metaphor for an item. Semantic types are primarily a feature for application use and are typically not enforced or especially meaningful within the DB2 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 DB2 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.
Available Semantic Types: Semantic Type Constant Definition ------------- ---------------- ------------------------------------------------------ <Any> <User Specified> CreateDDO will assign any value specified to the semantic type value. Since applications can enforce semantics as they wish, no values are disallowed, except for item types classified as "document" (document model). ........................................................................................ Document DK_ICM_SEMANTIC_ Item generically represents a document. TYPE_DOCUMENT This can be considered a "common document" since it does not rigidly mean an implementation of a specific document model. This does not necessarily mean a document with parts using the DB2 Content Manager V8 "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_ Item represents a folder that can contain other items. TYPE_FOLDER 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 utilizing the DKFolder mechanism. However, this value does not necessarily mean that a solution utilizes 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_ Item represents a generic container or generic item. TYPE_CONTAINER 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_ Alleged to most nearly resemble document part of type TYPE_BASE "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. Do 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. ........................................................................................ Annotation DK_ICM_SEMANTIC_ Same as BASE (See "Base" documentation for details) TYPE_ANNOTATION except alleged to most nearly resembles "ANNOTATION". ........................................................................................ History DK_ICM_SEMANTIC_ Same as BASE (See "Base" documentation for details) TYPE_HISTORY except alleged to most nearly resembles "HISTORY". ........................................................................................ Note DK_ICM_SEMANTIC_ Same as BASE (See "Base" documentation for details) TYPE_NOTE except alleged to most nearly resembles "NOTE". ........................................................................................ <User Defined> <User Defined> A User Defined Semantic Type. Please refer to the Semantic Type Samples for more information. ---------------------------------------------------------------------------------------- Note: Constants available in com.ibm.mm.sdk.common.DKConstantICM.
Default Type and Default Value
Based on DKAttrDefICM.getDefaultType() & getDefaultValue() Depending on the "Default Type", the "Default Value" will be applied in the following manner.:
Default Type Constant Application of Default Value ------------ ------------------------------ ---------------------------------------- Undefined DK_ATTR_TYPE_DEFAULT_UNDEFINED Default Value Ignored. Regardless of what the Default Value is set to, the attribute is considered to have no default value based on default type. ...................................................................................... String DK_ATTR_TYPE_DEFAULT_STRING Regardless of whether the attribute is defined as nullable or not, the default value will be considered as a String representation of the value and will be converted to the correct type, depending on the attribute type and set as the default value. ...................................................................................... Float DK_ATTR_TYPE_DEFAULT_FLOAT If attribute type is a float, the default value will be converted to a float object and set as the default value. If the attribute type takes a String, it will be set as the string. Otherwise it will be ignored if not applicable for that attribute type. ...................................................................................... Decimal DK_ATTR_TYPE_DEFAULT_DECIMAL If attribute type is a float, the default value will be converted to a decimal object and set as the default value. If the attribute type takes a String, it will be set as the string. Otherwise it will be ignored if not applicable for that attribute type. ...................................................................................... Integer DK_ATTR_TYPE_DEFAULT_INTEGER If attribute type is numeric, the default value will be converted to that type and set as the default value. If the attribute type takes a String, it will be set as the string. Otherwise it will be ignored if not applicable for that attribute type. ...................................................................................... Hex String DK_ATTR_TYPE_DEFAULT_HEXSTRING This will be considered a string containint a hexidecimal numeric value. If attribute type is numeric, the default value will be converted to that type and set as the default value. If the attribute type takes a String, it will be set as the string. Otherwise it will be ignored if not applicable for that attribute type. ...................................................................................... Other DK_ATTR_TYPE_DEFAULT_OTHER If the attribute is not nullable (required), it will be converted to the correct type depending on the attribute type. If the attribute is nullable, the Default Value will be ignored & not set. -------------------------------------------------------------------------------------- Note: Constants defined in DKAttrDefICM Special Case Considerations: Default Value Attr Type Default Value Set To ----------------- --------- -------------------- "" (Empty String) Numeric 0 Date Current Date Time Current Time Timestamp Current Timestamp --------------------------------------------------
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 setup any other necessary information
within the DDOs in order to function correctly with other operations.
itemTypeViewName
- the object type you want to create semanticType
- 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.
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.
DKException
- (or subclass) Thrown if errors are detected such as the following:
- The Item Type name given does not exist in this datastore.
- The Semantic Type specified is incompatible with the Item Type specified.
- Child Component Type name specified instead of a Root Item Type name.
- Other Usage Errors
java.lang.Exception
- A few
java.lang.Exception
objects can be
propagated in rare cases from other libraries. However,
DB2 Content Manager V8 does not throw new exceptions
that are not at least of subclass DKException
and catches most java.lang.Exception
errors
and rethrows as DKException
instances.
createDDO
- public DKDDO createDDO(java.lang.String pidString,
- boolean initializeMetadataStructures)
- throws DKException
- DKUsageError
- java.lang.Exception
createDDOFromPID(String pidString)
which defaults to the recommended option setting (FALSE).
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:
- Attributes are initialized default values and do not reflect actual values in the persisted item.
- Properties such as semantic type, ACL, and Records Enabled are not accurate until properly retrieved.
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)
.
createDDO
in interface dkDatastoreIntICM
initializeMetadataStructures
- If requested (TRUE), pre-fill the DDO with the following. If set to FALSE, do *NOT* pre-fill with the following.
- DKDDO properties, including but not limited to "semantic type" and "item type property". (See "WARNING")
- DKDDO data items for attributes (initialized with NULL or default value if exists)
- Creation of empty child collections for all sub-entity types.
- Creation of empty DKParts coll for "document" classified item types.
- Creation of empty DKFolder coll for root components specified with semantic type "Folder".
- 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 desired in order 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)
- For
createDDO()
andcreateChildDDO()
methods without this parameter, this setting defaults to TRUE in C++ and FALSE in Java. Note that for recreated DDOs from PIDs, FALSE is strongly recommended. - For
createDDOFromPID()
methods in either C++ or Java, this setting defaults to FALSE which is strongly recommended for recreating from a PID.
Note that if initializing metadata structures through a method that recreates a DDO for an existing item from a PID object or PID string:
- Attributes are initialized default values and do not reflect actual values in the persisted item.
- Properties such as semantic type, ACL, and Records Enabled are not accurate until properly retrieved.
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)
.
createDDOFromPID(String pidString)
.
However, returned DDO might include initialized metadata structures depending
on the 'initializeMetadataStructures
' parameter to this method.
createDDOFromPID
- public DKDDO createDDOFromPID(java.lang.String pidString)
- throws DKException
- DKUsageError
- java.lang.Exception
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 may be cast to the correct structure, since will be setup correctly according to the Item Type Definition. For more information, please refer to the "Returns" documentation.
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.
createDDOFromPID
in interface dkDatastoreIntICM
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.
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.
java.lang.Exception
- A few
java.lang.Exception
objects can be
propagated in rare cases from other libraries. However,
DB2 Content Manager V8 does not throw new exceptions
that are not at least of subclass DKException
and catches most java.lang.Exception
errors
and rethrows as DKException
instances.
createDDO
- public DKDDO createDDO(java.lang.String pidString)
- throws DKException
- DKUsageError
- java.lang.Exception
createDDOFromPID(String pidString)
.
createDDOFromPID(String pidString)
.
See
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: - The new name eliminates ambiguities caused by similar parameter types for creating new component DDOs and recreating DDOs from PID strings that can cause accidental usage of the incorrect method when the compiler chooses the nearest signature to match the types actually passed.
- The new name eliminates easily encountered compile errors due to ambiguous parameter types that could be encountered when attempting to use additional parameters that control behavior.
- All new and remaining non-deprecated methods use the recommended
behavior for blank DDOs or initializing metadata structures by default.
All methods that assumed default behavior that was not recommended
(in Java or C++) were deprecated. See section
"Blank DDOs versus Initialized Metadata Structures" in
createDDOFromPID(String pidString)
- All methods with behavior options that could possibly be used to request
behavior that is not recommended are deprecated and should not be used
to avoid any confusion or mistake that could enable usage that is not recommended.
Prior to the new
createDDOFromPID(
...)
methods, the originalcreateDDO(
...)
methods with boolean behavior options for blank DDOs or initializing metadata structures might have been used to ensure recommended choices. However, with the deprecation and new methods, simply use any non-deprecated method and the optimal behavior is now used. You no longer have to remember to use the correct choice. See the detailed explanation and recommendations for the original documentation for parameter 'initializeMetadataStructures
createDDO(String pidString, boolean initializeMetadataStructures)
- Most importantly, unlike Java, the default C++ behavior of
createDDO(DKPidICM)
andcreateDDO(String pidString)
initialized metadata structures rather than returning blank DDOs and is not recommended. In order to simplify usage and avoid incorrect signatures from accidentally being used (or easily encountered compile errors due to ambiguous type conversions), the methods to recreate DDOs from PIDs are renamed for easier usability and more intuitive usage.
See section "Blank DDOs versus Initialized Metadata Structures" and subsection "WARNING for C++" increateDDOFromPID(String pidString)
createDDO
in interface dkDatastoreIntICM
java.lang.Exception
createDDO
- public DKDDO createDDO(DKPidICM pid,
- java.lang.String[] fedAttributeList)
- throws DKException
- DKUsageError
- java.lang.Exception
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 DB2 Content Manager V8 connector, use
createDDOFromPID(DKPidICM)
.
pid
- Same as '
pid
' parameter in createDDOFromPID(DKPidICM)
However, this DDO should have a 3-part object type containing
federation mapping.
fedAttributeList
- An array of federated attribute names.
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.
createDDOFromPID
- public DKDDO createDDOFromPID(DKPidICM pid)
- throws DKException
- DKUsageError
- java.lang.Exception
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)
createDDOFromPID
in interface dkDatastoreIntICM
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.
java.lang.Exception
createDDO
- public DKDDO createDDO(DKPidICM pid)
- throws DKException
- DKUsageError
- java.lang.Exception
createDDOFromPID(DKPidICM)
.
createDDOFromPID(DKPidICM)
.
See
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)
.
createDDO
in interface dkDatastoreIntICM
createDDO
- public DKDDO createDDO(DKPidICM pid,
- boolean initializeMetadataStructures)
- throws DKException
- DKUsageError
- java.lang.Exception
createDDOFromPID(DKPidICM)
which defaults to the recommended option setting (FALSE).
createDDOFromPID(DKPidICM)
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(DKPidICM)
.
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:
- Attributes are initialized default values and do not reflect actual values in the persisted item.
- Properties such as semantic type, ACL, and Records Enabled are not accurate until properly retrieved.
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)
.
createDDO
in interface dkDatastoreIntICM
initializeMetadataStructures
- Same as '
initializeMetadataStructures
' parameter in createDDO(String pidString, boolean initializeMetadataStructures)
createDDOFromPID(String pidString)
.
However, returned DDO might include initialized metadata structures depending
on the 'initializeMetadataStructures
' parameter to this method.
createChildDDO
- public DKDDO createChildDDO(java.lang.String itemTypeViewName,
- java.lang.String childTypeViewName)
- throws DKException
- java.lang.Exception
DKDDO
structure, which
allows for easier and greater functionality. The DDO returned will have the appropriate
properties and attributes setup 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.
- DKDDO properties, if any apply for this child type.
- DKDDO data items for attributes (initialized with NULL or default value if exists)
- Creation of empty child collections for all sub-entity types.
- DKDDO properties that apply only to root components, including but not limited to "semantic type", "item type property", ACL, Records Enabled, etc.
- Creation of empty DKParts coll for "document" classified item types.
- Creation of empty DKFolder coll for root components specified with semantic type "Folder".
DDO Constructors Not Recommended
See section "DDO Constructors Not Recommended" in method
createDDO(String itemType, int semanticType)
.
createChildDDO
in interface dkDatastoreIntICM
itemTypeViewName
- Name of the item type (root component) or item type view
that the child type is defined within. This is the same name
as the root component type. Always specify the overall item
type view name regardless of the depth
of the child type within the item type hierarchy.
childTypeViewName
- Name of the child component type or view for which you
want to create a DDO.
DKDDO
and are
not sub-classed further (unlike root components).
java.lang.Exception
- A few
java.lang.Exception
objects can be
propagated in rare cases from other libraries. However,
DB2 Content Manager V8 does not throw new exceptions
that are not at least of subclass DKException
and catches most java.lang.Exception
errors
and rethrows as DKException
instances.
destroy
- public void destroy()
- throws DKException
- java.lang.Exception
startTransaction
- public void startTransaction()
- throws DKException
- java.lang.Exception
startTransaction
in interface dkDatastore
startTransaction
in interface dkDatastoreIntICM
startTransaction
in class dkAbstractDatastore
validateConnection
- public short validateConnection( )
- throws DKException
- java.lang.Exception
validateConnection
in interface dkDatastore
validateConnection
in class dkAbstractDatastore
The return values are:
- 0: OK
- 1: connection is invalid
- 2: no connection exist
- 3: unknown (for connectors can't do validation)
java.lang.Exception
checkIn
- public void checkIn(dkDataObject item)
- throws DKException
- java.lang.Exception
checkIn
in interface dkDatastoreIntICM
item
- Root component DDO for the item to check in (unlock). DKException
- if a problem is encountered. java.lang.Exception
checkOut
- public void checkOut(dkDataObject item)
- throws DKException
- java.lang.Exception
checkOut
in interface dkDatastoreIntICM
item
- Root component DDO for the item to be checked out (locked). DKException
- if a problem is encountered. java.lang.Exception
writeEvent
- public void writeEvent(DKEventDefICM aEvent)
- throws DKException
- java.lang.Exception
aEvent
- a DKEventDefICM object to be written to the event log. DKException
- if a problem is encountered. java.lang.Exception
listEvents
- public dkCollection listEvents( java.lang.String itemId,
- short maxResults)
- throws DKException
- java.lang.Exception
itemId
- an item id . maxResults
- the maxium number of DKEventDefICM objects to be returned in the collection. DKException
- if a problem is encountered. java.lang.Exception
listContentViewEvents
- public dkCollection listContentViewEvents( java.lang.String[] userIds,
- DKTimestamp from,
- DKTimestamp to,
- int maxResults,
- int startAtRow,
- int options)
- throws DKException
- java.lang.Exception
It is important to remember that audit events for the resource manager views must be turned on in the server for these events to be stored. If these audit events are not on, this method will never return any results. These may be turned on in the System Administration client in the Logging tab of the item type properties.
The 'to' and 'from' timestamps are assumed to be in GMT. Keep this in mind when passing in these parameters.
If maxResults is set to a value 0 or less, this is treated as having no maximum number of results. In this case all results are returned. Likewise passing in 0 or less for startAtRow will start at the first result.
The maxResults and startAtRow parameters may be used to implement a simple form of paged results. If you want to retrieve multiple pages of size 100, you could start with a startRow of 0 and a maxResults of 100. This gives the first 100 events that match the other criteria. To get the next page, you set the startRow to 100, and maxResults to 100 to get the next 100. As a new query is run each time this method is called, the pages may not be totally consistent. For example, if database maintanence cleans up some old events, the result from page to page will be inconistent. As oldest events are returned first, order should stay consistent as long as events are not deleted.
Options may be used to control how the server executes this request and what information is returned. Currently the only option supported is to return only records. Each option is a bit in the integer, so, they may be added together to specify multiple options. If options is set to DKConstantICM.DK_ICM_EVENT_OPTION_RECORDS_ONLY, then only records are returned.
Note that the itemID and versionID, in the event could be part itemID or the document itemId depending whether the item is a document model item or a resource item. For a document model item, the event would have the part itemID in this field, as this is an operation on the part. For resource items, this is always the itemID of the resource item itself. For document model items, the document itemID and versionId may be found in event data 2 and event data 3.
userIds
- a list of userids for which the events are needed from
- a timestamp that determines the start of the time interval for which events are returned to
- a timestamp that determines the end of the time interval for which events are returned maxResults
- the maximum number of events that will be returned (0 for all) startAtRow
- the row to start the results at, setting this to 100 would return results starting with the 100th row. options
- bit options to control what is returned. See above for details. DKException
- If the library server does not support this operation. Support was added in 8.5 fix pack 3. java.lang.Exception
listAdminEvents
- public dkCollection listAdminEvents( short maxResults)
- throws DKException
- java.lang.Exception
maxResults
- the maxium number of events to retrieve. 0 means no limits. DKException
- if an error occured java.lang.Exception
- if an error occured retrieveEvent
- public dkCollection retrieveEvent( int eventCode,
- short maxResults)
- throws DKException
- java.lang.Exception
eventCode
- the given event code to retrieve the DKEventDefICM object. java.lang.Exception
changePassword
- public void changePassword(java.lang.String userId,
- java.lang.String oldPwd,
- java.lang.String newPwd)
- throws DKException
- java.lang.Exception
dkAbstractDatastore
Note:DKUsageError exception thrown if method is not implemented
changePassword
in interface dkDatastore
changePassword
in class dkAbstractDatastore
userId
- - userid oldPwd
- - old password newPwd
- - new password java.lang.Exception
retrieveFormOverlay
- public dkXDO retrieveFormOverlay( java.lang.String name)
- throws DKException
- java.lang.Exception
name
- the name of the form overlay object. DKException
- if an error occurs. java.lang.Exception
isGlobalCacheEnabled
- public boolean isGlobalCacheEnabled( )
true
if global cache is enabled,
false
otherwise isUserCacheEnabled
- public boolean isUserCacheEnabled( )
true
if user and global cache are enabled,
false
otherwise textSearchEnabled
- public boolean textSearchEnabled( )
- throws java.lang.Exception
textSearchEnabled
in interface dkDatastoreIntICM
true
if text search is enabled,
false
otherwise java.lang.Exception
getTextSearchEngineTypes
- public dkCollection getTextSearchEngineTypes( )
- throws java.lang.Exception
java.lang.Exception
db2TSWithCtorEnabled
- public boolean db2TSWithCtorEnabled( )
db2TSWithCtorEnabled
in interface dkDatastoreIntICM
true
if the new DB2 Text Search text search feature is enabled,
false
otherwise db2NSEenabled
- public boolean db2NSEenabled()
db2NSEenabled
in interface dkDatastoreIntICM
true
if DB2 NSE text search is enabled,
false
otherwise getTextSearchEngine
- public DKTextIndexTypeICM getTextSearchEngine( )
- DKTextIndexTypeICM.DB2 if index type is DB2 NSE only.
- DKTextIndexTypeICM.ORACLE if index type is ORACLE.
- DKTextIndexTypeICM.DB2TS if index type is DB2 Text Search only. Even if you have coexistence between DB2 NSE and DB2 Text Search, you will still get DKTextIndexTypeICM.DB2TS back.
LDAPEnabled
- public boolean LDAPEnabled()
- throws java.lang.Exception
LDAPEnabled
in interface dkDatastoreIntICM
java.lang.Exception
adminDomainEnabled
- public boolean adminDomainEnabled( )
- throws java.lang.Exception
adminDomainEnabled
in interface dkDatastoreIntICM
java.lang.Exception
platform
- public short platform()
Possible values are:
DKConstantICM.RM_PLATFORM_WIN
(0
): WindowsDKConstantICM.RM_PLATFORM_AIX
(1
): AIXDKConstantICM.RM_PLATFORM_SUN
(2
): SolarisDKConstantICM.RM_PLATFORM_390
(3
): z/OS, OS/390DKConstantICM.RM_PLATFORM_LINUX
(4
): LinuxDKConstantICM.RM_PLATFORM_ISERIES
(5
): iSeries, AS/400DKConstantICM.RM_PLATFORM_HP
(6
): HP-UXDKConstantICM.RM_PLATFORM_SOLARISX86
(7
): Solaris x86DKConstantICM.RM_PLATFORM_HPIA64
(8
): HP-IA64 (64-bit)
NOTE: This listing of values are operating system values within the API and is not necessarily an indication of support for any particular operating system or lack there-of. Refer to product documentation and prerequisite information for supported operation systems.
platform
in interface dkDatastoreIntICM
schemaName
- public java.lang.String schemaName( )
- throws DKException
- java.lang.Exception
schemaName
in interface dkDatastoreIntICM
prefetchObjects
- public dkCollection prefetchObjects( dkCollection prefetchColl,
- DKNVPair[] nvPairs)
- throws DKException
- java.lang.Exception
- DK_CM_DOCUMENT, the document and the TOC of parts should already be retrieved. If the parts TOC is not retrieved, parts are not prefetched. If one of the parts failed to prefetch then an exception is thrown and does not continue to prefetch other parts. Only the parts with content are attempted to prefetched, and ones with no-content are ignored.
- DK_CM_ITEM, and is classified as type resource, item is prefetched.
- DK_CM_ITEM, and is classified as type doc-part, exception is thrown.
- DK_CM_ITEM, and is classified as type non-resource, exception is thrown.
- DK_CM_ITEM, and is a child component, exception is thrown.
nvPairs
- options in the form of name-value pairs:
If one of the following option is specified, it applies to all the items in the collection.
Description of prefetch options:
- Prefetches the object to the staging area. This option is not valid for zOS RM.
Name =DKConstantICM.DK_ICM_STAGE_IT
.
Value = Boolean in string format , "true" or "false". - Prefetches the object Synchronously.
Name =DKConstantICM.DK_ICM_SYNCHRONOUS
.
Value = Boolean in string format , "true" or "false". - Target RM the object to be prefetched to.This option is not valid for zOS RM.
Name =DKConstantICM.DK_ICM_TARGET_RMNAME
Value = Valid RMName in string format.
DKException-
- following are the exceptions thrown:
- If there is no prefetch collection associated with the itemtype.
- If there is RM associated with itemtype is not available.
- If there is prefetchcollection pamar value is null or has zero elements. Following exception is thrown. DKUsageError with errorid= DKMessageIdICM.DK_ICM_MSG_COLLECTION_HAD_NO_VALID_ELEMENTS
- If prefetchColl param value has more than one element. Following exception is thrown. DKException with errorid= DKMessageIdICM.DK_ICM_MSG_FEATURE_NOT_SUPPORTED
java.lang.Exception
getRootFolder
- public DKDDO getRootFolder()
- throws DKException
- java.lang.Exception
When creating an item type, you may specify that the item type is
hierarchical. This is done by using the method:
.
For these hierarchical item types there
are additional constraints and behavior beyond regular item types.
These item types are designed to provide a 'file system like'
hierarchy that can easily be used to create applications that
provide a hierarchical browse model.
DKItemTypeDefICM::setHierarchical(boolean)
Hierarchical items have the following constraints:
- each item must have a parent hierarchical item (besides the root)
- each item can only have a single hierarchical parent
- each item must have a name, represented by the ICM$NAME attribute
- each item's name must be unique inside of its parent's folder
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
and item type to only contain 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 may still be used without restriction, but these do not form hierarchical links.
As a parent folder is required in this model, this must be specified
when creating an item unless the system is configured to use a
default folder. The parent folder is specified on 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 may be configured to allow items to be created in a
hierarchical item type without specifying the parent by setting a
flag in the library server configuration using
.
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 system default folder use the method
DKLSCfgDefICM::setHierarchicalDefaultFolderEnabled(boolean)
The use of the
system default folder is discouraged, though it can be useful when
applications that are not aware of the hierarchical model need to
create items in hierarchical item types.
DKDatastoreICM::getDefaultFolder()
Since a hierarchical parent is required, a new method
is provided to move an item from one folder to another:
.
This method allows hierarchical items to be moved without violating
the parent constraints. This new method may also be used with
non-hierarchical items and provides a method that moves multiple
items at the same time:
DKDatastoreExtICM::moveToFolder(childItem, oldFolder, newFolder)
.
DKDatastoreExtICM::moveToFolder(childItems, oldFolder, newFolder)
The constraints of this model also have 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 it has no hierarchical parent, one must be specified or
the default folder configured as on create. If the item already has
a hierarchical parent, then a new parent cannot be specified. The
name constraint would also be enforced on reindex, so 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 this
would also be an error. For more details see:
.
DKDatastoreICM::moveObject(dkDataObject, dkDataObject, int)
For updating a hierarchical item, a parent may not be specified
using the DKConstantICM.DK_ICM_PROPERTY_PARENT_FOLDER
property as this would result in two parents. Likewise, folder
operations would be 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 delete will be prevented unless the item is not a folder or unless the folder has no children. A folder with children can't be deleted directly as this would cause its children to not have a parent. Delete item does not support deleting all children under a folder (cascade delete), however an applications can implement this.
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:
- A user is reindexing a non-hierarchical item to a hierarchical item type. If this item does not have a hierarchical parent folder, the user provides the hierarchical parent folder as part of the reindex. At the same time, another user is adding the same item into a hierarchical parent folder.
- A user is deleting an empty hierarchical folder while a different user is moving a hierarchical child item from another hierarchical folder to the same empty hierarchical folder. This scenario results in a hierarchical link with a deleted hierarchical parent folder.
DKException
- if a problem occurs
DKException will be throw if library server is not at release 8.4.3
or higher. java.lang.Exception
getDefaultFolder()
,
getName(DKDDO)
,
DKDatastoreExtICM.moveToFolder(dkCollection, dkDataObject, dkDataObject)
,
DKDatastoreExtICM.moveToFolder(dkDataObject, dkDataObject, dkDataObject)
,
DKItemTypeDefICM.setFoldersOnly(boolean)
,
DKItemTypeDefICM.setHierarchical(boolean)
,
DKLSCfgDefICM.setHierarchicalDefaultFolderEnabled(boolean)
,
addObject(dkDataObject, int)
,
deleteObject(dkDataObject, int)
,
moveObject(dkDataObject, dkDataObject, int)
getDefaultFolder
- public DKDDO getDefaultFolder()
- throws DKException
- java.lang.Exception
DKLSCfgDefICM::enableHierarchicalDefaultFolder()
.
For more information on hierarchical item types see:
.
DKDatastoreICM::getRootFolder()
DKException
- if a problem occurs
DKException will be thrown if library server is not at release 8.4.3
or higher. java.lang.Exception
getName
- public java.lang.String getName( DKDDO ddo)
- throws DKException
- java.lang.Exception
This method will work with any DDO. Because only item types that have the name attribute (ICM$NAME) can hold the name value, we must generate the name for items in item types that do not have the name attribute. The following algorithm is used to generate the name, in order of precedence:
- If the DDO specified is an item that has the ICM$NAME attribute in the root component type, return the value of the ICM$NAME attribute.
- If the DDO contains a primary resource, meaning it is a resource item or it is a document model item with at least one part, then the original file name is returned.
- If the item's type has a single representative attribute, then return the value of this attribute.
- If the item type has multiple representative attributes,
choose one of the representative attributes based on the
following preferences:
- first unique representative attribute
- first required representative attribute
- first representative attribute
- If there are not representative attributes, use the first unique user defined attribute in type preference order. Type preference order means that we choose the attribute based on type. The preference order is: VARCHAR, CHAR, other types
- First required user defined attribute in type preference order
- First user defined attribute in type preference order
- If no qualifying attribute, then the ITEMID will be returned.
Note that if the value of the attribute chosen is null, then "[null]" will be returned.
Note that a retrieve call for the item may be made if the information needed to generate the name is not in memory. This is OK 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 CM standardized name attribute
ICM$NAME is always included in the root component type. This
method should always return ICM$NAME value for a hierarchical item.
For more information on hierarchical item types see:
.
DKDatastoreICM::getRootFolder()
ddo
- the item for which the name is desired DKException
- if a problem occurs java.lang.Exception
getLogID
- public java.lang.String getLogID( )
Know user of this class is the DKLogManagerICM.
Although public, this is an undocumented method for use by ICM connector classes only. Use of this method is prohibited except by members of Content Management team.
getUserTraceLevel
- public short getUserTraceLevel( )
Know user of this class is the DKLogManagerICM.
Although public, this is an undocumented method for use by ICM connector classes only. Use of this method is prohibited except by members of Content Management team.
getUserName
- public java.lang.String getUserName( )
Know user of this class is the DKLogManagerICM.
Although public, this is an undocumented method for use by ICM connector classes only. Use of this method is prohibited except by members of Content Management team.
getSessionId
- public java.lang.String getSessionId( )
getLSVersion
- public java.lang.String getLSVersion( )
getAPIVersion
- public java.lang.String getAPIVersion( )
getLSSessionId
- public java.lang.String getLSSessionId( )
clearCache
- public void clearCache(int option)
- throws DKException
- java.lang.Exception
By default global cache is NOT enabled. To enable global cache, the property JavaGlobalCacheEnabled must be set to true in cmbicmcache.ini file. cmbicmcache.ini file is located under %IBMCMROOT%/cmgmt/connectors directory.
At present, the following types of objects are always stored in the datastore's local cache. As mentioned before, objects in the datastore's cache is accessible only to that datastore.
- Item Type
- Component type
- Component Type View
- Item Type View
- Access Control List
- Privilege Set
- User
- User Group
- Resource Manager definitions
If global cache is enabled, the following types of objects are stored in the global area. Otherwise, these are also stored in the datastore's local cache.
- Attribute
- Attribute group
- Event type
- Link type
- XDO classification
- Mime type
- NLS keywords
- Semantic type
- Privilege
- Privilege Group
Environments with multiple DKDatastoreICM instances--especially ones that use mid-tier servers should turn global cache ON. This includes custom applications where the Java API is running in a mid-tier server environment. Applications that use multiple threads--especially mid-tier process threads that repeat the following pattern will benefit from turning global cache ON.
- Connect to DB2 Content Manager.
- Perform an operation (such as run-time CRUD and query or administration/definition time operations).
- Disconnect from DB2 Content Manager.
Enabling global cache improves response times by saving the Java API from repeatedly communicating with the library server to manifest these objects. By enabling global cache, you can consolidate the caches of multiple DKDatastoreICM instances into one global area. This prevents the duplication of identical objects (the ones that are stored in the global cache), and in particular maximizes performance and scalability of a mid-tier environment.
The option argument can be any of the following values -
- DK_CM_CLEAR_CACHE_LOCAL
- DK_CM_CLEAR_CACHE_GLOBAL
- DK_CM_CLEAR_CACHE_ALL
The behavior of this method varies based on
- the value of the option argument and
- global cache being enabled
DK_CM_CLEAR_CACHE_LOCAL will clear the ojects that reside in the datastore's local cache.
DK_CM_CLEAR_CACHE_GLOBAL will clear the objects that reside in the global cache. If global cache is not enabled and this option is passed, the exception DKUsageError will be thrown with the errorId DK_CM_MSG_BADOPTVALUE.
DK_CM_CLEAR_CACHE_ALL will clear the local cache of datastore and also the global cache. Global cache will be cleared only if it is enabled. Note that if global cache is not enabled, all the cached objects will reside in the datastore's local cache, and will be removed from there.
Note that location of objects in the global or local cache could change in the future. The safest bet for an application is to always pass DK_CM_CLEAR_CACHE_ALL. This will clear all objects that are cached. An application does not have to be concerned about the location of an object in the cache. Also, in the future, if an object that is being cached in the global cache is moved to the local cache (or vice-versa), an application does not have to changes its logic. Also in the future, we may provide options to remove a particular type of object from the cache.
An example where DK_CM_CLEAR_CACHE_LOCAL and DK_CM_CLEAR_CACHE_GLOBAL can be used is a scenario where an application has implemented its own datastore pool. In this situation, if the global cache and the local cache of all the datastore's in the pool need to be cleared, the application implementation should do the following -
- For the first datastore in the pool, clear the local cache of the datastore and global cache by using DK_CM_CLEAR_CACHE_ALL.
- Clear the local cache of all other datastore's in the pool by using DK_CM_CLEAR_CACHE_LOCAL.
This method is available only from Content Manager Version 8.3 Fix Pack 4 release.
clearCache
in interface dkDatastore
clearCache
in class dkAbstractDatastore
option
- clear cache option for selective clearing of cache.
Valid values are DK_CM_CLEAR_CACHE_ALL, DK_CM_CLEAR_CACHE_LOCAL
and DK_CM_CLEAR_CACHE_GLOBAL. DKException
- If option passed in is not one of the following -
DK_CM_CLEAR_CACHE_LOCAL or DK_CM_CLEAR_CACHE_ALL or
DK_CM_CLEAR_CACHE_GLOBAL. This exception is also thrown if
option passed is DK_CM_CLEAR_CACHE_GLOBAL and global cache is not
enabled. java.lang.Exception