com.ibm.mm.sdk.common
Class DKRetrieveOptionsICM
- java.lang.Object
com.ibm.mm.sdk.common.DKRetrieveOptionsICM
- public class DKRetrieveOptionsICM
- extends java.lang.Object
Each method is documented with a detailed explanation, default value used if selection not made, order of precedence considerations, data structures (how to find the data you requested in the DKDDOs), performance considerations, memory management (C++), behavior notes and considerations, and more.
The key principle is granular options based on performance and feature. Data selections are broken up into performance-based groups. Anything that is retrieved relatively for free with other like-kind data is not called out as a separate option, but filters are provided if an application desires extremely granular control. Then, for anything that costs additional performance, such as to retrieve more cursors or make another call to the server, a separate option setting must be set to acknowledge the performance considerations. For example, all base attributes are stored together and can be read together and are considered on option, baseAttributes(boolean). However, requesting children costs more and therefore children must be requested through a separate childListOneLevel(boolean) setting. If an application prefers more fine-grained control, it can set attributeFilter(DKProjectionListICM).
By default, nothing is selected (all requests set to false) and any filter assumes no restriction. You must build up your request, understanding the performance implications of each piece of additional data. As a general rule, only request data that you plan to use. See the various "PERFORMANCE CONSIDERATION" sections to consider timing and possibly deferring retrieval of some data until actually needed, but balancing the efficiencies retrieving data together in a single call.
Although there is no specific order in which you must set options, the following is simply a recommended logical order for reviewing and considering various settings. This does not necessarily include all or mean you need to request all from the top of the list down through your desired setting, but only a logical order for consideration. For those that you do choose to select, this is also the recommended general order in which to make your selections, omitting those that you do not want to change. You need only set options that you desire by setting to 'true' or otherwise changed from the default settings.
linksOutbound()
linksInbound()
linksInboundFolderSources()
linksDescriptors()
linksTypeFilter()
linksLevelTwoCount()
linksLevelTwo()
behaviorIgnoreNoneFoundError()
behaviorRecordLastRetrieveOption()
behaviorSkipExistenceCheck()
behaviorSkipResourceAttrRefresh()
behaviorPartsAttributesCoreOnly()
CREATING INSTANCE
To create an instance, use static DKRetrieveOptionsICM.createInstance(dkDatastoreIntICM dsICM). There is no public constructor as documented in method createInstance().
See DKRetrieveOptionsICM.createInstance(dkDatastoreIntICM dsICM).
PASSING INSTANCE TO RETRIEVE
To use this retrieve options instance with a retrieve call, pass this instance inside DKNVPair[] retrieve options, such as through DKDDO::retrieve(DKNVPair[]) or DKDatastoreICM::retrieveObjects(dkCollection,DKNVPair[]). Specify this instance in a DKNVPair with the name as constant DKConstant.DK_CM_PARM_RETRIEVE and the value as this DKRetrieveOptionsICM instance. For convenience, you can use DKRetrieveOptionsICM::dkNVPair() to return a DKNVPair[] for easy use.
See DKRetrieveOptionsICM::dkNVPair() for much more documentation and examples.
DETECTING INDIVIDUAL DDO SUCCESS/FAILURE
When calling multi-item retrieve, if 99 out of 100 fail, but 1 out of 100 is successfully retrieved, no exception is thrown. Indicators are provided to identify which DDOs were successfully retrieved and which were not. Detailed information on detecting the indicators/flags are covered in the "DATA STRUCTURES" section of documentation for method behaviorIgnoreNoneFoundError(boolean). (Indicator flags are not tied to the referenced setting but are documented in more detail in the referenced section.)
See DKRetrieveOptionsICM::behaviorIgnoreNoneFoundError(bool behaviorIgnoreNoneFoundErrorRequested)
VALIDATING PIDS
Documented in the "DATA STRUCTURES" section of method behaviorIgnoreNoneFoundError(boolean). (Not tied to the referenced setting but is simply documented in more detail in the referenced section.)
See DKRetrieveOptionsICM::behaviorIgnoreNoneFoundError(bool behaviorIgnoreNoneFoundErrorRequested)
MINIMUM SETTINGS TO FORCE SERVER CALL
If nothing is requested in the retrieve options when using the DKRetrieveOptionsICM interface, retrieve honors the "nothing" request and returns without error. No server call is made because nothing was requested and the success/fail indicator for the last operation property is marked as failed. Perhaps you might want to force a call such as to re-validate the PIDs, but not actually retrieve anything. If you truly do not want to retrieve anything, then you should not call retrieve. However, if you still want to use retrieve and want the bare minimum settings to still invoke a retrieve call, see instructions documented in the "DATA STRUCTURES" section of method behaviorIgnoreNoneFoundError(boolean). (Not tied to the referenced setting but is simply documented in more detail in the referenced section.)
See DKRetrieveOptionsICM::behaviorIgnoreNoneFoundError(bool behaviorIgnoreNoneFoundErrorRequested)
DEFINITIONS
"Directly Selected DDOs": This term is used to refer to DKDDO objects directly submitted to retrieve either by the caller or directly returned by a query. For example, DKDatastoreICM::retrieveObjects(dkCollection) submits a collection of DKDDO instances directly to retrieve, DKDatastoreICM::retrieveObject(dkDataObjectBase) submits a single DKDDO instance directly to retrieve, DKDDO::retrieve() submits the DKDDO instance upon which the retrieve() method was called directly to retrieve, and DKDatastoreICM::execute() submits all query results as DKDDO instances to retrieve before returning the results. When DKDDO instances are submitted explicitly to retrieve, these are considered "directly selected DDOs" compared to any other DDOs such as children, document parts, or folder contents that are not originally submitted to retrieve but were retrieved as a result of a child list, parts list, or links list request that populated DDOs under the directly submitted DDOs. These are considered to be indirectly retrieved and are not listed in the original collection of DKDDO instances specifically requested. Note that any persistent DDO can be directly retrieved, including root components, child components, document parts, and folder contents.
"Base DDOs": These DDOs are the same as the "Directly Selected DDO" explained above. However, the term "base DDO" or simply "base" if often used to communicate which DDO relative to the original list of directly selected DDOs a particular statement refers to. In this case, "base DDO" means the original DKDDO instance in the original collection submitted to retrieve. Remember there are other DDOs that are populated by request under the directly selected DDOs, such as children, links, folder contents, and parts lists. Since the directly selected DDOs can themselves be root components, child components, document parts, folder contents, or linked items, the term "base DDO" is used to reflect that a statement refers to only those DDO instances directly submitted to retrieve and not any of the other DDOs listed within the directly-submitted DDOs. For example, since a query can return both root components and child components together in one collection as a result of a query, the directly returned DDOs cannot necessarily be called parent DDOs, root DDOs, or child DDOs in all cases.
BEHAVIOR NOTES
When refreshing (re-retrieving) a DDO that has been previously retrieved, existing data inside the DKDDO is typically cleared or updated only for the data requested by the current retrieve option settings. Old data is typically not cleared unless it is specifically requested and not found when refreshed from the current persistent value. For example, if you previously retrieved base attributes and children, but this time you requested only to retrieve children, the existing attributes are left as-is in the base DDOs and are not cleared or updated, however all existing child component collections are cleared and repopulated to reflect the current list of valid children. Similarly, if you request linksOutbound(true) and linksInbound(false), then all existing inbound links are left as-is but all existing outbound links are cleared and refreshed based on current outbound links data.
As already mentioned, if nothing is requested when using this DKRetrieveOptionsICM interface, retrieve honors the "nothing" request and returns without error. However, compared to the old bitwise 'int' retrieve options when used directly with retrieve (not indirectly such as through query), the similar-named bitwise 'int' retrieve option, DKConstant.DK_CM_CONTENT_IDONLY behaves very differently and instead assumes DK_CM_CONTENT_ONELEVEL (equivalent to baseAttributes(true), basePropertyAclName(true), basePropertyCheckedOutDetails(true), and childListOneLevel(true)) and did not honor the IDONLY request. Bitwise "IDONLY" was only a query-retrieve option not supported by other retrieve interfaces. More details on impact on individual success/failure status or all directly-selected DDOs is detailed in method behaviorIgnoreNoneFoundError(boolean).
Duplicate directly-selected DDOs are ignored by multi-item retrieve and will be flagged with as failed for their success/failure status. Retrieve processes only one unique component based on the PIDs (Item ID, Component ID, and Version ID) of DKDDOs submitted to retrieve in the dkCollection.
There is no specific order in which you must select options. Validation of incompatible options is performed only by the call to retrieve, not the options instance itself. Some settings might perform validation on input parameters for validity, such as a valid link type name for the linkTypeFilter(String) setting, but combinations of options and validity for the particular retrieve method used is checked when retrieve is called and passed this DKRetrieveOptionsICM instance. You can set options in any order, even if temporarily incompatible options are set. You are responsible for following the guidance in the "PRECEDENCE" sections for each setting. Although there is no specific order mandated, there is a recommended logical order to consider your various settings in a common logical progression documented at the top of the class documentation (above).
Method Summary
Modifier and Type | Method and Description |
---|---|
attributeFilters()
See DKRetrieveOptionsICM::baseAttributes(boolean baseAttributesRequested).
|
|
|
attributeFilters(DKProjectionListICM attributeFilters)
Improve performance by requesting only subset of attributes that you desire.
|
|
baseAttributes()
See DKRetrieveOptionsICM::baseAttributes(boolean baseAttributesRequested).
|
|
baseAttributes(boolean baseAttributesRequested)
Request user and core system attributes for directly selected component DDOs.
|
|
basePropertyAclName()
See DKRetrieveOptionsICM::basePropertyAclName(boolean basePropertyAclNameRequested).
|
|
basePropertyAclName(boolean basePropertyAclNameRequested)
If retrieving base attributes (baseAttributes(true)), also retrieve the
ACL Name property / system-attribute for any root components or
document parts directly selected.
|
|
basePropertyCheckedOutDetails()
See DKRetrieveOptionsICM::basePropertyCheckedOutDetails(boolean basePropertyCheckedOutDetailsRequested).
|
|
basePropertyCheckedOutDetails(boolean basePropertyCheckedOutDetailsRequested)
If retrieving base attributes (baseAttributes(true)), also retrieve the
checked out information properties / system-attributes for any root components
directly selected.
|
|
behaviorIgnoreNoneFoundError()
See DKRetrieveOptionsICM::behaviorIgnoreNotFoundError(boolean behaviorIgnoreNotFoundErrorRequested)
|
|
behaviorIgnoreNoneFoundError(boolean behaviorIgnoreNoneFoundErrorRequested)
Request that no exception is thrown if none of the selected DDOs are found
(or otherwise not a single selected DDO was retrieved successfully).
|
|
behaviorPartsAttributesCoreOnly()
See DKRetrieveOptionsICM::behaviorPartsAttributesCoreOnly(boolean behaviorPartsAttributesCoreOnly)
|
|
behaviorPartsAttributesCoreOnly(boolean behaviorPartsAttributesCoreOnly)
Request that only core parts attributes are retrieved when parts attributes are requested.
|
|
behaviorRecordLastRetrieveOption()
See DKRetrieveOptionsICM::behaviorRecordLastRetrieveOption(boolean behaviorRecordLastRetrieveOptionRequested)
|
|
behaviorRecordLastRetrieveOption(boolean behaviorRecordLastRetrieveOptionRequested)
Request the last-retrieve option to be recorded in each DKDDO
directly selected for retrieval so that when revisiting your DKDDO
objects you can detect what was last retrieve, perhaps before
determining if you want to retrieve more information.
|
|
behaviorSkipExistenceCheck()
See DKRetrieveOptionsICM::behaviorSkipExistenceCheck(boolean behaviorSkipExistenceCheckRequested)
|
|
behaviorSkipExistenceCheck(boolean behaviorSkipExistenceCheckRequested)
Request skipping existence checks for directly selected components
if possible.
|
|
behaviorSkipResourceAttrRefresh()
See DKRetrieveOptionsICM::behaviorSkipResourceAttrRefresh(bool behaviorSkipResourceAttrRefreshRequested)
|
|
behaviorSkipResourceAttrRefresh(boolean behaviorSkipResourceAttrRefreshRequested)
Request skipping refresh (re-retrieve) of resource content meta-data system attributes
if already retrieved previously if resource content was requested.
|
|
childAttributes()
See DKRetrieveOptionsICM::childAttributes(boolean childAttributesRequested)
|
|
childAttributes(boolean childAttributesRequested)
Request user and system attributes for child components retrieved under
the directly selected component DDOs if the "child list / TOC"
options are requested.
|
|
childListAllLevels()
See DKRetrieveOptionsICM::childListAllLevels(boolean childListAllLevelsRequested)
|
|
childListAllLevels(boolean childListAllLevelsRequested)
Request the all generations / levels of child components listed
(table of contents (TOC)) for directly selected component DDOs.
|
|
childListOneLevel()
See DKRetrieveOptionsICM::childListOneLevel(boolean childListOneLevelRequested)
|
|
childListOneLevel(boolean childListOneLevelRequested)
Request the next level of child components listed (table of contents (TOC))
for directly selected component DDOs.
|
|
createInstance(dkDatastoreIntICM dsICM)
Create a DKRetrieveOptionsICM instance.
|
|
dkNVPair()
Returns a DKNVPair[] that contains this set of retrieve options.
|
|
functionCheckOut()
See DKRetrieveOptionsICM::functionCheckOut(boolean functionCheckOutRequested)
|
|
functionCheckOut(boolean functionCheckOutRequested)
Check out (lock) all items directly selected for retrieval.
|
|
functionVersionLatest()
See DKRetrieveOptionsICM::functionVersionLatest(boolean functionVersionLatestRequested){
|
|
functionVersionLatest(boolean functionVersionLatestRequested)
Request the latest available version for all components directly selected,
overriding the specific version number identified in the PIDs for the
directly selected component DDOs.
|
|
linksDescriptors()
See DKRetrieveOptionsICM::linksDescriptors(boolean linksDescriptorsRequested)
|
|
linksDescriptors(boolean linksDescriptorsRequested)
If list links requested (inbound or outbound), additionally list the
optional descriptor item DDOs.
|
|
linksInbound()
See DKRetrieveOptionsICM::linksInbound(boolean linksOutboundRequested)
|
|
linksInbound(boolean linksInboundRequested)
Request the inbound links listed (table of contents (TOC)) for directly selected
component DDOs.
|
|
linksInboundFolderSources()
See DKRetrieveOptionsICM::linksInboundFoldeSources(boolean folderSourceDDOsRequested)
|
|
linksInboundFolderSources(boolean folderSourceDDOsRequested)
If inbound links listed, instruct retrieve to hold onto folder source
information and report it through a special construct.
|
|
linksLevelTwo()
See DKRetrieveOptionsICM::linksLevelTwo(boolean linksLevelTwoRequested)
|
|
linksLevelTwo(boolean linksLevelTwoRequested)
If already listing the first level of links, this setting requests the second level
of links for any inbound or outbound link list request.
|
|
linksLevelTwoCount()
See DKRetrieveOptionsICM::linksLevelTwoCount(boolean linksLevelTwoCountRequested)
|
|
linksLevelTwoCount(boolean linksLevelTwoCountRequested)
If already listing the first level of links, this setting requests the second level
of links count for any inbound or outbound link list request.
|
|
linksOutbound()
See DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested)
|
|
linksOutbound(boolean linksOutboundRequested)
Request the outbound links listing (table of contents (TOC)) and folder
contents listing (TOC) for directly selected component DDOs.
|
|
linksTypeFilter()
See DKRetrieveOptionsICM::linksType(boolean linksTypeRequested)
|
|
linksTypeFilter(java.lang.String linkTypeNameRequested)
If list links requested (inbound or outbound), list only links of
the specified link type name or specify '*' for all link types.
|
|
partsAttributes()
See DKRetrieveOptionsICM::partsAttributes(boolean partAttributesRequested)
|
|
partsAttributes(boolean partsAttributesRequested)
Request user and system attributes for document parts retrieved under
the directly selected component DDOs if the "parts list / TOC"
options are requested.
|
|
partsList()
See DKRetrieveOptionsICM::partsList(boolean partListRequested)
|
|
partsList(boolean partsListRequested)
Request the document parts listed (table of contents (TOC)) for any directly
selected component DDOs that happens to be a root component of a
"document" classified item type.
|
|
partsPropertyAclName()
See DKRetrieveOptionsICM::partsPropertyAclName(boolean partsPropertyAclNameRequested).
|
|
partsPropertyAclName(boolean partsPropertyAclNameRequested)
Retrieve the ACL Name property / system-attribute for any document
part listed under parent documents directly-selected for retrieval
and listed through the from a request to partsList(true).
|
|
resourceContent()
See DKRetrieveOptionsICM::resourceContent(boolean resourceContentRequested)
|
|
resourceContent(boolean resourceContentRequested)
[Single-Item Retrieve Only]
Request resource content for any resource items and document parts
(including parts listed through partsList(boolean) for any
directly-selected parent documents.
|
|
toString()
Request a single-line string description of this object.
|
|
toString(boolean showExcludeList)
Same as toString(), except that you can specify whether or not to print
the excluded items.
|
Methods inherited from class java.lang.Object |
---|
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Method Detail
createInstance
- public static DKRetrieveOptionsICM createInstance( dkDatastoreIntICM dsICM)
- throws DKUsageError
- java.lang.Exception
Parameters:
dsICM
- Connected DKDatastoreICM instance upon which retrieve operations are to be performed using this DKRetrieveOptionsICM instance. The DKDatastoreICM instance is used for validation and simple pre-processing of requests based on the connected user. For example, if a link type name is used, the name is immediately verified in order to produce usage errors immediately within context.
DATASTORE POOLING NOTES
The datastore instance upon which you plan to call retrieve must be supplied here. If you obtain a new DKDatastoreICM instance from the pool, you should create a new DKRetrieveOptionsICM instance for that instance. Error DKMessageId.DK_CM_MSG_INVPARM (DGL0303A) might result during a retrieve call if the datastore instance is different than the one used to create the DKRetrieveOptionsICM (especially when using attribute filters (projection lists)). Additionally, any definition names used with settings (such as link type filter) is validated up front based on the datastore instance provided to create the DKRetrieveOptionsICM and is not repeated. If the two datastore instances are not identical, this can result in a difference in typical errors if invalid names are caught at a different location than usual if the original checks passed but the current datastore instance believes the name is invalid.
MEMORY MANAGEMENT (Only C++)
This object does *not* assume ownership of the instance passed. The instance is just a reference for the DKRetrieveOptionsICM to perform some validation. The original instance is fully expected to be used further by the caller. A retrieve option is useless if no subsequent retrieve calls are expected, clearly indicating the end users intent to continue to use the DKDatastoreICM instance.
The caller is responsible for freeing the memory for the DKDatastoreICM instance after there is no more need for it or this DKRetrieveOptionsICM instance.
Returns:
Returns a pointer to the instance created for the caller.
MEMORY MANAGEMENT (Only C++)
Ownership of the object is passed to the caller. An instance is simply created on the caller's behalf. The caller is responsible for freeing the memory when no longer needed.
MEMORY MANAGEMENT (Only C++)
Ownership of the object is passed to the caller. An instance is simply created on the caller's behalf. The caller is responsible for freeing the memory when no longer needed.
Throws:
DKMessageId.DK_CM_MSG_INVPARM(1)
- DKUsageError with ID DKMessageId.DK_CM_MSG_INVPARM (DGL0303A) if the DKDatastoreICM parameter specified is invalid. The invalid parameter text is appended with a more detailed explanation explaining why the parameter is invalid, such as:
- DKMessageId.DK_CM_MSG_NULLDATAOBJECT (DGL0385A) if the object is null.
- DKMessageId.DK_CM_MSG_CONNECTNOTFOUND (DGL0310A) if the datastore clearly indicates it is not connected.
DKMessageId.DK_CM_MSG_INVPARM(2)
- DKUsageError (propagated from internal constructor and initialization methods) with error ID DKMessageId.DK_CM_MSG_INVPARM (DGL0303A) if the DKDatastoreICM instance has no DKDatastoreDefICM (is null).
java.lang.Exception
- propagated from dkDatastoreIntICM.isConnected() and
propagated from DKRetrieveOptionsICM(dkDatastoreIntICM), which
propagated from DKRetrieveOptionsICM::init(dkDatastoreIntICM),
which propagated from dkDatastoreIntICM::datastoreDef().
dkNVPair
- public DKNVPair[] dkNVPair()
Returns a DKNVPair[] that contains this set of retrieve options.
This is a convenient way to easily use this retrieve options instance
with any retrieve method that accepts DKNVPair[] options.
Use this retrieve options instance pre-packaged within a DKNVPair[] for use with retrieve interfaces accepting the DKNVPair[] form of retrieve options. In Java, this method returns a reference to a DKNVPair[] of length '1' where DKNVPair[0] is DKNVPair(DKConstant.DK_CM_PARM_RETRIEVE = <this DKRetrieveOptionsICM instance>). In C++, the DKNVPair[] length is increased to '2' where DKNVPair[1] is DKNVPair(DK_CM_PARM_RETRIEVE = <NULL>). (Note: Do not hard-code expected length. Instead use Java's built-in ".length" or C++ DKRetrieveOptionsICM::dkNVPairLength() for actual array length.)
Instead of creating your own DKNVPair[] (and managing the memory in C++) for each and every retrieve call that does not have a signature that accepts DKRetrieveOptionsICM directly but does support it through a DKNVPair[] options interface, use this method for convenient use. The same DKNVPair[] instance is returned on repeated requests for optimized use and there is no need for the caller to free the memory in C++.
When using the C++
PASSING INSTANCE TO RETRIEVE
To use this retrieve options instance with a retrieve call, pass this instance inside DKNVPair[] retrieve options, such as through DKDDO::retrieve(DKNVPair[]) or DKDatastoreICM::retrieveObjects(dkCollection,DKNVPair[]). Specify this instance in a DKNVPair with the name as constant DKConstant.DK_CM_PARM_RETRIEVE and the value as this DKRetrieveOptionsICM instance. For convenience, you can use DKRetrieveOptionsICM::dkNVPair() to return a DKNVPair[] for easy use.
For example: (Java)
Creating Your Own DKNVPair
This method effectively does the following for you (and allows you to omit tracking the DKNVPair[] as a separate variable).
C++ DIFFERENCES: ARRAY LENGTH & END ELEMENTS
Java arrays know their length and can be naturally detected. Most DKNVPair[] option parsing by the APIs simply reads the full array in Java without extra help. C++ arrays are just pointers to the first element and the length is not detectable through the array object alone. The C++ APIs require the caller to tell additionally report the length or when to stop reading through the array so that parsing does not run off the end. There are two ways this input is accepted in C++, which can vary from method to method. First, many signatures take an additional length parameter where the caller passes the actual length (or the length they desire to be read up to). Other signatures that do not have a length parameter require the user to add an additional DKNVPair element named DK_CM_PARM_END to tell the API to stop reading further when looping through the array while reading option values. Some methods might also accept both and just stop at the first of the two conditions, END found or reached end of specified length.
To simplify working with DKNVPair* options, tracking lengths, or using END elements, the following suffice for all retrieve methods when only passing this DKRetrieveOptionsICM object.
For example, you can easily make a retrieve call using DKNVPair* options in one line:
When working with your own DKNVPair[] options, as a general rule to consistently create DKNVPair[] options in C++ regardless of what type of end indicator is used for a particular method, you should always add a DK_CM_PARM_END element (as shown in the example). This way you do not have to create DKNVPair[] options differently depending on the method. Most methods rely on the additional length parameter exclusively without regard to an END element. Some methods rely exclusively on an END element. A very small subset relies on the first of the two.
Furthermore, most methods that accept the length parameter also completely ignore END elements. If the specified array length extends beyond END markers found, in most cases the API continues reading the remaining options up to the specified length. This means that any additional options specified beyond END markers might or might not be read depending on the particular code path. If the length passed in is incorrect, the API might walk past any END elements and out of bounds if the true length is less than the specified length. As a general rule, always create DKNVPair[] lengths to fit your actual options and do not rely on END elements to stop options parsing. Always fill the array from the front with valid options and leave no gaps. For example, if you have a 5-element array, start filling positions in order of 0, 1, 2, 3, then 4 to ensure you leave no gaps between valid options to avoid confusion. Always place the END element as the last element in the array. If your DKNVPair[] array must be larger, ensure that you reset all unused elements to ignored or terminating elements. For example, you could set any unused elements to DK_CM_PARM_END (provided you are not filling gaps between valid option with a confusing END element that can lead to uncertainty of reading options beyond the END element.
BEHAVIOR NOTES
The original instance is returned (not a copy). Do not modify this instance or you could impact subsequent calls for this instance. Minimal verification is performed and if the DKNVPair is determined to have been altered, the original DKNVPair will be repaired / updated. A new copy is not created even in Java to preserve identical behavior in C++, which is required to ensure proper memory cleanup. It is not guaranteed that the DKNVPair[] will always be corrected.
When using the DKNVPair[] retrieve options, the following validation errors can result from the following methods.
Exceptions From Methods Above
Use this retrieve options instance pre-packaged within a DKNVPair[] for use with retrieve interfaces accepting the DKNVPair[] form of retrieve options. In Java, this method returns a reference to a DKNVPair[] of length '1' where DKNVPair[0] is DKNVPair(DKConstant.DK_CM_PARM_RETRIEVE = <this DKRetrieveOptionsICM instance>). In C++, the DKNVPair[] length is increased to '2' where DKNVPair[1] is DKNVPair(DK_CM_PARM_RETRIEVE = <NULL>). (Note: Do not hard-code expected length. Instead use Java's built-in ".length" or C++ DKRetrieveOptionsICM::dkNVPairLength() for actual array length.)
Instead of creating your own DKNVPair[] (and managing the memory in C++) for each and every retrieve call that does not have a signature that accepts DKRetrieveOptionsICM directly but does support it through a DKNVPair[] options interface, use this method for convenient use. The same DKNVPair[] instance is returned on repeated requests for optimized use and there is no need for the caller to free the memory in C++.
When using the C++
dkNVPair()
method, always use
dkNVPairLength()
(C++ only) to pass the length if the
method signature requires the length of the DKNVPair*. Do not hard
code expectations of the number of elements currently returned by
dkNVPair()
.
PASSING INSTANCE TO RETRIEVE
To use this retrieve options instance with a retrieve call, pass this instance inside DKNVPair[] retrieve options, such as through DKDDO::retrieve(DKNVPair[]) or DKDatastoreICM::retrieveObjects(dkCollection,DKNVPair[]). Specify this instance in a DKNVPair with the name as constant DKConstant.DK_CM_PARM_RETRIEVE and the value as this DKRetrieveOptionsICM instance. For convenience, you can use DKRetrieveOptionsICM::dkNVPair() to return a DKNVPair[] for easy use.
For example: (Java)
// Assume you have a connected DKDatastoreICM instance as variable "dsICM" // and a DKDDO to retrieve in variable "ddo". DKRetrieveOptionsICM dkRetrieveOptions = DKRetrieveOptionsICM.createInstance(dsICM); // ... Set various settings in dkRetrieveOptions instance ... ddo.retrieve(dkRetrieveOptions.dkNVPair()); // OR (use multi-item retrieve / always use if retrieving multiple) dkCollection coll = new DKSequentialCollection(); coll.addElement(ddo); dsICM.retrieveObjects(coll,dkRetrieveOptions.dkNVPair());Or: (C++)
// Assume you have a connected DKDatastoreICM* instance as variable "dsICM" // and a DKDDO* to retrieve in variable "ddo". DKRetrieveOptionsICM* dkRetrieveOptions = DKRetrieveOptionsICM::createInstance(dsICM); // ... Set various settings in dkRetrieveOptions instance ... ddo->retrieve(dkRetrieveOptions->dkNVPair(),dkRetrieveOptions->dkNVPairLength()); // OR (use multi-item retrieve / always use if retrieving multiple) dkCollection* coll = new DKSequentialCollection(); coll->addElement((dkDastaObject*)ddo); dsICM->retrieveObjects(coll,dkRetrieveOptions->dkNVPair(),dkRetrieveOptions->dkNVPairLength());This method is intended primarily for use with retrieve-specific interfaces. For use with other features that might indirectly invoke retrieve, you should assess whether you need your own DKNVPair[] where you might want to specify more options pertaining to other features. For query (DKDatastoreICM::evaluate(), execute(), executeWithCallback(), etc.), review other options that you might be interested in adding to your own DKNVPair[] for desired performance and behavior. Otherwise, if you are satisfied with all defaults, this DKNVPair[] will work for query calls as well.
Creating Your Own DKNVPair
This method effectively does the following for you (and allows you to omit tracking the DKNVPair[] as a separate variable).
Java: DKNVPair[] optionsDKNVPair = new DKNVPair[1]; optionsDKNVPair[0] = new DKNVPair(DKConstant.DK_CM_PARM_RETRIEVE,dkRetrieveOptions); C++: DKNVPair* optionsDKNVPair = new DKNVPair[2]; optionsDKNVPair[0].set(DK_CM_PARM_RETRIEVE,dkRetrieveOptions); optionsDKNVPair[1].set(DK_CM_PARM_END ,DKAny()); // Unset DKAny is NULLFor example, if you choose to create and use your own DKNVPair:
Java: // Assume you have a connected DKDatastoreICM instance as variable "dsICM" // and a DKDDO to retrieve in variable "ddo". DKRetrieveOptionsICM dkRetrieveOptions = DKRetrieveOptionsICM.createInstance(dsICM); // ... Set various settings in dkRetrieveOptions instance ... DKNVPair[] optionsDKNVPair = new DKNVPair[1]; optionsDKNVPair[0] = new DKNVPair(DKConstant.DK_CM_PARM_RETRIEVE,dkRetrieveOptions); ddo.retrieve(optionsDKNVPair); // or dkCollection coll = new DKSequentialCollection(); coll.addElement(ddo); dsICM.retrieveObjects(coll,optionsDKNVPair); C++: // Assume you have a connected DKDatastoreICM* instance as variable "dsICM" // and a DKDDO* to retrieve in variable "ddo". DKRetrieveOptionsICM* dkRetrieveOptions = DKRetrieveOptionsICM::createInstance(dsICM); // ... Set various settings in dkRetrieveOptions instance ... DKNVPair* optionsDKNVPair = new DKNVPair[2]; optionsDKNVPair[0].set(DK_CM_PARM_RETRIEVE,dkRetrieveOptions); optionsDKNVPair[1].set(DK_CM_PARM_END ,DKAny()); // Unset DKAny is NULL ddo->retrieve(optionsDKNVPair); // or dkCollection* coll = new DKSequentialCollection(); coll->addElement(ddo); dsICM->retrieveObjects(coll,optionsDKNVPair,2); delete[] optionsDKNVPair;See the SSearchICM sample for example code creating DKNVPair[] options for use with query.
C++ DIFFERENCES: ARRAY LENGTH & END ELEMENTS
Java arrays know their length and can be naturally detected. Most DKNVPair[] option parsing by the APIs simply reads the full array in Java without extra help. C++ arrays are just pointers to the first element and the length is not detectable through the array object alone. The C++ APIs require the caller to tell additionally report the length or when to stop reading through the array so that parsing does not run off the end. There are two ways this input is accepted in C++, which can vary from method to method. First, many signatures take an additional length parameter where the caller passes the actual length (or the length they desire to be read up to). Other signatures that do not have a length parameter require the user to add an additional DKNVPair element named DK_CM_PARM_END to tell the API to stop reading further when looping through the array while reading option values. Some methods might also accept both and just stop at the first of the two conditions, END found or reached end of specified length.
To simplify working with DKNVPair* options, tracking lengths, or using END elements, the following suffice for all retrieve methods when only passing this DKRetrieveOptionsICM object.
DKRetrieveOptionsICM::dkNVPair()
DKRetrieveOptionsICM::dkNVPairLength()
(C++ Only)
For example, you can easily make a retrieve call using DKNVPair* options in one line:
ddo.retrieve(dkRetrieveOptions->dkNVPair(),dkRetrieveOptions->dkNVPairLength());
When working with your own DKNVPair[] options, as a general rule to consistently create DKNVPair[] options in C++ regardless of what type of end indicator is used for a particular method, you should always add a DK_CM_PARM_END element (as shown in the example). This way you do not have to create DKNVPair[] options differently depending on the method. Most methods rely on the additional length parameter exclusively without regard to an END element. Some methods rely exclusively on an END element. A very small subset relies on the first of the two.
Furthermore, most methods that accept the length parameter also completely ignore END elements. If the specified array length extends beyond END markers found, in most cases the API continues reading the remaining options up to the specified length. This means that any additional options specified beyond END markers might or might not be read depending on the particular code path. If the length passed in is incorrect, the API might walk past any END elements and out of bounds if the true length is less than the specified length. As a general rule, always create DKNVPair[] lengths to fit your actual options and do not rely on END elements to stop options parsing. Always fill the array from the front with valid options and leave no gaps. For example, if you have a 5-element array, start filling positions in order of 0, 1, 2, 3, then 4 to ensure you leave no gaps between valid options to avoid confusion. Always place the END element as the last element in the array. If your DKNVPair[] array must be larger, ensure that you reset all unused elements to ignored or terminating elements. For example, you could set any unused elements to DK_CM_PARM_END (provided you are not filling gaps between valid option with a confusing END element that can lead to uncertainty of reading options beyond the END element.
BEHAVIOR NOTES
The original instance is returned (not a copy). Do not modify this instance or you could impact subsequent calls for this instance. Minimal verification is performed and if the DKNVPair is determined to have been altered, the original DKNVPair will be repaired / updated. A new copy is not created even in Java to preserve identical behavior in C++, which is required to ensure proper memory cleanup. It is not guaranteed that the DKNVPair[] will always be corrected.
When using the DKNVPair[] retrieve options, the following validation errors can result from the following methods.
- DKDatastoreICM::retrieveObjects(dkCollection,DKNVPair[])
- DKDatastoreICM::retrieveObject(dkDataObject,DKNVPair[])
- DKDDO::retrieve(DKNVPair[])
Exceptions From Methods Above
-
DKMessageIdICM.DK_ICM_MSG_DUPLICATE_SELECTION_NAME
DKUsageError with ID DKMessageIdICM.DK_ICM_MSG_DUPLICATE_SELECTION_NAME (DGL4125A) if more than one DKConstant.DK_CM_PARM_RETRIEVE is found in a DKNVPair and DKRetrieveOptionsICM values used. This error is reported if two or more DKRetrieveOptionsICM values are found or if both a DKRetrieveOptionsICM value and a bitwise int value are found. If two or more bitwise int values are found, no error is reported and in Java the latest bitwise int option is used or in C++ the first bitwise in option is used, ignoring the previous value.
-
DKMessageIdICM.DK_ICM_MSG_PROJ_RETRIEVE_OPTION_NOT_INTEGER_TYPE
DKUsageError with ID DKMessageIdICM.DK_ICM_MSG_PROJ_RETRIEVE_OPTION_NOT_INTEGER_TYPE (DGL7135A) if the value of any retrieve option (NVPair named DKConstant.DK_CM_PARM_RETRIEVE) has a value that is neither a DKRetrieveOptionsICM or Integer instance.
This error also occurs if both a DKConstant.DK_CM_PARM_RETRIEVE option is provided with a DKRetrieveOptionsICM value (which includes its own projection list settings) and a DKConstant.DK_CM_PARM_PROJECTION_LIST value is provided with the old DKNVPair[] projection list style. If a DKRetrieveOptionsICM is used, the new projection list interface must also be used.
Additional detail is appended providing details on what instance was provided and the DKNVPair name of issue.
-
DKMessageIdICM.DK_ICM_MSG_PROJ_RETRIEVE_OPTION_NOT_SUPPLIED
DKUsageError with ID DKMessageIdICM.DK_ICM_MSG_PROJ_RETRIEVE_OPTION_NOT_SUPPLIED (DGL7138A) if the value of any retrieve option (NVPair named DKConstant.DK_CM_PARM_RETRIEVE) has no corresponding value (is null). Additional detail is appended providing details on what instance was provided.
-
DKMessageIdICM.DK_ICM_MSG_PROJ_PROJ_LIST_OPTION_NOT_DKNVPAIR_TYPE
DKUsageError with ID DKMessageIdICM.DK_ICM_MSG_PROJ_PROJ_LIST_OPTION_NOT_DKNVPAIR_TYPE (DGL7140A) if the value of the DKNVPair projection list option (NVPair named DKContant.DK_CM_PARM_PROJECTION_LIST) has a value that is not an instance of DKNVPair[]. Additional detail is appended providing details on what instance was provided.
-
DKMessageIdICM.DK_ICM_MSG_PROJ_PROJ_LIST_NOT_SUPPLIED
DKUsageError with ID DKMessageIdICM.DK_ICM_MSG_PROJ_PROJ_LIST_NOT_SUPPLIED (DGL7139A) if the value of the DKNVPair projection list option (NVPair named DKContant.DK_CM_PARM_PROJECTION_LIST) has no value (is null). Additional detail is appended indicating the DKNVPair index of issue.
Returns:
a reference to a DKNVPair[] of length '1' where DKNVPair[0] is
DKNVPair(DKConstant.DK_CM_PARM_RETRIEVE = <this DKRetrieveOptionsICM
instance>). The original instance is returned (not a copy). The
original instance might be corrected if it is detected as changed
(but is not guaranteed to always correct itself). Do not modify
the returned instance.
MEMORY MANAGEMENT (C++ Only)
The DKRetrieveOptionsICM instance remains the owner of the DKNVPair[] memory. Do NOT delete or modify the returned DKNVPair[]. As described in the "BEHAVIOR NOTES" section, the original instance is returned. When the DKRetrieveOptionsICM instance is deleted, it will delete the DKNVPair[].
MEMORY MANAGEMENT (C++ Only)
The DKRetrieveOptionsICM instance remains the owner of the DKNVPair[] memory. Do NOT delete or modify the returned DKNVPair[]. As described in the "BEHAVIOR NOTES" section, the original instance is returned. When the DKRetrieveOptionsICM instance is deleted, it will delete the DKNVPair[].
attributeFilters
- public void attributeFilters(DKProjectionListICM attributeFilters)
Improve performance by requesting only subset of attributes that you desire.
If you are only interested in some of the attributes, specify which attributes
you want to be retrieved, saving time and memory by omitting those that you
do not need. Furthermore, you can filter entire child component types
from the childList...() settings by omitting a projection for any
component type. You only retrieve the attributes and child components
specifically specified in the projection list.
This setting only filters attributes and does not enable retrieval of attributes. You must request attributes through other retrieve options for the applicable DDOs that you are interested in retrieving attributes. If attribute retrieval is not requested or specifically set to 'false', the general attribute requests take precedence and the projection list is ignored because there are not attributes to be returned.
This setting only filters component types and does not enable retrieval of child components. You must request child components through other retrieve options. See childList...() settings. The child list and attribute requests take precedence. If no child list settings are requested *or* if childAttributes(false), the projections for the affected component types are ignored.
You can specify a general list of attributes to apply to any type or you can specify specific attributes for each item type you are interested in. A projection lists attributes that you desire for a specific item type, thereby filtering those not mentioned. A projection list is a set of such projections.
For any child component type not covered by a projection, the child component type collection and all children of that type are omitted from retrieval. For example, suppose you specify a projection for item type "Book" but omit child component type "Chapter" and you retrieve a "Book" DDO with childListAllLevels(true) or childListOneLevel(true). Attributes of "Book" provided they are listed in the "Book" projection. Regardless of whether there are any "Chapter" child components, no chapter DDOs retrieved because no projection was provided.
Additionally, omitted projections can also filter directly-selected DDOs submitted to retrieve from the existence check on the directly-selected DDOs. If projections are omitted for component type views that apply to any directly-selected DDOs, the directly-selected DDOs will not be retrieved (will be flagged as FAILED since no existence check was performed) unless children were requested and a non-zero count of children were found.
For more details on projections, refer to DKProjectionListICM.
See DKProjectionListICM documentation.
DEFAULT: null (All Attributes and Component Types Implicitly Selected)
PRECEDENCE
If 'null', this setting has no effect, indicating that no filter is supplied (everything shows through, limited of course to actual selections by other retrieve options).
This setting only filters data requested by other options and does not select any new data. Therefore, if you do not select data with other options for which this setting applies additional filters, although you might enable some aspect to show through the filter, but without the data requested in general in the first place, this setting has no effect.
For example, this setting only filters attributes requested through other attribute-inclusive settings, such as DKRetrieveOptionsICM::baseAttributes(boolean baseAttributesRequested), childAttributes(boolean childAttributesRequested), and partsAttributes(boolean partsAttributesRequested). Attribute filters only filter selected data and does not include any additional data on its own. If baseAttributes(true) and childAttributes(false), this setting will filter any attributes otherwise returned baseAttributes(true), but since no attributes are returned by childAttributes(false) this setting does not apply to children in this example scenario. If baseAttributes(false), childAttributes(false), and partsAttributes(false), the attribute filtering aspect of the projection list is ignored.
This setting filters out (or skips retrieval or refresh) of entire item type and component type views for any base DDO submitted directly to retrieve for children listed through child list retrieve options. You can filter the component types requested through other child-list-inclusive settings, such as DKRetrieveOptionsICM::childListOneLevel(boolean childListOneLevelRequested) and childListAllLevels(boolean childListAllLevelsRequested). If childListOneLevel(false) or childListAllLevels(false) or childAttributes(false), the child filtering aspect of the projection list is ignored.
The base DDO filtering aspect of omitted projections has significant implications. Projection lists can filter out the base DDOs directly submitted to retrieve for which the child list, parts list, function checkout, resource content, links list, folder list, or any other requests are in progress simply by omitting a projection for the base DDO type. When any of the base DDO submitted directly to retrieve do not show through in the projection list, DDOs of that type are skipped, marked as "FAIL" for their success/failure indictor to indicate that no server call was made (even for an existence check). To retrieve anything for a DDO, you must first at least include the submitted DDOs themselves in the projections. You do not need to retrieve attributes or anything else, but you must at least include a projection (to force inclusion in the existence check), unless your intent is to filter out DDOs of the omitted type. For example, in order to retrieve any children for any given item type view or component type view to which a DDO belongs, you must include the base DDOs submitted to retrieve in the projection list. Otherwise if omitted, all DDOs submitted to retrieve for any component type view (or item type view) that is filtered out due to omission will not be submitted to the server for an existence check nor have its children listed. To list children (or any other request), you do not need to request meta data for the base DDO (you can still choose DKRetrieveOptionsICM::baseAttributes(false) (default)), however, if submitting attribute filters (projection list), the projection list is always honored. If you omit projections for DDOs submitted, the entire DDO is considered filtered out. You cannot retrieve children (or anything else) if you exclude the DDO to which the children are to be listed. You can either specify a projection for all types of directly submitted base DDOs and include system attributes (
Finally, even if no attributes are requested for the directly-selected base DDOs (baseAttributes(false)), the projection list can still filter existence checks on the base DDOs, limiting checks to only those with projections specified. However, if nothing is requested to retrieve, the projection list does not enable existence checks if not necessary. The projection list can only filter existence checks needed by other retrieve options. For example, if you select nothing but linksOutbound(true), if you provided a projection list, of the submitted DDOs for retrieval, only those of the component type views for which projections exist will be checked. If no existence check is performed, links for DDOs of the omitted types will not be retrieved.
PERFORMANCE
Filtering the number of attributes and child component types to only those that you plan can save table joins, network communication, and memory allocation, object counts, and processing for data structures for which you have might have no need. This setting is a performance feature. See documentation explained above.
However, if want to select all attributes and all types, it is a little faster if you do not specify a projection list (attributeFilters(null)). You could specify a projection list with projections for all component types to be returned or specify the general projection ('*') with the all-attributes keyword (DKConstantICM.DK_ICM_ALL_ATTRS). However, there is additional processing on both the client-side and server to process your projection list request. If you truly desired all component types and all attributes and planned to use or display all, it is better to specify no attribute filters / projection list.
The fastest performance for any given component type view is to omit the type entirely by omitting a projection for that type. However, if you are including a projection merely for existence, use only system attributes (
Using attribute filters (or projection lists) is not always faster. There is overhead for processing which can consume the difference in performance savings or could require slightly more time. Attribute filters might not show an advantage for filtering out just a few small attributes for small sets of data. Attribute filters show the best advantages in the following cases:
Using a general wildcard projection (
If you want to retrieve all attributes of all types, it is slightly faster to not provide attribute filters (specify
When requesting all attributes for any given item type or component type projection, it is slightly faster to use the all-attributes keyword (
BEHAVIOR NOTES
Through the DKRetrieveOptionsICM interface, attribute filters and projection lists never select additional data and only filter data already selected by other options. For example, even if you supply a projection list that has projections for and shows through all child attributes, if you do not request child attributes in the first place, the filter has no effect because it is applied on top of a request that will not return any children to start with. However, this behavior is different from the old projection list interface (DKNVPair[] projections, not DKProjectionListICM), the old projection list overrode any bitwise 'int' retrieve options (or defaults if no options specified) and included all attributes, all children levels, and all children attributes (equivalent to DKConstant.DK_CM_CONTENT_ITEMTREE_NO_LINKS). The old DKNVPair[] projection list interface did in fact select additional data, regardless of the actual retrieve option used (unless you used query and bitwise IDONLY).
There are general projection ('*') behavior considerations and projection list "holes" for which you have several behavior options. There are also more considerations if you desire all component types and all attributes. See related information in DKProjectionListICM class documentation.
See DKProjectionListICM documentation.
When using the DKProjectionListICM interface, there is no need to specify projections for component types or parent component types that are not retrieved. When using the old DKNVPair[] projection list interface, you were required to specify projections with attributes for all parent hierarchy above any projection you specified, even if none of the parents appeared in the result. For example, consider an item type named "Book" and child component type "Chapter". Suppose you used query and obtained a list of chapters. If you wanted to specify a projection list, if you used the old DKNVPair[] projection list format, you were required to specify a projection with attributes for "Book", even though you directly selected "Chapter" components to retrieve. No "Book" components would ever be retrieved, but you were still required to specify a projection and attributes or else an exception was reported. With the newer DKProjectionListICM interface, there is no need to specify such projections. No exception will be thrown if you omit a parent type that is above the directly-selected DDOs.
This setting only filters attributes and does not enable retrieval of attributes. You must request attributes through other retrieve options for the applicable DDOs that you are interested in retrieving attributes. If attribute retrieval is not requested or specifically set to 'false', the general attribute requests take precedence and the projection list is ignored because there are not attributes to be returned.
This setting only filters component types and does not enable retrieval of child components. You must request child components through other retrieve options. See childList...() settings. The child list and attribute requests take precedence. If no child list settings are requested *or* if childAttributes(false), the projections for the affected component types are ignored.
You can specify a general list of attributes to apply to any type or you can specify specific attributes for each item type you are interested in. A projection lists attributes that you desire for a specific item type, thereby filtering those not mentioned. A projection list is a set of such projections.
For any child component type not covered by a projection, the child component type collection and all children of that type are omitted from retrieval. For example, suppose you specify a projection for item type "Book" but omit child component type "Chapter" and you retrieve a "Book" DDO with childListAllLevels(true) or childListOneLevel(true). Attributes of "Book" provided they are listed in the "Book" projection. Regardless of whether there are any "Chapter" child components, no chapter DDOs retrieved because no projection was provided.
Additionally, omitted projections can also filter directly-selected DDOs submitted to retrieve from the existence check on the directly-selected DDOs. If projections are omitted for component type views that apply to any directly-selected DDOs, the directly-selected DDOs will not be retrieved (will be flagged as FAILED since no existence check was performed) unless children were requested and a non-zero count of children were found.
For more details on projections, refer to DKProjectionListICM.
See DKProjectionListICM documentation.
DEFAULT: null (All Attributes and Component Types Implicitly Selected)
PRECEDENCE
If 'null', this setting has no effect, indicating that no filter is supplied (everything shows through, limited of course to actual selections by other retrieve options).
This setting only filters data requested by other options and does not select any new data. Therefore, if you do not select data with other options for which this setting applies additional filters, although you might enable some aspect to show through the filter, but without the data requested in general in the first place, this setting has no effect.
For example, this setting only filters attributes requested through other attribute-inclusive settings, such as DKRetrieveOptionsICM::baseAttributes(boolean baseAttributesRequested), childAttributes(boolean childAttributesRequested), and partsAttributes(boolean partsAttributesRequested). Attribute filters only filter selected data and does not include any additional data on its own. If baseAttributes(true) and childAttributes(false), this setting will filter any attributes otherwise returned baseAttributes(true), but since no attributes are returned by childAttributes(false) this setting does not apply to children in this example scenario. If baseAttributes(false), childAttributes(false), and partsAttributes(false), the attribute filtering aspect of the projection list is ignored.
This setting filters out (or skips retrieval or refresh) of entire item type and component type views for any base DDO submitted directly to retrieve for children listed through child list retrieve options. You can filter the component types requested through other child-list-inclusive settings, such as DKRetrieveOptionsICM::childListOneLevel(boolean childListOneLevelRequested) and childListAllLevels(boolean childListAllLevelsRequested). If childListOneLevel(false) or childListAllLevels(false) or childAttributes(false), the child filtering aspect of the projection list is ignored.
The base DDO filtering aspect of omitted projections has significant implications. Projection lists can filter out the base DDOs directly submitted to retrieve for which the child list, parts list, function checkout, resource content, links list, folder list, or any other requests are in progress simply by omitting a projection for the base DDO type. When any of the base DDO submitted directly to retrieve do not show through in the projection list, DDOs of that type are skipped, marked as "FAIL" for their success/failure indictor to indicate that no server call was made (even for an existence check). To retrieve anything for a DDO, you must first at least include the submitted DDOs themselves in the projections. You do not need to retrieve attributes or anything else, but you must at least include a projection (to force inclusion in the existence check), unless your intent is to filter out DDOs of the omitted type. For example, in order to retrieve any children for any given item type view or component type view to which a DDO belongs, you must include the base DDOs submitted to retrieve in the projection list. Otherwise if omitted, all DDOs submitted to retrieve for any component type view (or item type view) that is filtered out due to omission will not be submitted to the server for an existence check nor have its children listed. To list children (or any other request), you do not need to request meta data for the base DDO (you can still choose DKRetrieveOptionsICM::baseAttributes(false) (default)), however, if submitting attribute filters (projection list), the projection list is always honored. If you omit projections for DDOs submitted, the entire DDO is considered filtered out. You cannot retrieve children (or anything else) if you exclude the DDO to which the children are to be listed. You can either specify a projection for all types of directly submitted base DDOs and include system attributes (
DKContantICM.DK_ICM_SYSTEM_ATTRS
) (just to add a projection)
or request system attributes through a general projection that applies to
and automatically includes all types. Regardless of actual attributes
listed in the projection, retrieve options such as
DKRetrieveOptionsICM::baseAttributes(false) take precedence to exclude
retrieving the attributes, but the projection allows the base
DDO to be included. For best performance, use only system attributes
(DKContantICM.DK_ICM_SYSTEM_ATTRS
) when attempting to merely
include a projection for existence. If desired, you can use the filtering
feature to filter out base DDOs to restrict which DDOs for which you want
children listed.
Finally, even if no attributes are requested for the directly-selected base DDOs (baseAttributes(false)), the projection list can still filter existence checks on the base DDOs, limiting checks to only those with projections specified. However, if nothing is requested to retrieve, the projection list does not enable existence checks if not necessary. The projection list can only filter existence checks needed by other retrieve options. For example, if you select nothing but linksOutbound(true), if you provided a projection list, of the submitted DDOs for retrieval, only those of the component type views for which projections exist will be checked. If no existence check is performed, links for DDOs of the omitted types will not be retrieved.
PERFORMANCE
Filtering the number of attributes and child component types to only those that you plan can save table joins, network communication, and memory allocation, object counts, and processing for data structures for which you have might have no need. This setting is a performance feature. See documentation explained above.
However, if want to select all attributes and all types, it is a little faster if you do not specify a projection list (attributeFilters(null)). You could specify a projection list with projections for all component types to be returned or specify the general projection ('*') with the all-attributes keyword (DKConstantICM.DK_ICM_ALL_ATTRS). However, there is additional processing on both the client-side and server to process your projection list request. If you truly desired all component types and all attributes and planned to use or display all, it is better to specify no attribute filters / projection list.
The fastest performance for any given component type view is to omit the type entirely by omitting a projection for that type. However, if you are including a projection merely for existence, use only system attributes (
DKContantICM.DK_ICM_SYSTEM_ATTRS
) for the
fastest performance. Otherwise the server will include all other
attributes listed as part of the response during the existence check.
Using attribute filters (or projection lists) is not always faster. There is overhead for processing which can consume the difference in performance savings or could require slightly more time. Attribute filters might not show an advantage for filtering out just a few small attributes for small sets of data. Attribute filters show the best advantages in the following cases:
- When large attributes are filtered out (such as large CLOB or BLOB attributes).
- When large numbers of attributes per item or component are filtered out.
- When large numbers of items or components are being retrieved to offset the overhead with small incremental savings per item over a large set of items.
- When entire item types and component types are filtered out by omitted projections.
Using a general wildcard projection (
"*"
) costs additional
overhead to expand the projection based on the actual types of DDOs
submitted for retrieval. The expansion cost is typically considered very
minimal or negligible. However, if you do know all possible types that you
are interested in and if you can reasonably handle detecting which types
contain the attributes you are interested in (if specifying specific
attributes) you can save the cost of expanding the wildcard projection
during each retrieve call by specifying type-specific projections yourself
once up front when creating the projection list. If you reuse the same
projection list in multiple retrieve calls, the wildcard projection is
expanded each time based on the current set of DDOs submitted for each
particular retrieve call. However, if you are not certain of all types
that you are retrieving, such as from a query result, it could cost more to
prematurely expand yourself to too many anticipated item types if
the actual items submitted to retrieve (or returned from a query) include
many fewer actual item types and component types.
If you want to retrieve all attributes of all types, it is slightly faster to not provide attribute filters (specify
null
(default) for a projection list) due to the
minor overhead of processing a projection list described earlier.
For example, setting DKRetrieveOptionsICM::attributeFilters(null) is
slightly faster than specifying a projection list with either a
wildcard projection ("*"
) with the all-attributes
keyword (DKConstantICM.DK_ICM_ALL_ATTRS
) or individual
type-specific projections with the all-attributes keyword or
fully-specifying all attributes.
When requesting all attributes for any given item type or component type projection, it is slightly faster to use the all-attributes keyword (
DKConstantICM.DK_ICM_ALL_ATTRS
) than to list
out all possible attributes for that particular item type or component
type. This keyword is not expanded and is a shortcut bypassing
a slight amount of additional overhead to process each individual
attribute.
BEHAVIOR NOTES
Through the DKRetrieveOptionsICM interface, attribute filters and projection lists never select additional data and only filter data already selected by other options. For example, even if you supply a projection list that has projections for and shows through all child attributes, if you do not request child attributes in the first place, the filter has no effect because it is applied on top of a request that will not return any children to start with. However, this behavior is different from the old projection list interface (DKNVPair[] projections, not DKProjectionListICM), the old projection list overrode any bitwise 'int' retrieve options (or defaults if no options specified) and included all attributes, all children levels, and all children attributes (equivalent to DKConstant.DK_CM_CONTENT_ITEMTREE_NO_LINKS). The old DKNVPair[] projection list interface did in fact select additional data, regardless of the actual retrieve option used (unless you used query and bitwise IDONLY).
There are general projection ('*') behavior considerations and projection list "holes" for which you have several behavior options. There are also more considerations if you desire all component types and all attributes. See related information in DKProjectionListICM class documentation.
See DKProjectionListICM documentation.
When using the DKProjectionListICM interface, there is no need to specify projections for component types or parent component types that are not retrieved. When using the old DKNVPair[] projection list interface, you were required to specify projections with attributes for all parent hierarchy above any projection you specified, even if none of the parents appeared in the result. For example, consider an item type named "Book" and child component type "Chapter". Suppose you used query and obtained a list of chapters. If you wanted to specify a projection list, if you used the old DKNVPair[] projection list format, you were required to specify a projection with attributes for "Book", even though you directly selected "Chapter" components to retrieve. No "Book" components would ever be retrieved, but you were still required to specify a projection and attributes or else an exception was reported. With the newer DKProjectionListICM interface, there is no need to specify such projections. No exception will be thrown if you omit a parent type that is above the directly-selected DDOs.
Parameters:
attributeFilters
- Projection list specifying which attributes are desired for each item type. If 'null', all projections filtering attributes are discarded and all attributes are selected by default.
MEMORY MANAGEMENT (Only C++)
Memory ownership and responsibility for deleting the DKProjectionListICM instance is controlled by optional second parameter, "DKBoolean mustFreeMemory".
By default, the caller remains the owner of the DKProjectionListICM instance submitted and can be used in multiple retrieve options objects. This instance merely references the original instance.
The caller is responsible for freeing the memory for the DKProjectionListICM instance after this DKRetrieveOptionsICM instance is no longer needed.
attributeFilters
- public DKProjectionListICM attributeFilters( )
See DKRetrieveOptionsICM::baseAttributes(boolean baseAttributesRequested).
baseAttributes
- public void baseAttributes(boolean baseAttributesRequested)
Request user and core system attributes for directly selected component DDOs.
This option only requests attributes for directly selected DDOs such as:
Other DDOs that are retrieved under the directly selected DDOs are not included by this retrieve option. This option does not include children, linked items, folder contents, document parts, or any other related DDO unless their DDO instances also appear in the original selected list. This does not mean that this option applies only root component DDOs. For example, if your query returns a list of DDOs that directly include children and document parts, the attributes of those DDOs will be retrieved. If you have a list of child component DDOs that you want to retrieve, you can submit the collection of child components to multi-item retrieve and use this retrieve option setting to retrieve their attributes. However, if you select a root component to an item and through another option you request children, this option does not request attributes of the children as well. In this case, only the root component attributes are retrieved for the particular DDO selected. Unless another child attribute option is requested, the child components of the root component are not retrieved.
The system attributes covered by this setting by default are only the "core" properties that are persisted just like attributes in the same table. Other properties are not included if they are typically used less often and require additional overhead, such as joining another table on the server (such as checked out username) or requiring a measurable definition lookup that incurs a measurable performance hit if that definition set had not yet been cached (such as ACL name). For any property typically not needed or requires specific setting to acknowledge the performance cost, separate baseProperty____() settings. See all baseProperty____() methods, such as:
This option is also responsible for loading values for resource content system attributes accessed through the DKLobICM interface for any directly selected component that supports resource content (root component of a resource item or document part ("resource" or "doc-part" classified item types)). For example, this setting loads the mime type, original file name, and content size that can be accessed through the DKLobICM interface (more details in the "DATA STRUCTURES" section). Note that this setting does not load such data for document parts listed under directly selected parent documents (root components of "document"-classified item types) through the partsList(boolean) option. Use partsAttributes(boolean) to load such data for document parts listed through partList(boolean).
DEFAULT: false
PRECEDENCE
This setting is independent.
PERFORMANCE
Improve performance by requesting only subset of attributes that you desire. If you are only interested in some of the attributes, specify which attributes you want to be retrieved, saving time and memory by omitting those that you do not need.
See DKRetrieveOptionsICM::attributeFilters(DKProjectionListICM attributeFilters).
DATA STRUCTURES
User-defined attributes retrieved are added to their respective parent DDOs as a "data item" in the DKDDO object, in the attribute namespace. You can iterate through all attributes in a DKDDO by looping through all data item IDs from '0' to "ddo.dataCount()" (across all "data item" namespaces which can include other "data items" than attributes but can be identified by a type indicator). You can also look up attributes by name. To determine if an attribute exists, first look up the "data item" ID using ddo.dataId(DKConstant.DK_CM_NAMESPACE_ATTR,<your attribute name as String>). If the ID returned is '-1', no data item by that name exists. Once you have a valid ID or if you are listing through each ID, you can obtain the individual attribute name ("ddo.getDataName(dataid)"), value ("ddo.getData(dataid)"), and value type ((short) ddoItem.getDataPropertyByName(dataid,DK_CM_PROPERTY_TYPE)) to help you cast or otherwise handle correctly. (Details on detecting and handling all types explained in the SItemRetrievalICM sample.) Due to various retrieve options, filtered views, and other circumstances, you should always lookup attributes by ID and detect if they exist or not.
For examples and details accessing attributes, refer to the SItemRetrievalICM API education sample.
System-defined properties retrieved are added to their parent DDOs as a "property" in the DKDDO object, which is a separate list compared to the "data items" where user-defined attributes are stored. Similarly to "data items", you can list all properties from '0' to "ddo.propertyCount()" or detect if a property exists using the ddo.propertyId(<property name as String>). If the ID returned is '-1', no property exists by that name. Once you have an ID, you can look up the individual property name (ddo.getPropertyName(propertyId)) and value (ddo.getProperty(propertyId)). There are no namespaces for properties and there is no value type indicator. You must follow documentation to know what value types to cast to. Due to various possible states of DDOs and various retrieve options, always lookup properties by ID to first detect if they exist or not.
System attributes can vary for different component types and are not necessarily restricted to one set. The most common system attributes are based on the "SYSROOTATTRS" system attribute group which can appear in some definition listings. However the actual DKDDO property values do not necessarily use the same name as the system attribute names or carry the exactly value. For example, IDs are managed by the system internally and the DKDDO property typically surfaces names instead of IDs. Note that only some system attributes are queryable and when placing query conditions, they are based on the system attribute name and actual persisted values and typically do not include the attribute group name.
For any directly selected component DDO that supports resource content (root components of resource items or document parts ("resource" or "doc-part" classified item types)), resource content system attributes are retrieved through this setting. However, resource content system attributes are not stored as DKDDO "properties" and are instead loaded into the DKLobICM instance (or subclass) extension of DKDDO and are instead accessible through various DKLobICM::get___() methods. (See resourceContent(boolean) section "DATA STRUCTURES" for more details on detecting the DKLobICM subclass of DKDDO and more details regarding resource content.) The resource content system attributes are based on the "RESOURCEBLOB" system attribute group which can appear in some definition listings. The following system attribute / properties are loaded as a result of this call.
BEHAVIOR NOTES
Regardless of whether base attributes are requested, as long as at least some data is requested, an existence check is always performed on the directly-selected base DDOs, which are marked with an indicator for success/failure. Even if baseAttributes(false), as long as some other data is requested, an existence check is performed. If no data is requested, no existence check is performed. For more information on success/failure data structures and details, see documentation for DKRetrieveOptionsICM::behaviorIgnoreNoneFoundError(boolean) even if you are not using that setting.
See DKRetrieveOptionsICM::behaviorIgnoreNoneFoundError(boolean) (even if not using setting)
Under the old bitwise 'int' options if base attributes were not requested (such as if you used the CHILDREN retrieve option), no existence check was made and the base DDOs were listed as FAILED with one exception, when children were requested and a non-zero children count was found for the base DDOs. For example, when childListOneLevel(true) and baseAttributes(false), an existence check is performed on the directly-selected base DDOs and all directly selected base DDOs have their success/failure indicators set to SUCCESS if they were found, regardless of how many children they have. This also means that query will not filter out results in this case when a result DDO happens to have '0' children. These two settings are very similar to the old bitwise 'int' retrieve option DK_CM_CONTENT_CHILDREN, which behaved differently in this respect. The bitwise DK_CM_CONTENT_CHILDREN option is used, any base DDOs submitted to retrieve will be marked as FAILED. Since no attributes were requested for the base DDOs, the server returns no response under the old CHILDREN option. For any have children, they are confirmed to exist and are marked as SUCCESS. There is no distinction between those that have '0' children and those that do not exist, are duplicates, or failed for any other reason. Query only returns successful DDOs. Therefore, under the old bitwise DK_CM_CONTENT_CHILDREN option, query only returned those that have non-zero child counts. With the newer DKRetrieveOptionsICM interface, an existence check is always performed as long as something is requested and query will return not just those with non-zero child counts. (For more information on success/failure indicators, see method DKRetrieveOptionsICM::behaviorIgnoreNoneFoundError(boolean) even if you are not using that setting).
- The single DDO upon which a single-item retrieve call is made.
- All DDOs directly listed in a collection submitted to multi-item retrieve.
- All DDOs directly returned by query results.
Other DDOs that are retrieved under the directly selected DDOs are not included by this retrieve option. This option does not include children, linked items, folder contents, document parts, or any other related DDO unless their DDO instances also appear in the original selected list. This does not mean that this option applies only root component DDOs. For example, if your query returns a list of DDOs that directly include children and document parts, the attributes of those DDOs will be retrieved. If you have a list of child component DDOs that you want to retrieve, you can submit the collection of child components to multi-item retrieve and use this retrieve option setting to retrieve their attributes. However, if you select a root component to an item and through another option you request children, this option does not request attributes of the children as well. In this case, only the root component attributes are retrieved for the particular DDO selected. Unless another child attribute option is requested, the child components of the root component are not retrieved.
The system attributes covered by this setting by default are only the "core" properties that are persisted just like attributes in the same table. Other properties are not included if they are typically used less often and require additional overhead, such as joining another table on the server (such as checked out username) or requiring a measurable definition lookup that incurs a measurable performance hit if that definition set had not yet been cached (such as ACL name). For any property typically not needed or requires specific setting to acknowledge the performance cost, separate baseProperty____() settings. See all baseProperty____() methods, such as:
- DKRetrieveOptionsICM::basePropertyAclName(boolean basePropertyAclNameRequested)
- DKRetrieveOptionsICM::basePropertyCheckedOutDetails(boolean basePropertyCheckedOutDetailsRequested)
This option is also responsible for loading values for resource content system attributes accessed through the DKLobICM interface for any directly selected component that supports resource content (root component of a resource item or document part ("resource" or "doc-part" classified item types)). For example, this setting loads the mime type, original file name, and content size that can be accessed through the DKLobICM interface (more details in the "DATA STRUCTURES" section). Note that this setting does not load such data for document parts listed under directly selected parent documents (root components of "document"-classified item types) through the partsList(boolean) option. Use partsAttributes(boolean) to load such data for document parts listed through partList(boolean).
DEFAULT: false
PRECEDENCE
This setting is independent.
PERFORMANCE
Improve performance by requesting only subset of attributes that you desire. If you are only interested in some of the attributes, specify which attributes you want to be retrieved, saving time and memory by omitting those that you do not need.
See DKRetrieveOptionsICM::attributeFilters(DKProjectionListICM attributeFilters).
DATA STRUCTURES
User-defined attributes retrieved are added to their respective parent DDOs as a "data item" in the DKDDO object, in the attribute namespace. You can iterate through all attributes in a DKDDO by looping through all data item IDs from '0' to "ddo.dataCount()" (across all "data item" namespaces which can include other "data items" than attributes but can be identified by a type indicator). You can also look up attributes by name. To determine if an attribute exists, first look up the "data item" ID using ddo.dataId(DKConstant.DK_CM_NAMESPACE_ATTR,<your attribute name as String>). If the ID returned is '-1', no data item by that name exists. Once you have a valid ID or if you are listing through each ID, you can obtain the individual attribute name ("ddo.getDataName(dataid)"), value ("ddo.getData(dataid)"), and value type ((short) ddoItem.getDataPropertyByName(dataid,DK_CM_PROPERTY_TYPE)) to help you cast or otherwise handle correctly. (Details on detecting and handling all types explained in the SItemRetrievalICM sample.) Due to various retrieve options, filtered views, and other circumstances, you should always lookup attributes by ID and detect if they exist or not.
For examples and details accessing attributes, refer to the SItemRetrievalICM API education sample.
System-defined properties retrieved are added to their parent DDOs as a "property" in the DKDDO object, which is a separate list compared to the "data items" where user-defined attributes are stored. Similarly to "data items", you can list all properties from '0' to "ddo.propertyCount()" or detect if a property exists using the ddo.propertyId(<property name as String>). If the ID returned is '-1', no property exists by that name. Once you have an ID, you can look up the individual property name (ddo.getPropertyName(propertyId)) and value (ddo.getProperty(propertyId)). There are no namespaces for properties and there is no value type indicator. You must follow documentation to know what value types to cast to. Due to various possible states of DDOs and various retrieve options, always lookup properties by ID to first detect if they exist or not.
System attributes can vary for different component types and are not necessarily restricted to one set. The most common system attributes are based on the "SYSROOTATTRS" system attribute group which can appear in some definition listings. However the actual DKDDO property values do not necessarily use the same name as the system attribute names or carry the exactly value. For example, IDs are managed by the system internally and the DKDDO property typically surfaces names instead of IDs. Note that only some system attributes are queryable and when placing query conditions, they are based on the system attribute name and actual persisted values and typically do not include the attribute group name.
For any directly selected component DDO that supports resource content (root components of resource items or document parts ("resource" or "doc-part" classified item types)), resource content system attributes are retrieved through this setting. However, resource content system attributes are not stored as DKDDO "properties" and are instead loaded into the DKLobICM instance (or subclass) extension of DKDDO and are instead accessible through various DKLobICM::get___() methods. (See resourceContent(boolean) section "DATA STRUCTURES" for more details on detecting the DKLobICM subclass of DKDDO and more details regarding resource content.) The resource content system attributes are based on the "RESOURCEBLOB" system attribute group which can appear in some definition listings. The following system attribute / properties are loaded as a result of this call.
DKLobICM Value Based on System Attribute
--------------------- ---------------------------
getMimeType() RESOURCEBLOB.MIMETYPEID
getOrgFileName() RESOURCEBLOB.ORIFNAME
getSize() RESOURCEBLOB.RESOURCELENGTH
getRMName() RESOURCEBLOB.RMCODE
getSMSCollName() RESOURCEBLOB.SMSCOLLCODE
getCreatedTimestamp() RESOURCEBLOB.OBJECTCREATED
getUpdatedTimestamp() RESOURCEBLOB.OBJECTUPDATED
getResourceName() RESOURCEBLOB.EXTOBJECTNAME
BEHAVIOR NOTES
Regardless of whether base attributes are requested, as long as at least some data is requested, an existence check is always performed on the directly-selected base DDOs, which are marked with an indicator for success/failure. Even if baseAttributes(false), as long as some other data is requested, an existence check is performed. If no data is requested, no existence check is performed. For more information on success/failure data structures and details, see documentation for DKRetrieveOptionsICM::behaviorIgnoreNoneFoundError(boolean) even if you are not using that setting.
See DKRetrieveOptionsICM::behaviorIgnoreNoneFoundError(boolean) (even if not using setting)
Under the old bitwise 'int' options if base attributes were not requested (such as if you used the CHILDREN retrieve option), no existence check was made and the base DDOs were listed as FAILED with one exception, when children were requested and a non-zero children count was found for the base DDOs. For example, when childListOneLevel(true) and baseAttributes(false), an existence check is performed on the directly-selected base DDOs and all directly selected base DDOs have their success/failure indicators set to SUCCESS if they were found, regardless of how many children they have. This also means that query will not filter out results in this case when a result DDO happens to have '0' children. These two settings are very similar to the old bitwise 'int' retrieve option DK_CM_CONTENT_CHILDREN, which behaved differently in this respect. The bitwise DK_CM_CONTENT_CHILDREN option is used, any base DDOs submitted to retrieve will be marked as FAILED. Since no attributes were requested for the base DDOs, the server returns no response under the old CHILDREN option. For any have children, they are confirmed to exist and are marked as SUCCESS. There is no distinction between those that have '0' children and those that do not exist, are duplicates, or failed for any other reason. Query only returns successful DDOs. Therefore, under the old bitwise DK_CM_CONTENT_CHILDREN option, query only returned those that have non-zero child counts. With the newer DKRetrieveOptionsICM interface, an existence check is always performed as long as something is requested and query will return not just those with non-zero child counts. (For more information on success/failure indicators, see method DKRetrieveOptionsICM::behaviorIgnoreNoneFoundError(boolean) even if you are not using that setting).
Parameters:
baseAttributesRequested
- If 'true', you request user and system attributes for any directly selected DDO. If 'false', you do not request such attributes.
baseAttributes
- public boolean baseAttributes()
See DKRetrieveOptionsICM::baseAttributes(boolean baseAttributesRequested).
basePropertyAclName
- public void basePropertyAclName( boolean basePropertyAclNameRequested)
If retrieving base attributes (baseAttributes(true)), also retrieve the
ACL Name property / system-attribute for any root components or
document parts directly selected.
This setting specifically controls whether the following DDO property is populated:
The ACL Name property (DKConstantICM.DK_ICM_PROPERTY_ACL (
"Core" properties that are persisted just like attributes in the same table are automatically included with the baseAttributes(boolean baseAttributesRequested) setting if set to true. The ACL Name property is not included by default both because it is typically infrequently used by applications and it requires additional overhead processing the value, including a measurable definition lookup that incurs a measurable performance hit if that definition set had not yet been cached (such as ACL name).
Root components (which hold the ACL for the whole item) and document parts have an ACL Name property. Since access to child components is controlled through the ACL of the entire item, child components do not have their own ACL and therefore have no ACL Name property. This setting has no effect on child components directly submitted to retrieve.
DEFAULT: false
PRECEDENCE
This setting is independent of all other retrieve options, with one exception.
If attribute filters / projection list (DKProjectionListICM) is specified (through DKRetrieveOptionsICM::attributeFilters(DKProjectionListICM)) and if the projection list omits system attributes for some or all projections that apply to component type views of directly selected DDOs, the filter takes precedent and no ACL Name value is returned from the server or populated in the DKDDOs for the component type views whose corresponding projection had omitted system attributes. If the projection list omits entire projections for directly-selected base DDOs, DDOs of that type are not retrieved, no existence check is performed, and no ACL Name property (or any other user or system attribute) are retrieved. No exception is thrown.
You can request this setting independently from the baseAttributes(boolean) setting.
PERFORMANCE
A small, but measurable ACL name lookup is required to populate the ACL name from an ACL code. If the ACL names have not yet been accessed and cached, this lookup can be more noticeable. Since this is typically not used all the time by applications, it is better to omit this property unless you have plans to use it.
For any child component DDOs (which do not have an ACL Name property), there is no cost for these DDOs since there is no ACL name lookup.
DATA STRUCTURES
The ACL Name is stored in a DKDDO as a "property". First, see baseAttributes(boolean baseAttributesRequested) to understand how properties in general are stored in a DKDDO and how they can be accessed.
See DKRetrieveOptionsICM::baseAttributes(boolean baseAttributesRequested)
This DKDDO property is named "SYSROOTATTRS.ACLCODE" and contains a String that specifies the ACL Name (not code) governing access to this item. Again, despite the property name "ACLCODE", it contains a name, not an ID code.
If the ACL property is not requested, the properties will not be added to the DKDDO. It will remain omitted from the DKDDO property list. If it already exist from a previous retrieve call or other operation that had included it, it will not be updated from its previous values.
BEHAVIOR NOTES
Since child components do not have an ACL Name property, this setting has no effect on child components directly submitted to retrieve and no error is reported.
This option's behavior when not requested varies from the behavior when the old bitwise 'int' retrieve options were used. If the bitwise 'int' option DKConstant.DK_CM_CONTENT_RETRIEVE_IGNORE_ACL_NAME (65536) was used, the ACL property is still added or refreshed, but the value is an empty string (""). With the newer DKRetrieveOptionsICM interface, the property is entirely omitted if not requested (or not refreshed if previously set).
This setting specifically controls whether the following DDO property is populated:
- DKConstantICM.DK_ICM_PROPERTY_ACL (
"SYSROOTATTRS.ACLCODE"
) = <String
> - ACL Name (not code) governing access to this item.
The ACL Name property (DKConstantICM.DK_ICM_PROPERTY_ACL (
"SYSROOTATTRS.ACLCODE"
)) only appears on root components.
"Core" properties that are persisted just like attributes in the same table are automatically included with the baseAttributes(boolean baseAttributesRequested) setting if set to true. The ACL Name property is not included by default both because it is typically infrequently used by applications and it requires additional overhead processing the value, including a measurable definition lookup that incurs a measurable performance hit if that definition set had not yet been cached (such as ACL name).
Root components (which hold the ACL for the whole item) and document parts have an ACL Name property. Since access to child components is controlled through the ACL of the entire item, child components do not have their own ACL and therefore have no ACL Name property. This setting has no effect on child components directly submitted to retrieve.
DEFAULT: false
PRECEDENCE
This setting is independent of all other retrieve options, with one exception.
If attribute filters / projection list (DKProjectionListICM) is specified (through DKRetrieveOptionsICM::attributeFilters(DKProjectionListICM)) and if the projection list omits system attributes for some or all projections that apply to component type views of directly selected DDOs, the filter takes precedent and no ACL Name value is returned from the server or populated in the DKDDOs for the component type views whose corresponding projection had omitted system attributes. If the projection list omits entire projections for directly-selected base DDOs, DDOs of that type are not retrieved, no existence check is performed, and no ACL Name property (or any other user or system attribute) are retrieved. No exception is thrown.
You can request this setting independently from the baseAttributes(boolean) setting.
PERFORMANCE
A small, but measurable ACL name lookup is required to populate the ACL name from an ACL code. If the ACL names have not yet been accessed and cached, this lookup can be more noticeable. Since this is typically not used all the time by applications, it is better to omit this property unless you have plans to use it.
For any child component DDOs (which do not have an ACL Name property), there is no cost for these DDOs since there is no ACL name lookup.
DATA STRUCTURES
The ACL Name is stored in a DKDDO as a "property". First, see baseAttributes(boolean baseAttributesRequested) to understand how properties in general are stored in a DKDDO and how they can be accessed.
See DKRetrieveOptionsICM::baseAttributes(boolean baseAttributesRequested)
This DKDDO property is named "SYSROOTATTRS.ACLCODE" and contains a String that specifies the ACL Name (not code) governing access to this item. Again, despite the property name "ACLCODE", it contains a name, not an ID code.
If the ACL property is not requested, the properties will not be added to the DKDDO. It will remain omitted from the DKDDO property list. If it already exist from a previous retrieve call or other operation that had included it, it will not be updated from its previous values.
BEHAVIOR NOTES
Since child components do not have an ACL Name property, this setting has no effect on child components directly submitted to retrieve and no error is reported.
This option's behavior when not requested varies from the behavior when the old bitwise 'int' retrieve options were used. If the bitwise 'int' option DKConstant.DK_CM_CONTENT_RETRIEVE_IGNORE_ACL_NAME (65536) was used, the ACL property is still added or refreshed, but the value is an empty string (""). With the newer DKRetrieveOptionsICM interface, the property is entirely omitted if not requested (or not refreshed if previously set).
Parameters:
basePropertyAclNameRequested
- If 'true', you request the ACL Name property to be populated in directly selected root component DDOs. If 'false', you do not request this property.
basePropertyAclName
- public boolean basePropertyAclName( )
See DKRetrieveOptionsICM::basePropertyAclName(boolean basePropertyAclNameRequested).
basePropertyCheckedOutDetails
- public void basePropertyCheckedOutDetails( boolean basePropertyCheckedOutDetailsRequested)
If retrieving base attributes (baseAttributes(true)), also retrieve the
checked out information properties / system-attributes for any root components
directly selected.
This setting specifically controls whether the following DDO properties are populated:
Only root components are checked out (locked) which govern the entire item (and all children).
"Core" properties that are persisted just like attributes in the same table are automatically included with the baseAttributes(boolean baseAttributesRequested) setting if set to true. The checked out detail properties are not included by default both because they are not always needed by all applications and they require additional overhead to join another table on the server to obtain the checked out status and information.
If you only want to check if DDO is checked out and if you only want the checked out user name, you can use the DKDatastoreExtICM::checkedOutUserid(DKDDO) method which requires one small server call with minimal processing for every DDO you inspect. Although small for one call, if you want to check more than one, this setting is optimized until multi-item retrieve to retrieve the status for multiple items at once.
Children and document parts cannot be directly checked out independently from the root component of the item (or parent document) that contains them. Children and document parts are locked through the root component of the item or document. Therefore child components and document parts do not have independent checked out status to report through their own properties. This setting has no effect on child components or document parts directly submitted to retrieve.
DEFAULT: false
PRECEDENCE
This setting is independent of all other retrieve options, with one exception.
If attribute filters / projection list (DKProjectionListICM) is specified (through DKRetrieveOptionsICM::attributeFilters(DKProjectionListICM)) and if the projection list omits system attributes for some or all projections that apply to component type views of directly selected DDOs, the filter takes precedent and no checked-out detail properties value are returned from the server or populated in the DKDDOs for the component type views whose corresponding projection had omitted system attributes. If the projection list omits entire projections for directly-selected base DDOs, DDOs of that type are not retrieved, no existence check is performed, and no checked-out detail properties (or any other user or system attribute) are retrieved. No exception is thrown.
You can request this setting independently from the baseAttributes(boolean) setting.
PERFORMANCE There is a small, but measurable cost to join the additional checked out table. Since this is typically not used all the time by applications, it is better to omit this property unless you have plans to use it.
DATA STRUCTURES
The Checked Out Details are store in a DKDDO as two "properties". First, see baseAttributes(boolean baseAttributesRequested) to understand how properties in general are stored in a DKDDO and how they can be accessed.
See DKRetrieveOptionsICM::baseAttributes(boolean baseAttributesRequested)
This information is stored in two DKDDO properties, named "Checked_Out_UserID" and "Checked_Out_TS". "Checked_Out_UserID" contains a String that specifies the User ID (in upper-case) that checked out (locked) the item or reports NULL if not checked out. "Checked_Out_TS" contains a DKTimestamp that specifies when the user checked out this time or NULL if not checked out.
If these properties are not requested, the two properties will not be added to the DKDDO. They will remain omitted from the DKDDO property list. If they already exist from a previous retrieve call or other operation that had included them, they will not be updated from their previous values.
BEHAVIOR NOTES
Since child components and document parts do not have independent checked out status information, this setting has no effect on child components or document parts directly submitted to retrieve. No error is reported.
This option's behavior when not requested varies from the behavior when the old bitwise 'int' retrieve options were used. If the bitwise 'int' option DKConstant.DK_CM_CONTENT_RETRIEVE_IGNORE_CHECKEDOUT_INFO (32768) was used, the "Checked_Out_UserID" and "Checked_Out_TS" properties are still added or refreshed, but the values for each are set to NULL, the same result as if the item was not checked out (locked) if you had requested the properties. With the newer DKRetrieveOptionsICM interface, the two properties are entirely omitted if not requested (or not refreshed if previously set).
This setting specifically controls whether the following DDO properties are populated:
- DKConstantICM.DK_ICM_PROPERTY_CHECKEDOUTUSERID (
"Checked_Out_UserID"
) = <String> - User ID (upper-case) that checked out (locked) this item or NULL if not checked out. - DKConstantICM.DK_ICM_PROPERTY_CHECKEDOUTTIMESTAMP (
"Checked_Out_TS"
) = <DKTimestamp> - Timestamp identifying when the user checked out this item or NULL if not checked out.
Only root components are checked out (locked) which govern the entire item (and all children).
"Core" properties that are persisted just like attributes in the same table are automatically included with the baseAttributes(boolean baseAttributesRequested) setting if set to true. The checked out detail properties are not included by default both because they are not always needed by all applications and they require additional overhead to join another table on the server to obtain the checked out status and information.
If you only want to check if DDO is checked out and if you only want the checked out user name, you can use the DKDatastoreExtICM::checkedOutUserid(DKDDO) method which requires one small server call with minimal processing for every DDO you inspect. Although small for one call, if you want to check more than one, this setting is optimized until multi-item retrieve to retrieve the status for multiple items at once.
Children and document parts cannot be directly checked out independently from the root component of the item (or parent document) that contains them. Children and document parts are locked through the root component of the item or document. Therefore child components and document parts do not have independent checked out status to report through their own properties. This setting has no effect on child components or document parts directly submitted to retrieve.
DEFAULT: false
PRECEDENCE
This setting is independent of all other retrieve options, with one exception.
If attribute filters / projection list (DKProjectionListICM) is specified (through DKRetrieveOptionsICM::attributeFilters(DKProjectionListICM)) and if the projection list omits system attributes for some or all projections that apply to component type views of directly selected DDOs, the filter takes precedent and no checked-out detail properties value are returned from the server or populated in the DKDDOs for the component type views whose corresponding projection had omitted system attributes. If the projection list omits entire projections for directly-selected base DDOs, DDOs of that type are not retrieved, no existence check is performed, and no checked-out detail properties (or any other user or system attribute) are retrieved. No exception is thrown.
You can request this setting independently from the baseAttributes(boolean) setting.
PERFORMANCE There is a small, but measurable cost to join the additional checked out table. Since this is typically not used all the time by applications, it is better to omit this property unless you have plans to use it.
DATA STRUCTURES
The Checked Out Details are store in a DKDDO as two "properties". First, see baseAttributes(boolean baseAttributesRequested) to understand how properties in general are stored in a DKDDO and how they can be accessed.
See DKRetrieveOptionsICM::baseAttributes(boolean baseAttributesRequested)
This information is stored in two DKDDO properties, named "Checked_Out_UserID" and "Checked_Out_TS". "Checked_Out_UserID" contains a String that specifies the User ID (in upper-case) that checked out (locked) the item or reports NULL if not checked out. "Checked_Out_TS" contains a DKTimestamp that specifies when the user checked out this time or NULL if not checked out.
If these properties are not requested, the two properties will not be added to the DKDDO. They will remain omitted from the DKDDO property list. If they already exist from a previous retrieve call or other operation that had included them, they will not be updated from their previous values.
BEHAVIOR NOTES
Since child components and document parts do not have independent checked out status information, this setting has no effect on child components or document parts directly submitted to retrieve. No error is reported.
This option's behavior when not requested varies from the behavior when the old bitwise 'int' retrieve options were used. If the bitwise 'int' option DKConstant.DK_CM_CONTENT_RETRIEVE_IGNORE_CHECKEDOUT_INFO (32768) was used, the "Checked_Out_UserID" and "Checked_Out_TS" properties are still added or refreshed, but the values for each are set to NULL, the same result as if the item was not checked out (locked) if you had requested the properties. With the newer DKRetrieveOptionsICM interface, the two properties are entirely omitted if not requested (or not refreshed if previously set).
Parameters:
basePropertyCheckedOutDetailsRequested
- If 'true', you request the checked out detail properties to be populated in directly selected root component DDOs. If 'false', you do not request these properties.
basePropertyCheckedOutDetails
- public boolean basePropertyCheckedOutDetails( )
See DKRetrieveOptionsICM::basePropertyCheckedOutDetails(boolean basePropertyCheckedOutDetailsRequested).
childListOneLevel
- public void childListOneLevel(boolean childListOneLevelRequested)
Request the next level of child components listed (table of contents (TOC))
for directly selected component DDOs. Any other DDO not directly listed
as selected DDOs to retrieve will not have any of its children retrieved.
For example, if a root component is selected for retrieval with this option,
only the first level of children are retrieved for the parent. Any grandchildren,
linked items, folder contents, document parts, or otherwise referenced DDOs
will not have their children retrieved by this option. If a child component
is selected for retrieve directly, its first generation of children are retrieved.
This option only lists children, blank DKDDOs with completed PID information that uniquely identifies a child for subsequent retrieve or delete requests. Child attributes are requested through a separate childAttributes() retrieve option. Grandchildren are controlled by using the childListAllLevels() retrieve option.
This option includes all direct descendent child component types by default. However, you can specify a specific list of child component types you are interested in, omitting any child types you do not desire. Child component types can be filtered using attribute (and child component type) filters (DKProjectionListICM). Create a DKProjectionListICM and submit through the attributeFilters(DKProjectionListICM) setting.
See DKRetrieveOptionsICM::attributeFilters(DKProjectionListICM attributeFilters).
DEFAULT: false
PRECEDENCE
This setting is independent of other settings, except for projection lists (if any submitted as attribute filters) that can filter out entire child component types or entire base DDOs submitted for which the child list is requested.
The projection list specified through DKRetrieveOptionsICM::attributeFilters(DKProjectionListICM) can filter out entire child component types from retrieval by omitting projections for the component type (if a projection list / filter is provided). Any childListOneLevel(true) request lists all children that show through the filter (i.e. have a projection for the respective component type view). No exceptions are thrown if children listed are filtered by the projection list.
Additionally, projection lists can filter out the base DDOs directly submitted to retrieve for which the child list is requested by omitting a projection for the base DDO type. In order to retrieve any children for any given item type view or component type view to which a DDO belongs, you must include the base DDOs submitted to retrieve in the projection list. Otherwise if omitted, all DDOs submitted to retrieve for any component type view (or item type view) that is filtered out due to omission will not be submitted to the server for an existence check nor have its children listed. To list children, you do not need to request meta data for the base DDO (you can still choose DKRetrieveOptionsICM::baseAttributes(false) (default)), however, if submitting attribute filters (projection list), the projection list is always honored. If you omit projections for DDOs submitted, the entire DDO is considered filtered out. You cannot retrieve children if you exclude the DDO to which the children are to be listed. You can either specify a projection for all types of directly submitted base DDOs and include system attributes (
If you request childListOneLevel(false) (specifically excluding the first level of children), you cannot request childListAllLevels(true) too. The all-levels child list request does not override this one-level child list request or exclusion. For more details, see the "PRECEDENCE" section of childListAllLevels(boolean).
PERFORMANCE Improve performance by requesting only subset of child component types that you desire. If you are only interested in some of the child component types, specify which child component types you want to be retrieved, saving time and memory by omitting those that you do not need. Use attribute (and component type) filters and omit a projection for the undesired child component types. You only retrieve the attributes and child components specifically specified in the projection list.
See DKRetrieveOptionsICM::attributeFilters(DKProjectionListICM attributeFilters).
DATA STRUCTURES
Child components retrieved are added to their respective parent DKDDO as a DKChildCollection (dkCollection interface), one for each child component type, each collection containing DKDDOs representing each child instance. The child collections are added as a "data item" to their parent DKDDO object in the children namespace.
You can iterate through all child collections in a DKDDO by looping through all data item IDs from '0' to "ddo.dataCount()" (across all "data item" namespaces which can include other "data items" than child collections but can be identified by a type indicator). You can also look up child collections by name (child component type name). To determine if a child collection exists, first look up the "data item" ID using ddo.dataId(DKConstant.DK_CM_NAMESPACE_CHILD,<your component type name as String>). If the ID returned is '-1', no data item by that name exists. Once you have a valid ID or if you are listing through each ID, you can obtain the individual data item name ("ddo.getDataName(dataid)"), value ("ddo.getData(dataid)"), and value type ((short) ddoItem.getDataPropertyByName(dataid,DK_CM_PROPERTY_TYPE)) to help you cast or otherwise handle correctly. Child collections appear with data item type DK_CM_DATAITEM_TYPE_COLLECTION_DDO along with the folder contents listing, but folder contents appear in the attribute namespace and can be distinguished by "data item" name DKConstant.DK_CM_DKFOLDER ("DKFolder"). (Details on detecting and handling all types explained in the SItemRetrievalICM sample.) Due to various retrieve options, filtered views, and other circumstances, you should always lookup child collections by ID and detect if they exist or not.
For child component type views that currently have no children, empty child collections are added indicating that no children currently exist for the particular child type and providing a collection for which you can add new child instances. However, empty chlid collections are added only for child types not excluded by the projection list (attribute filters). Similarly, existing child collections in existing DDOs are cleared, but only the types not excluded by the projection list. This way only the requested child component types are cleared and then populated with the latest data from the server.
For examples and details accessing children, refer to the SItemCreationICM and SItemRetrievalICM API education samples.
BEHAVIOR NOTES
If no children are defined for the item types of DDOs selected or if children are defined but no children are found, the call returns without error. No exceptions are thrown.
When using the DKRetrieveOptionsICM interface to pass options, child collections are not added for special system child collections with names similar to "ICMParts1006" (actual appended number varies). A special child component type named "ICMParts1006" (or any with similar names) that might appear in "document"-classified item types. Although this child component type can be listed when you list all (user + system) sub-entities under a component type view definition, the system component types starting with "ICMParts10..." have no use in a DKDDO as a child collection and are omitted when using the new options interface. However, when using the older bitwise 'int' retrieve options (or defaults if no options specified), a special empty child collection appears as a DKDDO "data item" in the DKConstant.DK_CM_NAMESPACE_CHILD namespace with a name similar to "ICMParts10__" and has data item type DK_CM_DATAITEM_TYPE_COLLECTION_DDO. This collection appears when using the old options (or defaults) when the item type is classified as "document" and when the bitwise retrieve option is not DKConstant.DK_CM_CONTENT_CHILDREN (or if additionally DKConstant.DK_CM_CONTENT_IDONLY if you used query). If you use the old bitwise int options (or defaults), ignore (do not use) any such "ICMParts10..." child collection. Parts are listed through the true parts collection created and populated by the DKRetrieveOptionsICM::partsList(boolean) setting, which is not a child collection and is not in the child DKDDO "data item" namespace.
When child listing is not requested (childListOneLevel(false) and childListAllLevels(false)), retrieve does not add or modify child collections (DKChildCollection instances set a DKDDO "data items" in the CHILD namespace) for the selected DKDDOs. If children have not been previously listed in the selected DKDDOs, child collections are omitted entirely unless requested, not even empty child collections. If child collections already exist int the selected DKDDO instances (such as if children were previously listed or otherwise exist in the selected DDOs), the existing child collections or child instances will not be modified in any way (or cleared). For example, if you choose to retrieve with only baseAttributes(true), this is treated as a "refresh base attributes only" request and simply refreshes exactly what you requested, leaving other DKDDO data structures in your DKDDO in-tact. If children previously existed in the DKDDO, the old values remain untouched.
However, this behavior (not creating empty collections and not clearing existing child collections when no child listing requested) is different from the old bitwise 'int' options or defaults if no options specified. The old bitwise 'int' options (or defaults) always created empty collections and cleared any existing collections. For example, if performed ddo.retrieve(DKConstant.DK_CM_CONTENT_ATTRONLY), even though you only refreshed attributes, the empty child collections are populated in the DKDDO and any existing child collections are cleared.
When using projection lists (attributeFilters(DKProjectionListICM)), Empty child collections are populated only for child component types that show through the filter. If refreshing (re-retrieving) existing DDOs, existing child collections for child types omitted by your projection list are not removed or cleared. Retrieve modifies only data that you request and leaves other collections as they were. If you had other child collections in your DDO that you are not refreshing, they will remain with their original contents.
When childListOneLevel(true) and baseAttributes(false), an existence check is performed on the directly-selected base DDOs and all directly selected base DDOs have their success/failure indicators set to SUCCESS if they were found, regardless of how many children they have. This also means that query will not filter out results in this case when a result DDO happens to have '0' children. These two settings are very similar to the old bitwise 'int' retrieve option DK_CM_CONTENT_CHILDREN, which behaved differently in this respect. The bitwise DK_CM_CONTENT_CHILDREN option is used, any base DDOs submitted to retrieve will be marked as FAILED. Since no attributes were requested for the base DDOs, the server returns no response under the old CHILDREN option. For any have children, they are confirmed to exist and are marked as SUCCESS. There is no distinction between those that have '0' children and those that do not exist, are duplicates, or failed for any other reason. Query only returns successful DDOs. Therefore, under the old bitwise DK_CM_CONTENT_CHILDREN option, query only returned those that have non-zero child counts. With the newer DKRetrieveOptionsICM interface, an existence check is always performed as long as something is requested and query will return not just those with non-zero child counts. (For more information on success/failure indicators, see method DKRetrieveOptionsICM::behaviorIgnoreNoneFoundError(boolean) even if you are not using that setting).
When childListOneLevel(true) (or childListAllLevels(true)), all existing child collections (DKChildCollections) (regardless of child component view type) under the directly-selected DKDDOs are cleared. Although any projection list specified through the attributeFilters(DKProjectionListICM) setting can restrict retrieval to specific child component types, it does not mean that existing children of other types will remain as if to only refresh the specified child component type. Within child collections, outdated child information is not mixed with new child information. If you previously had children of several child component types populated in your DKDDO and then re-retrieved or refreshed with a projection list that included a subset of the child component types, all existing children will be cleared, not just children of the types listed in the projection list.
This option only lists children, blank DKDDOs with completed PID information that uniquely identifies a child for subsequent retrieve or delete requests. Child attributes are requested through a separate childAttributes() retrieve option. Grandchildren are controlled by using the childListAllLevels() retrieve option.
This option includes all direct descendent child component types by default. However, you can specify a specific list of child component types you are interested in, omitting any child types you do not desire. Child component types can be filtered using attribute (and child component type) filters (DKProjectionListICM). Create a DKProjectionListICM and submit through the attributeFilters(DKProjectionListICM) setting.
See DKRetrieveOptionsICM::attributeFilters(DKProjectionListICM attributeFilters).
DEFAULT: false
PRECEDENCE
This setting is independent of other settings, except for projection lists (if any submitted as attribute filters) that can filter out entire child component types or entire base DDOs submitted for which the child list is requested.
The projection list specified through DKRetrieveOptionsICM::attributeFilters(DKProjectionListICM) can filter out entire child component types from retrieval by omitting projections for the component type (if a projection list / filter is provided). Any childListOneLevel(true) request lists all children that show through the filter (i.e. have a projection for the respective component type view). No exceptions are thrown if children listed are filtered by the projection list.
Additionally, projection lists can filter out the base DDOs directly submitted to retrieve for which the child list is requested by omitting a projection for the base DDO type. In order to retrieve any children for any given item type view or component type view to which a DDO belongs, you must include the base DDOs submitted to retrieve in the projection list. Otherwise if omitted, all DDOs submitted to retrieve for any component type view (or item type view) that is filtered out due to omission will not be submitted to the server for an existence check nor have its children listed. To list children, you do not need to request meta data for the base DDO (you can still choose DKRetrieveOptionsICM::baseAttributes(false) (default)), however, if submitting attribute filters (projection list), the projection list is always honored. If you omit projections for DDOs submitted, the entire DDO is considered filtered out. You cannot retrieve children if you exclude the DDO to which the children are to be listed. You can either specify a projection for all types of directly submitted base DDOs and include system attributes (
DKContantICM.DK_ICM_SYSTEM_ATTRS
)
(just to add a projection) or request system attributes through a general
projection that applies to and automatically includes all types.
Regardless of actual attributes listed in the projection, retrieve options
such as DKRetrieveOptionsICM::baseAttributes(false) take precedence to
exclude retrieving the attributes, but the projection allows the base
DDO to be included. For best performance, use only system attributes
when attempting to merely include a projection for existence.
If desired, you can use the filtering feature to filter out base DDOs
to restrict which DDOs for which you want children listed.
If you request childListOneLevel(false) (specifically excluding the first level of children), you cannot request childListAllLevels(true) too. The all-levels child list request does not override this one-level child list request or exclusion. For more details, see the "PRECEDENCE" section of childListAllLevels(boolean).
PERFORMANCE Improve performance by requesting only subset of child component types that you desire. If you are only interested in some of the child component types, specify which child component types you want to be retrieved, saving time and memory by omitting those that you do not need. Use attribute (and component type) filters and omit a projection for the undesired child component types. You only retrieve the attributes and child components specifically specified in the projection list.
See DKRetrieveOptionsICM::attributeFilters(DKProjectionListICM attributeFilters).
DATA STRUCTURES
Child components retrieved are added to their respective parent DKDDO as a DKChildCollection (dkCollection interface), one for each child component type, each collection containing DKDDOs representing each child instance. The child collections are added as a "data item" to their parent DKDDO object in the children namespace.
You can iterate through all child collections in a DKDDO by looping through all data item IDs from '0' to "ddo.dataCount()" (across all "data item" namespaces which can include other "data items" than child collections but can be identified by a type indicator). You can also look up child collections by name (child component type name). To determine if a child collection exists, first look up the "data item" ID using ddo.dataId(DKConstant.DK_CM_NAMESPACE_CHILD,<your component type name as String>). If the ID returned is '-1', no data item by that name exists. Once you have a valid ID or if you are listing through each ID, you can obtain the individual data item name ("ddo.getDataName(dataid)"), value ("ddo.getData(dataid)"), and value type ((short) ddoItem.getDataPropertyByName(dataid,DK_CM_PROPERTY_TYPE)) to help you cast or otherwise handle correctly. Child collections appear with data item type DK_CM_DATAITEM_TYPE_COLLECTION_DDO along with the folder contents listing, but folder contents appear in the attribute namespace and can be distinguished by "data item" name DKConstant.DK_CM_DKFOLDER ("DKFolder"). (Details on detecting and handling all types explained in the SItemRetrievalICM sample.) Due to various retrieve options, filtered views, and other circumstances, you should always lookup child collections by ID and detect if they exist or not.
For child component type views that currently have no children, empty child collections are added indicating that no children currently exist for the particular child type and providing a collection for which you can add new child instances. However, empty chlid collections are added only for child types not excluded by the projection list (attribute filters). Similarly, existing child collections in existing DDOs are cleared, but only the types not excluded by the projection list. This way only the requested child component types are cleared and then populated with the latest data from the server.
For examples and details accessing children, refer to the SItemCreationICM and SItemRetrievalICM API education samples.
BEHAVIOR NOTES
If no children are defined for the item types of DDOs selected or if children are defined but no children are found, the call returns without error. No exceptions are thrown.
When using the DKRetrieveOptionsICM interface to pass options, child collections are not added for special system child collections with names similar to "ICMParts1006" (actual appended number varies). A special child component type named "ICMParts1006" (or any with similar names) that might appear in "document"-classified item types. Although this child component type can be listed when you list all (user + system) sub-entities under a component type view definition, the system component types starting with "ICMParts10..." have no use in a DKDDO as a child collection and are omitted when using the new options interface. However, when using the older bitwise 'int' retrieve options (or defaults if no options specified), a special empty child collection appears as a DKDDO "data item" in the DKConstant.DK_CM_NAMESPACE_CHILD namespace with a name similar to "ICMParts10__" and has data item type DK_CM_DATAITEM_TYPE_COLLECTION_DDO. This collection appears when using the old options (or defaults) when the item type is classified as "document" and when the bitwise retrieve option is not DKConstant.DK_CM_CONTENT_CHILDREN (or if additionally DKConstant.DK_CM_CONTENT_IDONLY if you used query). If you use the old bitwise int options (or defaults), ignore (do not use) any such "ICMParts10..." child collection. Parts are listed through the true parts collection created and populated by the DKRetrieveOptionsICM::partsList(boolean) setting, which is not a child collection and is not in the child DKDDO "data item" namespace.
When child listing is not requested (childListOneLevel(false) and childListAllLevels(false)), retrieve does not add or modify child collections (DKChildCollection instances set a DKDDO "data items" in the CHILD namespace) for the selected DKDDOs. If children have not been previously listed in the selected DKDDOs, child collections are omitted entirely unless requested, not even empty child collections. If child collections already exist int the selected DKDDO instances (such as if children were previously listed or otherwise exist in the selected DDOs), the existing child collections or child instances will not be modified in any way (or cleared). For example, if you choose to retrieve with only baseAttributes(true), this is treated as a "refresh base attributes only" request and simply refreshes exactly what you requested, leaving other DKDDO data structures in your DKDDO in-tact. If children previously existed in the DKDDO, the old values remain untouched.
However, this behavior (not creating empty collections and not clearing existing child collections when no child listing requested) is different from the old bitwise 'int' options or defaults if no options specified. The old bitwise 'int' options (or defaults) always created empty collections and cleared any existing collections. For example, if performed ddo.retrieve(DKConstant.DK_CM_CONTENT_ATTRONLY), even though you only refreshed attributes, the empty child collections are populated in the DKDDO and any existing child collections are cleared.
When using projection lists (attributeFilters(DKProjectionListICM)), Empty child collections are populated only for child component types that show through the filter. If refreshing (re-retrieving) existing DDOs, existing child collections for child types omitted by your projection list are not removed or cleared. Retrieve modifies only data that you request and leaves other collections as they were. If you had other child collections in your DDO that you are not refreshing, they will remain with their original contents.
When childListOneLevel(true) and baseAttributes(false), an existence check is performed on the directly-selected base DDOs and all directly selected base DDOs have their success/failure indicators set to SUCCESS if they were found, regardless of how many children they have. This also means that query will not filter out results in this case when a result DDO happens to have '0' children. These two settings are very similar to the old bitwise 'int' retrieve option DK_CM_CONTENT_CHILDREN, which behaved differently in this respect. The bitwise DK_CM_CONTENT_CHILDREN option is used, any base DDOs submitted to retrieve will be marked as FAILED. Since no attributes were requested for the base DDOs, the server returns no response under the old CHILDREN option. For any have children, they are confirmed to exist and are marked as SUCCESS. There is no distinction between those that have '0' children and those that do not exist, are duplicates, or failed for any other reason. Query only returns successful DDOs. Therefore, under the old bitwise DK_CM_CONTENT_CHILDREN option, query only returned those that have non-zero child counts. With the newer DKRetrieveOptionsICM interface, an existence check is always performed as long as something is requested and query will return not just those with non-zero child counts. (For more information on success/failure indicators, see method DKRetrieveOptionsICM::behaviorIgnoreNoneFoundError(boolean) even if you are not using that setting).
When childListOneLevel(true) (or childListAllLevels(true)), all existing child collections (DKChildCollections) (regardless of child component view type) under the directly-selected DKDDOs are cleared. Although any projection list specified through the attributeFilters(DKProjectionListICM) setting can restrict retrieval to specific child component types, it does not mean that existing children of other types will remain as if to only refresh the specified child component type. Within child collections, outdated child information is not mixed with new child information. If you previously had children of several child component types populated in your DKDDO and then re-retrieved or refreshed with a projection list that included a subset of the child component types, all existing children will be cleared, not just children of the types listed in the projection list.
Parameters:
childListOneLevelRequested
- If 'true', you request the next level of children for any directly selected DDO. If 'false', you do not request such children.
childListOneLevel
- public boolean childListOneLevel( )
See DKRetrieveOptionsICM::childListOneLevel(boolean childListOneLevelRequested)
childListAllLevels
- public void childListAllLevels( boolean childListAllLevelsRequested)
Request the all generations / levels of child components listed
(table of contents (TOC)) for directly selected component DDOs. Except
for descendents that are retrieve which will have their corresponding children
retrieved as part of "all levels", any other DDO not directly listed
as selected DDOs to retrieve will not have any of its children retrieved.
Any linked items, folder contents, document parts, or otherwise referenced DDOs
will not have their children retrieved by this option. This option does not
retrieve parent DDOs. If a child component is selected for retrieve directly,
all levels of its children are retrieved, but its ancestors or parents will
not have their children retrieved unless otherwise directly selected.
This option only lists children, blank DKDDOs with completed PID information (that uniquely identifies a child for subsequent retrieve or delete requests) AND a listing of each of their children (following the "DATA STRUCTURES" outlined below). Child attributes are requested through a separate childAttributes() retrieve option.
This option includes all descendent child component types (all levels) by default. However, you can specify a specific list of child component types you are interested in, omitting any child types you do not desire. Child component types can be filtered using attribute (and child component type) filters (DKProjectionListICM). Create a DKProjectionListICM and submit through the attributeFilters(DKProjectionListICM) setting.
See DKRetrieveOptionsICM::attributeFilters(DKProjectionListICM attributeFilters).
DEFAULT: false
PRECEDENCE
You cannot omit the first level of children and retrieve the rest. If you specifically exclude the first level of children with a childListOneLevel(false) request (the default), there are no first level children for which the remaining levels of children can be retrieved. Requests for both all-levels of children and excluding the first level of children are contradictory and cannot be used together. The all-levels child list request does not override the one-level child list request or exclusion.
To request childListAllLevels(true), you must also request childListOneLevel(true). If you truly want to omit the first level of children, do not request all levels since there would be nothing to retrieve. If you want to omit only some types of first level children, you can use attribute filters / projection list to entirely omit children of specific types.
If childListOneLevel(false) and childListAllLevels(true), DKUsageError with error ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) is thrown (appended with text describing the offending options).
Additionally, any projection list specified through DKRetrieveOptionsICM::attributeFilters(DKProjectionListICM) can filter out entire child component types from retrieval by omitting projections for the component type (if a projection list / filter is provided). Any childListAllLevels(true) request lists all children that show through the filter (i.e. have a projection for the respective component type view). No exceptions are thrown if children listed are filtered by the projection list.
Also, if projections are missing for any of the first level children, just like a childListOneLevel(false) request, no children can be retrieved under the missing first-level DKDDOs. This is considered a projection list hole and could be your intent. If you omit any first level child component types, no children defined under that type can be retrieved, regardless of filters provided for additional levels of children. You can add a general wildcard projection (
PERFORMANCE
The same performance considerations apply as described in DKRetrieveOptionsICM::childListOneLevel(boolean childListOneLevelRequested), except that the same considerations extend to all levels of children.
See "PERFORMANCE" section for method DKRetrieveOptionsICM::childListOneLevel(boolean childListOneLevelRequested).
DATA STRUCTURES
The same data structures apply as described in DKRetrieveOptionsICM::childListOneLevel(boolean childListOneLevelRequested), except that each of the child component DKDDOs will in turn have their children listed as DKChildCollections for each of their child types containing DKDDOs for each of their own children. This builds a graph starting from the parents.
See "DATA STRUCTURES" section for method DKRetrieveOptionsICM::childListOneLevel(boolean childListOneLevelRequested).
BEHAVIOR NOTES
The same behavior notes apply as described in DKRetrieveOptionsICM::childListOneLevel(boolean childListOneLEvelRequested).
See "BEHAVIOR NOTES" section for method DKRetrieveOptionsICM::childListOneLevel(boolean childListOneLevelRequested).
This option only lists children, blank DKDDOs with completed PID information (that uniquely identifies a child for subsequent retrieve or delete requests) AND a listing of each of their children (following the "DATA STRUCTURES" outlined below). Child attributes are requested through a separate childAttributes() retrieve option.
This option includes all descendent child component types (all levels) by default. However, you can specify a specific list of child component types you are interested in, omitting any child types you do not desire. Child component types can be filtered using attribute (and child component type) filters (DKProjectionListICM). Create a DKProjectionListICM and submit through the attributeFilters(DKProjectionListICM) setting.
See DKRetrieveOptionsICM::attributeFilters(DKProjectionListICM attributeFilters).
DEFAULT: false
PRECEDENCE
You cannot omit the first level of children and retrieve the rest. If you specifically exclude the first level of children with a childListOneLevel(false) request (the default), there are no first level children for which the remaining levels of children can be retrieved. Requests for both all-levels of children and excluding the first level of children are contradictory and cannot be used together. The all-levels child list request does not override the one-level child list request or exclusion.
To request childListAllLevels(true), you must also request childListOneLevel(true). If you truly want to omit the first level of children, do not request all levels since there would be nothing to retrieve. If you want to omit only some types of first level children, you can use attribute filters / projection list to entirely omit children of specific types.
If childListOneLevel(false) and childListAllLevels(true), DKUsageError with error ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) is thrown (appended with text describing the offending options).
Additionally, any projection list specified through DKRetrieveOptionsICM::attributeFilters(DKProjectionListICM) can filter out entire child component types from retrieval by omitting projections for the component type (if a projection list / filter is provided). Any childListAllLevels(true) request lists all children that show through the filter (i.e. have a projection for the respective component type view). No exceptions are thrown if children listed are filtered by the projection list.
Also, if projections are missing for any of the first level children, just like a childListOneLevel(false) request, no children can be retrieved under the missing first-level DKDDOs. This is considered a projection list hole and could be your intent. If you omit any first level child component types, no children defined under that type can be retrieved, regardless of filters provided for additional levels of children. You can add a general wildcard projection (
"*"
)
with system attributes selected (DKConstantICM.DK_ICM_SYSTEM_ATTRS
)
for all component types to ensure a minimum level of selection of all
component types if it is not your intent to omit them. See
DKProjectionListICM documentation for more information on omitted
projections.
PERFORMANCE
The same performance considerations apply as described in DKRetrieveOptionsICM::childListOneLevel(boolean childListOneLevelRequested), except that the same considerations extend to all levels of children.
See "PERFORMANCE" section for method DKRetrieveOptionsICM::childListOneLevel(boolean childListOneLevelRequested).
DATA STRUCTURES
The same data structures apply as described in DKRetrieveOptionsICM::childListOneLevel(boolean childListOneLevelRequested), except that each of the child component DKDDOs will in turn have their children listed as DKChildCollections for each of their child types containing DKDDOs for each of their own children. This builds a graph starting from the parents.
See "DATA STRUCTURES" section for method DKRetrieveOptionsICM::childListOneLevel(boolean childListOneLevelRequested).
BEHAVIOR NOTES
The same behavior notes apply as described in DKRetrieveOptionsICM::childListOneLevel(boolean childListOneLEvelRequested).
See "BEHAVIOR NOTES" section for method DKRetrieveOptionsICM::childListOneLevel(boolean childListOneLevelRequested).
childListAllLevels
- public boolean childListAllLevels( )
See DKRetrieveOptionsICM::childListAllLevels(boolean childListAllLevelsRequested)
childAttributes
- public void childAttributes(boolean childAttributesRequested)
Request user and system attributes for child components retrieved under
the directly selected component DDOs if the "child list / TOC"
options are requested. The "child list" options (childListOneLevel()
and childListAllLevels()) retrieve only blank DDOs with completed PID
information. This option populates those DDOs with attributes.
This option only applies to children indirectly retrieved through child list retrieve options and populated within the directly selected DDOs. This does not retrieve any attributes for DDOs directly specified in a list of DDOs to retrieve, even if one of the directly selected DDOs happens to be a child component. Use baseAttributes() to request attributes on directly selected DDOs. Furthermore, this option does not request attributes for linked items, folder contents, or otherwise referenced components that are not retrieved as child components through the "child list" retrieve options.
DEFAULT: false
PRECEDENCE
This setting applies only to children listed through the child list request settings in the same retrieve call. If you already retrieved or listed the children and want to simply retrieve attributes for the children, submit the children directly to retrieve through multi-item retrieve (DKDatastoreICM::retrieveObjects(dkCollection,DKNVPair[])). For directly-selected DDOs (including any children directly submitted to retrieve), use the baseAttributes(boolean) setting to retrieve attributes.
This setting depends on the child list retrieve options which controls population of child collections and child component DDOs. Child attributes are populated only for children listed. If no children are listed, there are no children for which to retrieve attributes. For example, if childListOneLevel(false) and childListAllLevels(false), then there are no children for which attributes can be retrieved.
If childAttributes(true), childListOneLevel(false), and childListAllLevels(false), DKUsageError with error ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) is thrown (appended with text describing the offending options).
PERFORMANCE
Improve performance by requesting only subset of attributes that you desire. If you are only interested in some of the attributes, specify which attributes you want to be retrieved, saving time and memory by omitting those that you do not need.
See DKRetrieveOptionsICM::attributeFilters(DKProjectionListICM attributeFilters).
If there happen to be children found by the child list requests (such as childListOneLevel(true) or childListAllLevels(true), the cost to for childAttributes(true) should be negligible since no attribute data is selected in the server or returned.
DATA STRUCTURES
The same data structures apply as described in DKRetrieveOptionsICM::baseAttributes(boolean baseAttributesRequested), except that the DKDDO instances affected are those populated in child collections, as described in DKRetrieveOptionsICM::childListOneLevel(boolean childListOneLevelRequested).
See "DATA STRUCTURES" section for method DKRetrieveOptionsICM::baseAttributes(boolean baseAttributesRequested).
See "DATA STRUCTURES" section for method DKRetrieveOptionsICM::childListOneLevel(boolean childListOneLevelRequested).
BEHAVIOR NOTES
If no children are defined for the item types of DDOs selected or if children are defined but no children are found, the call returns without error. No exceptions are thrown.
The childAttributes(true) setting includes core system-defined attributes on children (those that are stored with the child component row in persistent storage and can be retrieved without measurable overhead or processing).
This option only applies to children indirectly retrieved through child list retrieve options and populated within the directly selected DDOs. This does not retrieve any attributes for DDOs directly specified in a list of DDOs to retrieve, even if one of the directly selected DDOs happens to be a child component. Use baseAttributes() to request attributes on directly selected DDOs. Furthermore, this option does not request attributes for linked items, folder contents, or otherwise referenced components that are not retrieved as child components through the "child list" retrieve options.
DEFAULT: false
PRECEDENCE
This setting applies only to children listed through the child list request settings in the same retrieve call. If you already retrieved or listed the children and want to simply retrieve attributes for the children, submit the children directly to retrieve through multi-item retrieve (DKDatastoreICM::retrieveObjects(dkCollection,DKNVPair[])). For directly-selected DDOs (including any children directly submitted to retrieve), use the baseAttributes(boolean) setting to retrieve attributes.
This setting depends on the child list retrieve options which controls population of child collections and child component DDOs. Child attributes are populated only for children listed. If no children are listed, there are no children for which to retrieve attributes. For example, if childListOneLevel(false) and childListAllLevels(false), then there are no children for which attributes can be retrieved.
If childAttributes(true), childListOneLevel(false), and childListAllLevels(false), DKUsageError with error ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) is thrown (appended with text describing the offending options).
PERFORMANCE
Improve performance by requesting only subset of attributes that you desire. If you are only interested in some of the attributes, specify which attributes you want to be retrieved, saving time and memory by omitting those that you do not need.
See DKRetrieveOptionsICM::attributeFilters(DKProjectionListICM attributeFilters).
If there happen to be children found by the child list requests (such as childListOneLevel(true) or childListAllLevels(true), the cost to for childAttributes(true) should be negligible since no attribute data is selected in the server or returned.
DATA STRUCTURES
The same data structures apply as described in DKRetrieveOptionsICM::baseAttributes(boolean baseAttributesRequested), except that the DKDDO instances affected are those populated in child collections, as described in DKRetrieveOptionsICM::childListOneLevel(boolean childListOneLevelRequested).
See "DATA STRUCTURES" section for method DKRetrieveOptionsICM::baseAttributes(boolean baseAttributesRequested).
See "DATA STRUCTURES" section for method DKRetrieveOptionsICM::childListOneLevel(boolean childListOneLevelRequested).
BEHAVIOR NOTES
If no children are defined for the item types of DDOs selected or if children are defined but no children are found, the call returns without error. No exceptions are thrown.
The childAttributes(true) setting includes core system-defined attributes on children (those that are stored with the child component row in persistent storage and can be retrieved without measurable overhead or processing).
childAttributes
- public boolean childAttributes( )
See DKRetrieveOptionsICM::childAttributes(boolean childAttributesRequested)
linksOutbound
- public void linksOutbound(boolean linksOutboundRequested)
Request the outbound links listing (table of contents (TOC)) and folder
contents listing (TOC) for directly selected component DDOs. Any
other DDO not directly listed as selected DDOs to retrieve will not have
any of its outbound links (or folder contents) listing retrieved or
refreshed. Links and folder contents *listing means that only
links and folder relationships are retrieved, not any data for the other
items linked except for their PIDs. For outbound links, the target and
descriptor DDOs of the links retrieved will not in turn have its
links, attributes, children, parts, or any other of its data retrieved.
Separate retrieve calls or settings must be used to retrieve links of
linked items or folder contents. Since links only apply to root
components, only root components will have links retrieved as a result
of this option. Additionally, only root components created with the
semantic type (or "item property type") of DKConstant.DK_CM_FOLDER (2)
can have folder contents and therefore only items found with this
semantic type should have folder contents. If this setting is used
with a child component, the link retrieve request is ignored.
This option only lists links and their target DDOs, blank DKDDOs with completed PID information that uniquely identifies an item for subsequent retrieve, update, and delete requests. In the case of outbound links, the selected component is the source DDO and the target DDO is the unknown DKDDO to be listed. The link source DDO reference points to the same instance as the selected DDO and therefore appears populated with data as the selected source DDO instance is populated.
Links optionally can include a descriptor item, a third DDO associated with this link to provide attributes and details for the link. This setting does not request the descriptor DDO on its own since there is additional overhead if descriptor items exist for a link. If you want the optional descriptor nodes populated (if they exist), use the linksDescriptors(boolean linksDescriptorsRequested) setting. By default, link descriptor DDOs will not be listed in the link and will instead appear as NULL.
Target (and descriptor) DDO attributes can be requested by adding all desired target (and descriptor) DDOs to a collection (DKSequentialCollection) and submitting the collection to multi-item retrieve (DKDatastoreICM::retrieveObjects()).
By default all links are listed regardless of type when this option is used alone. However, if you only need one link type, you can save time transferring unnecessary data across the network and unnecessary memory usage to populate links of other link types. See linksTypeFilter(String linkTypeRequested) for more information on filtering links for just one link type.
Links are used most often to start from a source and link to a target item. Typically, users start at the source and retrieve outbound links to find the targets. Therefore, this outbound links retrieve option is typically requested more often than the inbound links. This option does not retrieve inbound links, where the selected DDO happens to be the target and you want to list all the source DDOs that point to the selected DDO as targets of links. Use linksInbound() to list inbound links if necessary.
Folder relationships are based on outbound links where the folder is the source and any documents or subfolders in the folder are targets of links. A special link type is used to represent folder relationships, DKConstantICM.DK_ICM_LINKTYPENAME_DKFOLDER ("DKFolder"). For more details, refer to the SFolderICM API education sample. If you want to retrieve anything in the folder contents (such as attributes), pass the DKFolder (dkCollection interface) or create your own DKSequentialCollection (dkCollection interface) containing all folder contents you want to retrieve (perhaps from multiple folders) and send the collection to multi-item retrieve (DKDatastoreICM::retrieveObjects()).
DEFAULT: false
PRECEDENCE
The linksOutbound(boolean) has a few order of precedence and dependencies to consider. Note that linksInbound(boolean) does not share all order of precedence and dependency considerations that apply to linksOutbound(boolean).
FOR BOTH INBOUND & OUTBOUND:
If a projection list (DKProjectionListICM) is specified (through DKRetrieveOptionsICM::attributeFilters(DKProjectionListICM)) and if the projection list omits projections for directly-selected base DDOs, DDOs of that type are not retrieved, no existence check is performed, and no links are listed for DDOs of that type. (Note if children are requested, exist, and are not filtered out by omitted projections, those particular items are considered validated and links can be listed. No exception is thrown as a result of no links retrieved as a result of projection list filtering. Note that there is an exception unrelated to links list requests that can report an error if all directly-selected DDOs omitted (see behaviorIgnoreNoneFoundError(boolean)).
This setting is also filtered by specific link type requests by DKRetrieveOptionsICM::linksTypeFilter(). Also, whether or not the descriptor DDOs ("link items") associated with each link are retrieved depend on the DKRetrieveOptionsICM::linksDescriptors(boolean) setting.
FOR OUTBOUND REQUESTS ONLY:
Outbound links can populate folder contents/relationships since folder relationships are modeled as links using a special link type. However, this folder mechanism applies only to root components of items with semantic type DK_ICM_SEMANTIC_TYPE_FOLDER (2) or "item property type" DK_CM_FOLDER (2). For proper and consistent processing, Outbound link retrieval must inspect the semantic type property on all directly selected root components submitted to retrieve. Therefore, you must at a minimum retrieve the semantic type system-attribute/property along with your linksOutbound(true) request. If you desire all attributes for all directly-selected components, you could just request baseAttributes(true). However, for the fastest possible performance and minimized memory usage, you can also specify attribute filters to retrieve only the minimum number of system attributes. If you are already retrieving all base attributes (baseAttributes(true)) and have no projection list, the semantic type system-attribute/property is already included.
Otherwise, if you did not specify baseAttributes(true), you must at a minimum select baseAttributes(true) and provide attribute filters (attributeFilters(DKProjectionListICM)) with a projection list that requests system-attributes for all component type views of all directly selected base DDOs that are also root components. You cannot request individual system-attributes and must select all or none. If you do not want to identify all object types for root component DDOs directly selected, you can simply use the general projection (*) and include system-attributes for all using the DKConstantICM.DK_ICM_SYSTEM_ATTRS keyword. However, note that once you specify any projections, all omitted projections result in all DDOs of the omitted component type view to not be retrieved at all. Therefore, you must decide which other projections to specify for any other component DDOs (child or root) that are directly selected and any child component types that you might desire if you listed children. Simply using the general projection (*) to request system-attributes for all DDOs and will not omit any. However, if you had previously requested childAttributes(true), with no projection all attributes would have been returned, but with a projection now specified, only system attributes are returned unless you request all attributes for desired child component types. If you had already specified your own attribute filters (projection list), you must similarly ensure that all root components have system-attributes requested. For advanced usage of projection lists, careful consideration might be required.
If you do not request retrieval of the semantic type property for root components when requesting links, a DKUsageError exception with error ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) is thrown appended with the offending options. If you specify linksOutbound(true) and either baseAttributes(false) or specify attribute filters with any projections for root component type views that omit system attributes, this usage error is reported. Additionally, if a general projection ("*") is provided, it must not exclude system attributes when requesting linksOutbound(true) or the same exception is thrown. This ensures consistent behavior for any call with the same options and filters.
PERFORMANCE
This setting operates on a single-item basis, even when called through multi-item retrieve (or through query). When used under multi-item retrieve, other requests, such as attributes and children are optimized on a multi-item basis, however link retrieval is not. For every item directly selected, a separate call is made to the server to retrieve links. Furthermore, outbound and inbound links are retrieved separately, requiring a separate call for each. For example, if you select 100 root components for retrieval and request attributes, links outbound, and links inbound, by default approximately 3 calls will be made for attributes of all 100, 100 calls for outbound links, and another 100 calls for inbound links, totaling 203 calls to the server. Only retrieve links when necessary and only retrieve the direction needed.
Listing optional link descriptor DDOs requires additional overhead if any are set in the links retrieved (there is *no* overhead if none are set in the links actually listed). By default, this setting does not include listing descriptor DDOs. Unless you need the descriptor nodes listed, leave linksDescriptors(boolean linksDescriptorsRequested) set to false. Set linksDescriptors() to true if you do want them listed. For any item that links with descriptor items set, one more call is made for all descriptors for that item (inbound and outbound combined / optimized together this time) to complete the PID information. For each item, one additional query is performed to fully populate descriptor DDOs for inbound and outbound links combined, if any are needed. For example, consider the case of 100 select 100 root components used earlier, but this time you also request descriptor nodes, and consider a case where each item has links with descriptor nodes. 100 additional calls are made to complete descriptor item information, one call for each item (regardless of inbound or outbound directions), and totaling 303 calls.
If you only need one link type, you can save time transferring unnecessary data across the network and unnecessary memory usage populating links of types you do not need by specifying a specific link type. See linksTypeFilter(String linkTypeRequested) for more information.
If you only need to retrieve links to determine whether or not links (or folder contents) exist under an item, but the actual count does not matter, there are much faster alternatives. For example, if you simply wanted link listed just so you know whether to show a "[+]" sign in front of a folder or document, listing links is typically far more expensive if you are retrieving more than 1. If only retrieving one item, then listing links is typically faster. See online support document 1166065 a faster alternate solution using query. Although this online support document specifically covers folders, the same concept applies to links and generalized applications to links are provided through links at the bottom of this document. See online support document 1166065.
Depending on your application logic, use cases, and data model, it is probably much better to *not* retrieve links on all items and only retrieve links for a select subset of items when you know your application needs to assess or traverse the links.
Making a separate retrieve call just for links (perhaps after you already retrieve attributes and children for displaying meta-data in a search results list, there is no performance savings by combining your attribute and links retrieve requests in one single retrieve call. The same number of separate calls to the server are required. You can retrieve with an option to retrieve only links later as needed, unless your application absolutely must be able to assess and traverse links immediately without having to wait for another retrieve call to return at that point in time.
Refer to online support documents for more information and alternatives.
If you plan on retrieving multiple levels of links, you can significantly optimize performance using the linksLevelTwo() setting to reduce the number of calls (by 1/1000 in an extreme example) compared to simply calling retrieve with the links list options requested. Two levels can be obtained during the same call to the server that obtains one level of links. Similarly, if you only need the count of the number of links at the second level of links for each linked DDO, use the linksLevelTwoCount() option. Using these options incur additional network traffic and memory overhead, but are more optimal than separate retrieve calls. If you want to retrieve the whole link tree, you can utilize the two-level links list setting (but remember links & folder relationships can be cyclic). See these methods for more explanations, details, and performance considerations.
See DKRetrieveOptionsICM::linksLevelTwo(boolean linksLevelTwoRequested)
See DKRetrieveOptionsICM::linksLevelTwoCount(boolean linksLevelTwoRequested)
Note that child DDOs cannot have links. Therefore any child DDOs submitted to retrieve and links are requested, the child DDOs are not processed for links and have no performance cost for the links retrieve options on child DDOs since no check is performed. Only root components are actually evaluated for links.
DATA STRUCTURES
Links retrieved are added to their respective parent DKDDO as a DKLinksCollection (dkCollection interface), one for each link type, each collection containing DKLink objects, each of which reference a source DKDDO, target DKDDO, and descriptor DKDDO. In the case of outbound links, the source references the selected DKDDO instance and the target and descriptor DKDDOs are new instances. In the case of inbound links, the target references the selected DKDDO instance and the source and descriptor DKDDOs are new instances. Links are only "listed", creating blank DKDDOs with completed PID information so that each could be in turn retrieved, updated, or deleted.
As mentioned earlier, the optional link descriptor DDOs are not listed by default, unless linksDescriptors(boolean linksDescriptorsRequested) is set to true. If not requested, the descriptor DDOs will not be listed and will be NULL in the DKLink objects.
The link collections are added as a "data item" to their parent DKDDO object in the links namespace. You can iterate through all link collections in a DKDDO by looping through all data item IDs from '0' to "ddo.dataCount()" (across all "data item" namespaces which can include other "data items" than link collections but can be identified by a type indicator). You can also look up link collections by name (link type name) To determine if a link collection exists, first look up the "data item" ID using ddo.dataId(DKConstant.DK_CM_NAMESPACE_LINKS,<your link type name as String>). If the ID returned is '-1', no data item by that name exists. Once you have a valid ID or if you are listing through each ID, you can obtain the individual data item name ("ddo.getDataName(dataid)"), value ("ddo.getData(dataid)"), and value type ((short) ddoItem.getDataPropertyByName(dataid,DK_CM_PROPERTY_TYPE)) to help you cast or otherwise handle correctly. Link collections appear with data item type DK_CM_DATAITEM_TYPE_LINKCOLLECTION. (Details on detecting and handling all types explained in the SItemRetrievalICM sample.) Due to various retrieve options, and other circumstances, you should always lookup link collections by ID and detect if they exist or not.
Link collections for each type are created in the DKDDOs only if a link of that particular type is found for that selected DKDDO (or if an existing link collection of that type already existed prior to calling retrieve). Empty link collections are not added when no links are found for a particular link type. Use the simple utility function provided with the SLinksICM sample to easily and properly add an empty link collection for any link type. This way, there is no memory or performance cost regarding creation of empty data structures that are not a defined relationship specific to the particular DDDO.
For existing DDKDDOs that already have existing link collections, their existing link collections are cleared of existing inbound or outbound links if inbound or outbound links a requested again (considered a refresh). If your existing DDO has inbound and outbound links already listed and you request a refresh by re-retrieving with the linksOutbound(TRUE) option, the existing outbound links are cleared and repopulated with current links. The existing inbound links in this case are left as-is. Also note that DKLinkCollections, existing DKLink objects, and referenced source, target, and descriptor DKDDOs are dropped from the parent's DKDDO structure (and memory deleted in C++), replacing them with new DKLinkCollection and DKLink instances along with new blank source, target, and descriptor DKDDO instances. However, if you are requesting only a specific link type through the linksTypeFilter() option, existing link collections remain and are not cleared, except for the one link type that you requested to refresh. Retrieve modifies only the link collections for link types you request.
Also, for any DKDDO that complete link retrieval, a special DKDDO "property" named DKConstantICM.DK_ICM_PROPERTY_IS_LINKED ("islinked") (DKConstantICM.h in C++) is added and set with value Boolean.TRUE or Boolean.FALSE (TRUE or FALSE in C++) to indicate whether links exist in the DDO. For any DKDDO that contains at least one link upon completion of link retrieval, meaning at least one link (inbound or outbound) is successfully retrieved (or remains in the DDO if not refreshing all), the IS_LINKED property is added or updated with the value Boolean.TRUE (TRUE in C++) to indicate that DKLink objects exist in memory for this DKDDO instance. If no links are found (limited to any link type name restrictions requested through DKRetrieveOptionsICM::linkTypeName(String)) and if none remain from prior to retrieve (if not refreshing all), this property is set with value Boolean.FALSE. If no links are requested (inbound or outbound), no such property is added or modified by retrieve (any existing property by this name is not updated (or removed). Note that if the scope of retrieval is limited by direction or link type, existing links that remain in the DDO for directions or types not refreshed are not-revalidated, but do quality as links in memory when updating the IS_LINKED property. However, note that Boolean.FALSE (FALSE in C++) does not exactly mean that the persistent item is not linked. It just means no links (of the requested link types (perhaps limited to a specific link type by linkTypeName(String)) and retrieved only for the direction requested (inbound/outbound) can be seen by the current user and connection. Links to inaccessible items (filtered by access control) and links of other link types that are not requested (if restricted by linkTypeName(String)) are not listed. No links listed result in a Boolean.FALSE value indicating that no DKLink objects exist for this DKDDO in memory. Therefore, if you already had inbound links populated in the DKDDO and you requested outbound links only this time, the ...IS_LINKED will be set to Boolean.TRUE because your existing inbound links remain after your outbound link request (see BEHAVIOR NOTES section for more details on clearing existing link collection). The ...IS_LINKED property applies only to link collections and DKLink objects and does not apply to the special folder relationship link type and the associated folder collection or folder sources collection.
For examples and details accessing links, refer to the SLinksICM API education sample.
Folder relationships are based on links (the folder is the source and the documents or subfolders in the folder are the targets of links from the source folder). However, they do not use the same data structures in memory. Folders use a simplified interface that enables the folders to simply contain a collection of their contents, instead of DKLinkCollections. Targets of folder links (i.e. the folder contents) appear as a DKDDO "data item" in the attribute namespace (DKConstant.DK_CM_NAMESPACE_ATTR) named DKConstant.DK_CM_DKFOLDER ("DKFolder"). (ddo.dataId(DKConstant.DK_CM_NAMESPACE_ATTR,DKConstant.DK_CM_DKFOLDER)) This "data item" has data item type DK_CM_DATAITEM_TYPE_COLLECTION_DDO along with child collections, except that child collections appear in the CHILD namespace. The value of this data item is a DKFolder (dkCollection interface) that contains blank DKDDOs with completed PID information. The DKFolder is considered a simplified interface of an outbound link collection. There are no descriptor DDOs for folder links. Also remember that this folder mechanism only exists for root components created with the semantic type DKContantICM.DK_ICM_SEMANTIC_TYPE_FOLDER (2) (or "item property type" DKConstant.DK_CM_FOLDER (2)). Furthermore, a new the DKConstant.DK_CM_DKFOLDER attribute and empty DKFolder collection are added only when linksOutbound(true) requested and the linksTypeFiilter() option does not exclude the folder relationship link type (DKConstantICM.DK_ICM_LINKTYPENAME_DKFOLDER). Similarly, existing DKDDOs with existing DKFolder collections are cleared, but only when linksOutbound(true) requested and the linksTypeFiilter() option does not exclude the folder relationship link type.
With the DKFolder interface that appears on the folder for outbound links, similarly, inbound folder relationship links to not appear inside DKLinkCollections. When a document or subfolder retrieves inbound links, it discovers source DDOs for the folders that contain the document or subfolder as a target of an outbound folder relationship link. However, since folder relationships are not stored in DKLinkCollections, the source folder DKDDOs when inbound folder relationship links are found, the source DDO information must be discarded or stored in an alternate location. By default the source folder DKDDOs are not materialized. If you want the folder source DKDDOs, see DKRetrieveOptionsICM::linksInboundFolderSources(boolean folderSourceDDOsRequested).
For more details on accessing folders, refer to the SFolderICM API education sample.
BEHAVIOR NOTES
(C++/Java Difference) Consider when the same item is associated with more than one link relationship (among source, target, link item descriptor, folder content, source folder, etc.). When you retrieve link relationships for any individual base DDO, the links retrieved could have more than one reference to the same item among various link relationship references retrieved. For any of the references if the item is the same as the individual base DDO currently being retrieved, the base DDO reference is reused. However, for all other references that are not the same as the item being retrieved, the behavior when the same item appears in more than one link relationship varies between Java and C++. In Java, the one DDO instance is created and is reused for all occurrences and populated into the link relationship or collection within the scope of an individual base DDO. However in C++, DDO instances are not reused and instead C++ creates separate DDOs for each occurrence. Separate instances are used in C++ since sharing references can lead to invalid pointers should you happen to remove the actual owner. Furthermore, since linked items are retrieved as blank DDOs with completed PIDs, applications typically prefer to collect all non-retrieved DDOs into a single dkCollection (e.g. DKSequentialCollection) and perform an optimized multi-item retrieve for attributes. However, since C++ creates separate instances of the same DDO (if the same item appears in multiple places), you must handle the case of duplicate DDOs not retrieved since multi-item retrieve retrieves only the first occurrence and marks duplicates as failed. You might find that duplicate references are still not retrieved in the original link relationship references. Additionally, note that in Java the DDO instances are only reused within the scope under each individual base DDO and are not currently reused between multiple base DDOs retrieved. Therefore, in the case of multi-item retrieve, Java too must be handled carefully for duplicate DDOs if passing all DDOs associated with links to one optimized multi-item retrieve request for attributes.
When you retrieve only one direction of links, inbound or outbound (but not both), the existing link collections are cleared of existing links only in the requested direction. Any existing links in the direction that is not requested remain (and the DKConstantICM.DK_ICM_PROPERTY_IS_LINKED property is set to Boolean.TRUE). The DKLinkCollections can contain a mix if your old links from the direction (inbound or outbound) that you did not request and new links for the direction that you did request. However, links in within the same direction are never mixed and area easily separated using the direction-specific iterators.
With this outbound links (and folder contents) listing request, provided folder links are not excluded through the linksTypeFilter() setting, all folders (root components with semantic type DKContantICM.DK_ICM_SEMANTIC_TYPE_FOLDER / DKConstant.DK_CM_FOLDER (2)) are populated with at least an empty (cardinality '0') DKFolder collection (location and details of collection described in "DATA STRUCTURES" section), accurately reflecting the current folder content count that are accessible to the current user.
If outbound links are not requested (linksOutbound(false)), or if excluded when a specific link type name is requested that does not include folder relationships (not "*" or DKConstantICM.DK_ICM_LINKTYPENAME_DKFOLDER ("DKFolder"))), no DKFolder collection is added by the retrieve request and any existing collection is not refreshed or modified in any way. If no such DKFolder collection existed in the selected DDOs prior to the retrieve call, no such collection or DKDDO "data item" appears in the DKDDO after the call.
When using the newer DKRetrieveOptionsICM with either linksInbound(true) or linksOutbound(true), the DKDDO "property" DKConstantICM.DK_ICM_PROPERTY_IS_LINKED ("islinked") is always set to Boolean.TRUE if a non-zero links count is detected or Boolean.FALSE if no links are currently found, overriding any existing value if the property had existed in the DKDDO prior to the retrieve call (except of course if you requested only one direction and links still remain in the DKDDO for the other direction). However, under the older bitwise 'int' options, if you used DKCosntant.DK_CM_CONTENT_LINKS_INBOUND or DK_CM_CONTENT_LINKS_OUTBOUND, the DKConstantICM.DK_ICM_PROPERTY_IS_LINKED DKDDO property was never be added or updated to Boolean.FALSE if no links were found. If no links were found, the DKConstantICM.DK_ICM_PROPERTY_IS_LINKED property was not added if it did not exist and if it already existed, the value was not updated to Boolean.FALSE if it was previously set to Boolean.TRUE.
Remember that DKDDO property DKConstantICM.DK_ICM_PROPERTY_IS_LINKED with value Boolean.FALSE does not necessarily mean the persistent item is not linked. It just means that no links were found in for the current DKDDO instance given the access of the current user and limited to the link type name restrictions requested through linksTypeFilter(String linkTypeName)(String) and for the directions requested (inbound or outbound).
If you already had inbound links populated in the DKDDO and you requested outbound links only this time, DKConstantICM.DK_ICM_PROPERTY_IS_LINKED is set to Boolean.TRUE because your existing inbound link DKLink objects remain after your outbound link request, even if there are no outbound links found. Remember the ...IS_LINKED property needs to reflect that DKLink objects exist in the DKDDO, even if none are found in the specific direction for which you requested a refresh.
If DKConstantICM.DK_ICM_PROPERTY_IS_LINKED were set to Boolean.FALSE (or if the property were entirely omitted), any changes you make to the link collections are ignored. Link information is only processed in add or update operations if the ...IS_LINKED property exists and is set to Boolean.TRUE. If link retrieve sets this property to Boolean.FALSE, even if empty DKLinkCollection instances exist in your DKDDO, you must set the DKConstantICM.DK_ICM_PROPERTY_IS_LINKED back to Boolean.TRUE if you add any DKLink objects if you want them persisted. If not, add or update will ignore them (no exception thrown).
This option only lists links and their target DDOs, blank DKDDOs with completed PID information that uniquely identifies an item for subsequent retrieve, update, and delete requests. In the case of outbound links, the selected component is the source DDO and the target DDO is the unknown DKDDO to be listed. The link source DDO reference points to the same instance as the selected DDO and therefore appears populated with data as the selected source DDO instance is populated.
Links optionally can include a descriptor item, a third DDO associated with this link to provide attributes and details for the link. This setting does not request the descriptor DDO on its own since there is additional overhead if descriptor items exist for a link. If you want the optional descriptor nodes populated (if they exist), use the linksDescriptors(boolean linksDescriptorsRequested) setting. By default, link descriptor DDOs will not be listed in the link and will instead appear as NULL.
Target (and descriptor) DDO attributes can be requested by adding all desired target (and descriptor) DDOs to a collection (DKSequentialCollection) and submitting the collection to multi-item retrieve (DKDatastoreICM::retrieveObjects()).
By default all links are listed regardless of type when this option is used alone. However, if you only need one link type, you can save time transferring unnecessary data across the network and unnecessary memory usage to populate links of other link types. See linksTypeFilter(String linkTypeRequested) for more information on filtering links for just one link type.
Links are used most often to start from a source and link to a target item. Typically, users start at the source and retrieve outbound links to find the targets. Therefore, this outbound links retrieve option is typically requested more often than the inbound links. This option does not retrieve inbound links, where the selected DDO happens to be the target and you want to list all the source DDOs that point to the selected DDO as targets of links. Use linksInbound() to list inbound links if necessary.
Folder relationships are based on outbound links where the folder is the source and any documents or subfolders in the folder are targets of links. A special link type is used to represent folder relationships, DKConstantICM.DK_ICM_LINKTYPENAME_DKFOLDER ("DKFolder"). For more details, refer to the SFolderICM API education sample. If you want to retrieve anything in the folder contents (such as attributes), pass the DKFolder (dkCollection interface) or create your own DKSequentialCollection (dkCollection interface) containing all folder contents you want to retrieve (perhaps from multiple folders) and send the collection to multi-item retrieve (DKDatastoreICM::retrieveObjects()).
DEFAULT: false
PRECEDENCE
The linksOutbound(boolean) has a few order of precedence and dependencies to consider. Note that linksInbound(boolean) does not share all order of precedence and dependency considerations that apply to linksOutbound(boolean).
FOR BOTH INBOUND & OUTBOUND:
If a projection list (DKProjectionListICM) is specified (through DKRetrieveOptionsICM::attributeFilters(DKProjectionListICM)) and if the projection list omits projections for directly-selected base DDOs, DDOs of that type are not retrieved, no existence check is performed, and no links are listed for DDOs of that type. (Note if children are requested, exist, and are not filtered out by omitted projections, those particular items are considered validated and links can be listed. No exception is thrown as a result of no links retrieved as a result of projection list filtering. Note that there is an exception unrelated to links list requests that can report an error if all directly-selected DDOs omitted (see behaviorIgnoreNoneFoundError(boolean)).
This setting is also filtered by specific link type requests by DKRetrieveOptionsICM::linksTypeFilter(). Also, whether or not the descriptor DDOs ("link items") associated with each link are retrieved depend on the DKRetrieveOptionsICM::linksDescriptors(boolean) setting.
FOR OUTBOUND REQUESTS ONLY:
Outbound links can populate folder contents/relationships since folder relationships are modeled as links using a special link type. However, this folder mechanism applies only to root components of items with semantic type DK_ICM_SEMANTIC_TYPE_FOLDER (2) or "item property type" DK_CM_FOLDER (2). For proper and consistent processing, Outbound link retrieval must inspect the semantic type property on all directly selected root components submitted to retrieve. Therefore, you must at a minimum retrieve the semantic type system-attribute/property along with your linksOutbound(true) request. If you desire all attributes for all directly-selected components, you could just request baseAttributes(true). However, for the fastest possible performance and minimized memory usage, you can also specify attribute filters to retrieve only the minimum number of system attributes. If you are already retrieving all base attributes (baseAttributes(true)) and have no projection list, the semantic type system-attribute/property is already included.
Otherwise, if you did not specify baseAttributes(true), you must at a minimum select baseAttributes(true) and provide attribute filters (attributeFilters(DKProjectionListICM)) with a projection list that requests system-attributes for all component type views of all directly selected base DDOs that are also root components. You cannot request individual system-attributes and must select all or none. If you do not want to identify all object types for root component DDOs directly selected, you can simply use the general projection (*) and include system-attributes for all using the DKConstantICM.DK_ICM_SYSTEM_ATTRS keyword. However, note that once you specify any projections, all omitted projections result in all DDOs of the omitted component type view to not be retrieved at all. Therefore, you must decide which other projections to specify for any other component DDOs (child or root) that are directly selected and any child component types that you might desire if you listed children. Simply using the general projection (*) to request system-attributes for all DDOs and will not omit any. However, if you had previously requested childAttributes(true), with no projection all attributes would have been returned, but with a projection now specified, only system attributes are returned unless you request all attributes for desired child component types. If you had already specified your own attribute filters (projection list), you must similarly ensure that all root components have system-attributes requested. For advanced usage of projection lists, careful consideration might be required.
If you do not request retrieval of the semantic type property for root components when requesting links, a DKUsageError exception with error ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) is thrown appended with the offending options. If you specify linksOutbound(true) and either baseAttributes(false) or specify attribute filters with any projections for root component type views that omit system attributes, this usage error is reported. Additionally, if a general projection ("*") is provided, it must not exclude system attributes when requesting linksOutbound(true) or the same exception is thrown. This ensures consistent behavior for any call with the same options and filters.
PERFORMANCE
This setting operates on a single-item basis, even when called through multi-item retrieve (or through query). When used under multi-item retrieve, other requests, such as attributes and children are optimized on a multi-item basis, however link retrieval is not. For every item directly selected, a separate call is made to the server to retrieve links. Furthermore, outbound and inbound links are retrieved separately, requiring a separate call for each. For example, if you select 100 root components for retrieval and request attributes, links outbound, and links inbound, by default approximately 3 calls will be made for attributes of all 100, 100 calls for outbound links, and another 100 calls for inbound links, totaling 203 calls to the server. Only retrieve links when necessary and only retrieve the direction needed.
Listing optional link descriptor DDOs requires additional overhead if any are set in the links retrieved (there is *no* overhead if none are set in the links actually listed). By default, this setting does not include listing descriptor DDOs. Unless you need the descriptor nodes listed, leave linksDescriptors(boolean linksDescriptorsRequested) set to false. Set linksDescriptors() to true if you do want them listed. For any item that links with descriptor items set, one more call is made for all descriptors for that item (inbound and outbound combined / optimized together this time) to complete the PID information. For each item, one additional query is performed to fully populate descriptor DDOs for inbound and outbound links combined, if any are needed. For example, consider the case of 100 select 100 root components used earlier, but this time you also request descriptor nodes, and consider a case where each item has links with descriptor nodes. 100 additional calls are made to complete descriptor item information, one call for each item (regardless of inbound or outbound directions), and totaling 303 calls.
If you only need one link type, you can save time transferring unnecessary data across the network and unnecessary memory usage populating links of types you do not need by specifying a specific link type. See linksTypeFilter(String linkTypeRequested) for more information.
If you only need to retrieve links to determine whether or not links (or folder contents) exist under an item, but the actual count does not matter, there are much faster alternatives. For example, if you simply wanted link listed just so you know whether to show a "[+]" sign in front of a folder or document, listing links is typically far more expensive if you are retrieving more than 1. If only retrieving one item, then listing links is typically faster. See online support document 1166065 a faster alternate solution using query. Although this online support document specifically covers folders, the same concept applies to links and generalized applications to links are provided through links at the bottom of this document. See online support document 1166065.
Depending on your application logic, use cases, and data model, it is probably much better to *not* retrieve links on all items and only retrieve links for a select subset of items when you know your application needs to assess or traverse the links.
Making a separate retrieve call just for links (perhaps after you already retrieve attributes and children for displaying meta-data in a search results list, there is no performance savings by combining your attribute and links retrieve requests in one single retrieve call. The same number of separate calls to the server are required. You can retrieve with an option to retrieve only links later as needed, unless your application absolutely must be able to assess and traverse links immediately without having to wait for another retrieve call to return at that point in time.
Refer to online support documents for more information and alternatives.
If you plan on retrieving multiple levels of links, you can significantly optimize performance using the linksLevelTwo() setting to reduce the number of calls (by 1/1000 in an extreme example) compared to simply calling retrieve with the links list options requested. Two levels can be obtained during the same call to the server that obtains one level of links. Similarly, if you only need the count of the number of links at the second level of links for each linked DDO, use the linksLevelTwoCount() option. Using these options incur additional network traffic and memory overhead, but are more optimal than separate retrieve calls. If you want to retrieve the whole link tree, you can utilize the two-level links list setting (but remember links & folder relationships can be cyclic). See these methods for more explanations, details, and performance considerations.
See DKRetrieveOptionsICM::linksLevelTwo(boolean linksLevelTwoRequested)
See DKRetrieveOptionsICM::linksLevelTwoCount(boolean linksLevelTwoRequested)
Note that child DDOs cannot have links. Therefore any child DDOs submitted to retrieve and links are requested, the child DDOs are not processed for links and have no performance cost for the links retrieve options on child DDOs since no check is performed. Only root components are actually evaluated for links.
DATA STRUCTURES
Links retrieved are added to their respective parent DKDDO as a DKLinksCollection (dkCollection interface), one for each link type, each collection containing DKLink objects, each of which reference a source DKDDO, target DKDDO, and descriptor DKDDO. In the case of outbound links, the source references the selected DKDDO instance and the target and descriptor DKDDOs are new instances. In the case of inbound links, the target references the selected DKDDO instance and the source and descriptor DKDDOs are new instances. Links are only "listed", creating blank DKDDOs with completed PID information so that each could be in turn retrieved, updated, or deleted.
As mentioned earlier, the optional link descriptor DDOs are not listed by default, unless linksDescriptors(boolean linksDescriptorsRequested) is set to true. If not requested, the descriptor DDOs will not be listed and will be NULL in the DKLink objects.
The link collections are added as a "data item" to their parent DKDDO object in the links namespace. You can iterate through all link collections in a DKDDO by looping through all data item IDs from '0' to "ddo.dataCount()" (across all "data item" namespaces which can include other "data items" than link collections but can be identified by a type indicator). You can also look up link collections by name (link type name) To determine if a link collection exists, first look up the "data item" ID using ddo.dataId(DKConstant.DK_CM_NAMESPACE_LINKS,<your link type name as String>). If the ID returned is '-1', no data item by that name exists. Once you have a valid ID or if you are listing through each ID, you can obtain the individual data item name ("ddo.getDataName(dataid)"), value ("ddo.getData(dataid)"), and value type ((short) ddoItem.getDataPropertyByName(dataid,DK_CM_PROPERTY_TYPE)) to help you cast or otherwise handle correctly. Link collections appear with data item type DK_CM_DATAITEM_TYPE_LINKCOLLECTION. (Details on detecting and handling all types explained in the SItemRetrievalICM sample.) Due to various retrieve options, and other circumstances, you should always lookup link collections by ID and detect if they exist or not.
Link collections for each type are created in the DKDDOs only if a link of that particular type is found for that selected DKDDO (or if an existing link collection of that type already existed prior to calling retrieve). Empty link collections are not added when no links are found for a particular link type. Use the simple utility function provided with the SLinksICM sample to easily and properly add an empty link collection for any link type. This way, there is no memory or performance cost regarding creation of empty data structures that are not a defined relationship specific to the particular DDDO.
For existing DDKDDOs that already have existing link collections, their existing link collections are cleared of existing inbound or outbound links if inbound or outbound links a requested again (considered a refresh). If your existing DDO has inbound and outbound links already listed and you request a refresh by re-retrieving with the linksOutbound(TRUE) option, the existing outbound links are cleared and repopulated with current links. The existing inbound links in this case are left as-is. Also note that DKLinkCollections, existing DKLink objects, and referenced source, target, and descriptor DKDDOs are dropped from the parent's DKDDO structure (and memory deleted in C++), replacing them with new DKLinkCollection and DKLink instances along with new blank source, target, and descriptor DKDDO instances. However, if you are requesting only a specific link type through the linksTypeFilter() option, existing link collections remain and are not cleared, except for the one link type that you requested to refresh. Retrieve modifies only the link collections for link types you request.
Also, for any DKDDO that complete link retrieval, a special DKDDO "property" named DKConstantICM.DK_ICM_PROPERTY_IS_LINKED ("islinked") (DKConstantICM.h in C++) is added and set with value Boolean.TRUE or Boolean.FALSE (TRUE or FALSE in C++) to indicate whether links exist in the DDO. For any DKDDO that contains at least one link upon completion of link retrieval, meaning at least one link (inbound or outbound) is successfully retrieved (or remains in the DDO if not refreshing all), the IS_LINKED property is added or updated with the value Boolean.TRUE (TRUE in C++) to indicate that DKLink objects exist in memory for this DKDDO instance. If no links are found (limited to any link type name restrictions requested through DKRetrieveOptionsICM::linkTypeName(String)) and if none remain from prior to retrieve (if not refreshing all), this property is set with value Boolean.FALSE. If no links are requested (inbound or outbound), no such property is added or modified by retrieve (any existing property by this name is not updated (or removed). Note that if the scope of retrieval is limited by direction or link type, existing links that remain in the DDO for directions or types not refreshed are not-revalidated, but do quality as links in memory when updating the IS_LINKED property. However, note that Boolean.FALSE (FALSE in C++) does not exactly mean that the persistent item is not linked. It just means no links (of the requested link types (perhaps limited to a specific link type by linkTypeName(String)) and retrieved only for the direction requested (inbound/outbound) can be seen by the current user and connection. Links to inaccessible items (filtered by access control) and links of other link types that are not requested (if restricted by linkTypeName(String)) are not listed. No links listed result in a Boolean.FALSE value indicating that no DKLink objects exist for this DKDDO in memory. Therefore, if you already had inbound links populated in the DKDDO and you requested outbound links only this time, the ...IS_LINKED will be set to Boolean.TRUE because your existing inbound links remain after your outbound link request (see BEHAVIOR NOTES section for more details on clearing existing link collection). The ...IS_LINKED property applies only to link collections and DKLink objects and does not apply to the special folder relationship link type and the associated folder collection or folder sources collection.
For examples and details accessing links, refer to the SLinksICM API education sample.
Folder relationships are based on links (the folder is the source and the documents or subfolders in the folder are the targets of links from the source folder). However, they do not use the same data structures in memory. Folders use a simplified interface that enables the folders to simply contain a collection of their contents, instead of DKLinkCollections. Targets of folder links (i.e. the folder contents) appear as a DKDDO "data item" in the attribute namespace (DKConstant.DK_CM_NAMESPACE_ATTR) named DKConstant.DK_CM_DKFOLDER ("DKFolder"). (ddo.dataId(DKConstant.DK_CM_NAMESPACE_ATTR,DKConstant.DK_CM_DKFOLDER)) This "data item" has data item type DK_CM_DATAITEM_TYPE_COLLECTION_DDO along with child collections, except that child collections appear in the CHILD namespace. The value of this data item is a DKFolder (dkCollection interface) that contains blank DKDDOs with completed PID information. The DKFolder is considered a simplified interface of an outbound link collection. There are no descriptor DDOs for folder links. Also remember that this folder mechanism only exists for root components created with the semantic type DKContantICM.DK_ICM_SEMANTIC_TYPE_FOLDER (2) (or "item property type" DKConstant.DK_CM_FOLDER (2)). Furthermore, a new the DKConstant.DK_CM_DKFOLDER attribute and empty DKFolder collection are added only when linksOutbound(true) requested and the linksTypeFiilter() option does not exclude the folder relationship link type (DKConstantICM.DK_ICM_LINKTYPENAME_DKFOLDER). Similarly, existing DKDDOs with existing DKFolder collections are cleared, but only when linksOutbound(true) requested and the linksTypeFiilter() option does not exclude the folder relationship link type.
With the DKFolder interface that appears on the folder for outbound links, similarly, inbound folder relationship links to not appear inside DKLinkCollections. When a document or subfolder retrieves inbound links, it discovers source DDOs for the folders that contain the document or subfolder as a target of an outbound folder relationship link. However, since folder relationships are not stored in DKLinkCollections, the source folder DKDDOs when inbound folder relationship links are found, the source DDO information must be discarded or stored in an alternate location. By default the source folder DKDDOs are not materialized. If you want the folder source DKDDOs, see DKRetrieveOptionsICM::linksInboundFolderSources(boolean folderSourceDDOsRequested).
For more details on accessing folders, refer to the SFolderICM API education sample.
BEHAVIOR NOTES
(C++/Java Difference) Consider when the same item is associated with more than one link relationship (among source, target, link item descriptor, folder content, source folder, etc.). When you retrieve link relationships for any individual base DDO, the links retrieved could have more than one reference to the same item among various link relationship references retrieved. For any of the references if the item is the same as the individual base DDO currently being retrieved, the base DDO reference is reused. However, for all other references that are not the same as the item being retrieved, the behavior when the same item appears in more than one link relationship varies between Java and C++. In Java, the one DDO instance is created and is reused for all occurrences and populated into the link relationship or collection within the scope of an individual base DDO. However in C++, DDO instances are not reused and instead C++ creates separate DDOs for each occurrence. Separate instances are used in C++ since sharing references can lead to invalid pointers should you happen to remove the actual owner. Furthermore, since linked items are retrieved as blank DDOs with completed PIDs, applications typically prefer to collect all non-retrieved DDOs into a single dkCollection (e.g. DKSequentialCollection) and perform an optimized multi-item retrieve for attributes. However, since C++ creates separate instances of the same DDO (if the same item appears in multiple places), you must handle the case of duplicate DDOs not retrieved since multi-item retrieve retrieves only the first occurrence and marks duplicates as failed. You might find that duplicate references are still not retrieved in the original link relationship references. Additionally, note that in Java the DDO instances are only reused within the scope under each individual base DDO and are not currently reused between multiple base DDOs retrieved. Therefore, in the case of multi-item retrieve, Java too must be handled carefully for duplicate DDOs if passing all DDOs associated with links to one optimized multi-item retrieve request for attributes.
When you retrieve only one direction of links, inbound or outbound (but not both), the existing link collections are cleared of existing links only in the requested direction. Any existing links in the direction that is not requested remain (and the DKConstantICM.DK_ICM_PROPERTY_IS_LINKED property is set to Boolean.TRUE). The DKLinkCollections can contain a mix if your old links from the direction (inbound or outbound) that you did not request and new links for the direction that you did request. However, links in within the same direction are never mixed and area easily separated using the direction-specific iterators.
With this outbound links (and folder contents) listing request, provided folder links are not excluded through the linksTypeFilter() setting, all folders (root components with semantic type DKContantICM.DK_ICM_SEMANTIC_TYPE_FOLDER / DKConstant.DK_CM_FOLDER (2)) are populated with at least an empty (cardinality '0') DKFolder collection (location and details of collection described in "DATA STRUCTURES" section), accurately reflecting the current folder content count that are accessible to the current user.
If outbound links are not requested (linksOutbound(false)), or if excluded when a specific link type name is requested that does not include folder relationships (not "*" or DKConstantICM.DK_ICM_LINKTYPENAME_DKFOLDER ("DKFolder"))), no DKFolder collection is added by the retrieve request and any existing collection is not refreshed or modified in any way. If no such DKFolder collection existed in the selected DDOs prior to the retrieve call, no such collection or DKDDO "data item" appears in the DKDDO after the call.
When using the newer DKRetrieveOptionsICM with either linksInbound(true) or linksOutbound(true), the DKDDO "property" DKConstantICM.DK_ICM_PROPERTY_IS_LINKED ("islinked") is always set to Boolean.TRUE if a non-zero links count is detected or Boolean.FALSE if no links are currently found, overriding any existing value if the property had existed in the DKDDO prior to the retrieve call (except of course if you requested only one direction and links still remain in the DKDDO for the other direction). However, under the older bitwise 'int' options, if you used DKCosntant.DK_CM_CONTENT_LINKS_INBOUND or DK_CM_CONTENT_LINKS_OUTBOUND, the DKConstantICM.DK_ICM_PROPERTY_IS_LINKED DKDDO property was never be added or updated to Boolean.FALSE if no links were found. If no links were found, the DKConstantICM.DK_ICM_PROPERTY_IS_LINKED property was not added if it did not exist and if it already existed, the value was not updated to Boolean.FALSE if it was previously set to Boolean.TRUE.
Remember that DKDDO property DKConstantICM.DK_ICM_PROPERTY_IS_LINKED with value Boolean.FALSE does not necessarily mean the persistent item is not linked. It just means that no links were found in for the current DKDDO instance given the access of the current user and limited to the link type name restrictions requested through linksTypeFilter(String linkTypeName)(String) and for the directions requested (inbound or outbound).
If you already had inbound links populated in the DKDDO and you requested outbound links only this time, DKConstantICM.DK_ICM_PROPERTY_IS_LINKED is set to Boolean.TRUE because your existing inbound link DKLink objects remain after your outbound link request, even if there are no outbound links found. Remember the ...IS_LINKED property needs to reflect that DKLink objects exist in the DKDDO, even if none are found in the specific direction for which you requested a refresh.
If DKConstantICM.DK_ICM_PROPERTY_IS_LINKED were set to Boolean.FALSE (or if the property were entirely omitted), any changes you make to the link collections are ignored. Link information is only processed in add or update operations if the ...IS_LINKED property exists and is set to Boolean.TRUE. If link retrieve sets this property to Boolean.FALSE, even if empty DKLinkCollection instances exist in your DKDDO, you must set the DKConstantICM.DK_ICM_PROPERTY_IS_LINKED back to Boolean.TRUE if you add any DKLink objects if you want them persisted. If not, add or update will ignore them (no exception thrown).
Parameters:
linksOutboundRequested
- If 'true', you request outbound links listed for any directly selected DDO. If 'false', you do not request such links listed.
linksOutbound
- public boolean linksOutbound()
See DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested)
linksInbound
- public void linksInbound(boolean linksInboundRequested)
Request the inbound links listed (table of contents (TOC)) for directly selected
component DDOs.
The details and explanations of inbound links are nearly identical to outbound links, except that the directly selected component DDOs are the targets of links and from that point of reference, this option lists inbound links coming from other source item DDOs that link to each respective target DDO.
See DKRetrieveOptionsICM::linksInbound(boolean linksOutboundRequested) for detailed information, except understand that this time you are listing inbound links coming from an unknown source DDO pointing to the current selected DDO as the target of the link.
Important inbound folder relationship links information is detailed in linksOutbound(boolean linksOutboundRequested).
See DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested)
DEFAULT: false
PRECEDENCE
The linksInbound(boolean) request shares many similarities with the linksOutbound(boolean) request, except that this setting applies to the inbound direction. First see the "PRECEDENCE" section of linksOutbound(boolean) for common order or precedence and dependency considerations shared by both.
See "PREDENCE" section of DKRetrieveOptionsICM::linksOutbound(boolean)
Inbound links do not have any requirement for system attributes that are required by outbound link retrieval.
BEHAVIOR NOTES
Under the older bitwise 'int' inbound links option
The details and explanations of inbound links are nearly identical to outbound links, except that the directly selected component DDOs are the targets of links and from that point of reference, this option lists inbound links coming from other source item DDOs that link to each respective target DDO.
See DKRetrieveOptionsICM::linksInbound(boolean linksOutboundRequested) for detailed information, except understand that this time you are listing inbound links coming from an unknown source DDO pointing to the current selected DDO as the target of the link.
Important inbound folder relationship links information is detailed in linksOutbound(boolean linksOutboundRequested).
See DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested)
DEFAULT: false
PRECEDENCE
The linksInbound(boolean) request shares many similarities with the linksOutbound(boolean) request, except that this setting applies to the inbound direction. First see the "PRECEDENCE" section of linksOutbound(boolean) for common order or precedence and dependency considerations shared by both.
See "PREDENCE" section of DKRetrieveOptionsICM::linksOutbound(boolean)
Inbound links do not have any requirement for system attributes that are required by outbound link retrieval.
BEHAVIOR NOTES
Under the older bitwise 'int' inbound links option
DKConstant.DK_CM_CONTENT_LINKS_INBOUND
,
an empty (cardinality '0') DKFolder collection (for folder
contents/relationships listing) (DKDDO "data item"
named DKConstant.DK_CM_DKFOLDER) was added even if outbound
links were not requested (no DKConstant.DK_CM_CONTENT_LINKS_OUTOBUND
or DKConstant.DK_CM_CONTENT_ITEMTREE). This might appear
as though the folder contents were listed but happen to have
zero (accessible) folder contents/relationships. When using
the newer DKRetrieveOptionsICM interface to pass options,
the DKFolder collection is only added by retrieve
when linksOutbound(true), since this collection is
only populated by outbound links. Any other DKRetrieveOptionsICM
setting, including linksInbound(true), does not result in a
DKFolder collection added (not even an empty collection) by the
retrieve request. Any existing collection is not refreshed or
modified in any way. If no such DKFolder collection existed in the
selected DDOs prior to the retrieve call, no such collection or DKDDO
"data item" appears in the DKDDO after the call.
Parameters:
linksInboundRequested
- If 'true', you request inbound links listed for any directly selected DDO. If 'false', you do not request such links listed.
linksInbound
- public boolean linksInbound()
See DKRetrieveOptionsICM::linksInbound(boolean linksOutboundRequested)
linksInboundFolderSources
- public void linksInboundFolderSources( boolean folderSourceDDOsRequested)
If inbound links listed, instruct retrieve to hold onto folder source
information and report it through a special construct. As explained
in detail in the DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested)
method, folder relationships are based on links (the folder is the source and the
documents or subfolders in the folder are the targets of links from the source
folder). However, they do not use the same data structures in DKDDOs as links.
Details concerning this topic and why this option is provided are explained in the "DATA STRUCTURES" section of DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested). Review links and folder relationship data structure information.
By default, inbound folder links are ignored when inbound links are retrieved. Because folder contents are stored in a DKFolder collection (containing DKDDO objects), not DKLinkCollection objects (containing DKLink objects), only targets of outbound links are stored in the DKFolder collection because only targets of the folder relationships are the folder contents. The inbound folder relationships (links) do not fit in the DKFolder collection and are never stored in DKLinkCollections because folder relationships are not to be treated as DKLink objects by the user of the API. Only updates to the DKFolder collection are honored as modifications to folder relationships.
You can instruct the retrieve operation to hang on to folder source information when it finds an inbound folder link. There is no additional server communication needed since the information is already available during the inbound link retrieve call. The folder source information is stored in a specific property as outlined below.
DEFAULT: false
PRECEDENCE
This setting only applies if inbound links are requested. Folder source DDOs can only be recorded if inbound links are listed. Additionally, if folder links are filtered out through the linksTypeFilter() setting, there are no inbound folder sources that can be recorded.
If linksInbound(false) and linksInboundFolderSources(true), DKUsageError with error ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) is thrown (appended with text describing the offending options).
If linksTypeFilter(NOT "*" or DKConstantICM.DK_ICM_LINKTYPENAME_DKFOLDER ("DKFolder")) and linksInboundFolderSources(true), DKUsageError with error ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) is thrown (appended with text describing the offending options).
PERFORMANCE
When disabled (default), some memory overhead is saved by avoiding unnecessary DKDDO instance. The inbound folder relationship links are still returned from the server among any other links retrieved. There is no network communication savings.
DATA STRUCTURES
If true, the sources for all inbound folder relationship links retrieved are recorded as DDO property named with constant DKConstant.DK_CM_PROPERTY_FOLDER_SOURCES that contains a value that is a dkCollection. The dkCollection contains the source blank DKDDO objects (with completed PID information) for the source DDOs of inbound folder links to report all folders containing this DDO. It is possible for multiple folders to contain the same item, document, or subfolder.
DK_CM_PROPERTY_FOLDER_SOURCES = <Collection of source DDOs>.
Example:
Note that in C++, the populated collection and contents are fully owned by the base DDO and are deleted automatically by the DDO.
BEHAVIOR NOTES
If no folder sources are found, at a minimum, an empty folder sources collection is added, indicating that none were found.
As mentioned in the "PRECEDENCE" section, when a specific link type name is requested through linkTypeFilter(String linkTypeNameRequested) and if you specify a link type filter that excludes folder relationships (any request that is not "*" or DKConstantICM.DK_ICM_LINKTYPENAME_DKFOLDER ("DKFolder")), an error is thrown because it directly contradicts your request since folder sources would be filtered. However, when using the older bitwise 'int' retrieve options (or when no options objects provided) and when requesting folder sources through the old folder source request interface (DKDDO property DKConstant.DK_CM_PROPERTY_RECORD_FOLDER_SOURCES = <"TRUE" | "FALSE"> (java.lang.String)), no such error is thrown and an empty folder sources collection is created even if folder relationships would be filtered through the older link type filter request interface (DKDDO property DKConstant.DK_CM_PROPERTY_LINKTYPE_SELECTED = <Link Type Name> (java.lang.String)).
Details concerning this topic and why this option is provided are explained in the "DATA STRUCTURES" section of DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested). Review links and folder relationship data structure information.
By default, inbound folder links are ignored when inbound links are retrieved. Because folder contents are stored in a DKFolder collection (containing DKDDO objects), not DKLinkCollection objects (containing DKLink objects), only targets of outbound links are stored in the DKFolder collection because only targets of the folder relationships are the folder contents. The inbound folder relationships (links) do not fit in the DKFolder collection and are never stored in DKLinkCollections because folder relationships are not to be treated as DKLink objects by the user of the API. Only updates to the DKFolder collection are honored as modifications to folder relationships.
You can instruct the retrieve operation to hang on to folder source information when it finds an inbound folder link. There is no additional server communication needed since the information is already available during the inbound link retrieve call. The folder source information is stored in a specific property as outlined below.
DEFAULT: false
PRECEDENCE
This setting only applies if inbound links are requested. Folder source DDOs can only be recorded if inbound links are listed. Additionally, if folder links are filtered out through the linksTypeFilter() setting, there are no inbound folder sources that can be recorded.
If linksInbound(false) and linksInboundFolderSources(true), DKUsageError with error ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) is thrown (appended with text describing the offending options).
If linksTypeFilter(NOT "*" or DKConstantICM.DK_ICM_LINKTYPENAME_DKFOLDER ("DKFolder")) and linksInboundFolderSources(true), DKUsageError with error ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) is thrown (appended with text describing the offending options).
PERFORMANCE
When disabled (default), some memory overhead is saved by avoiding unnecessary DKDDO instance. The inbound folder relationship links are still returned from the server among any other links retrieved. There is no network communication savings.
DATA STRUCTURES
If true, the sources for all inbound folder relationship links retrieved are recorded as DDO property named with constant DKConstant.DK_CM_PROPERTY_FOLDER_SOURCES that contains a value that is a dkCollection. The dkCollection contains the source blank DKDDO objects (with completed PID information) for the source DDOs of inbound folder links to report all folders containing this DDO. It is possible for multiple folders to contain the same item, document, or subfolder.
DK_CM_PROPERTY_FOLDER_SOURCES = <Collection of source DDOs>.
Example:
// Now find out if there were any source folders found: dkCollection foundSourceFoldersColl = null; propId = ddo.propertyId(DKConstant.DK_CM_PROPERTY_FOLDER_SOURCES); if(propId > 0) foundSourceFolderColl = (dkCollection) ddo.getProperty(propId); if(foundSourceFolderColl==null) System.out.println("No source folders found."); else System.out.println("Found '"+foundSourceFolderColl.cardinality()+"' source folders that contain this item."); // Want to access the source folders? dkIterator iter = foundSourceFolderColl.createIterator(); while(iter.more()){ DKDDO folder = (DKDDO) iter.next(); // Do any processing you wish }
Note that in C++, the populated collection and contents are fully owned by the base DDO and are deleted automatically by the DDO.
BEHAVIOR NOTES
If no folder sources are found, at a minimum, an empty folder sources collection is added, indicating that none were found.
As mentioned in the "PRECEDENCE" section, when a specific link type name is requested through linkTypeFilter(String linkTypeNameRequested) and if you specify a link type filter that excludes folder relationships (any request that is not "*" or DKConstantICM.DK_ICM_LINKTYPENAME_DKFOLDER ("DKFolder")), an error is thrown because it directly contradicts your request since folder sources would be filtered. However, when using the older bitwise 'int' retrieve options (or when no options objects provided) and when requesting folder sources through the old folder source request interface (DKDDO property DKConstant.DK_CM_PROPERTY_RECORD_FOLDER_SOURCES = <"TRUE" | "FALSE"> (java.lang.String)), no such error is thrown and an empty folder sources collection is created even if folder relationships would be filtered through the older link type filter request interface (DKDDO property DKConstant.DK_CM_PROPERTY_LINKTYPE_SELECTED = <Link Type Name> (java.lang.String)).
Parameters:
folderSourceDDOsRequested
- If 'true', you request to list folder source DDOs for any directly selected DDO. If 'false', you do not request such DDOs to be listed.
linksInboundFolderSources
- public boolean linksInboundFolderSources( )
See DKRetrieveOptionsICM::linksInboundFoldeSources(boolean folderSourceDDOsRequested)
linksDescriptors
- public void linksDescriptors(boolean linksDescriptorsRequested)
If list links requested (inbound or outbound), additionally list the
optional descriptor item DDOs.
Links optionally can include a descriptor item, a third DDO associated with this link to provide attributes and details for the link. By default, the general links list requests (linksOutbound() and linksInbound()) do not include listing the descriptor DDO since there is additional overhead if descriptor items exist for any links listed. By default, link descriptor DDOs will not be listed in the link and will instead appear as NULL.
Refer to DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested) for more details on listing links, performance considerations, and data structures that apply to descriptor DDOs as well.
DEFAULT: false
PRECEDENCE
This setting only applies when used in conjunction with the linksInbound() or linksOutbound(), which control whether links are listed in general. If no links are listed, there is no need to populate the descriptor DDOs for those links (since there are no links). This setting only populates the descriptor DDO in links listed by other links listing requests.
If linksInbound(false), linksOutbound(false), and linksDescriptors(true), DKUsageError with error ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) is thrown (appended with text describing the offending options).
PERFORMANCE
Listing optional link descriptor DDOs requires additional overhead if any are set in the links retrieved (there is *no* overhead if none are set in the links actually listed). By default, this setting does not include listing descriptor DDOs. Unless you need the descriptor nodes listed, leave linksDescriptors(boolean linksDescriptorsRequested) set to false. Set linksDescriptors() to true if you do want them listed. For any item that links with descriptor items set, one more call is made for all descriptors for that item (inbound and outbound combined / optimized together this time) to complete the PID information. For each item, one additional query is performed to fully populate descriptor DDOs for inbound and outbound links combined, if any are needed. For example, consider the case of 100 select 100 root components used earlier, but this time you also request descriptor nodes, and consider a case where each item has links with descriptor nodes. 100 additional calls are made to complete descriptor item information, one call for each item (regardless of inbound or outbound directions), and totaling 303 calls.
For more links listing performance considerations, refer to DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested).
DATA STRUCTURES
Descriptor items are populated in memory as the "link item" reference in DKLink objects. Refer to the SLinksICM API education sample for more details.
Links data structures are explained in more detail in DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested).
See DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested)
Links optionally can include a descriptor item, a third DDO associated with this link to provide attributes and details for the link. By default, the general links list requests (linksOutbound() and linksInbound()) do not include listing the descriptor DDO since there is additional overhead if descriptor items exist for any links listed. By default, link descriptor DDOs will not be listed in the link and will instead appear as NULL.
Refer to DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested) for more details on listing links, performance considerations, and data structures that apply to descriptor DDOs as well.
DEFAULT: false
PRECEDENCE
This setting only applies when used in conjunction with the linksInbound() or linksOutbound(), which control whether links are listed in general. If no links are listed, there is no need to populate the descriptor DDOs for those links (since there are no links). This setting only populates the descriptor DDO in links listed by other links listing requests.
If linksInbound(false), linksOutbound(false), and linksDescriptors(true), DKUsageError with error ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) is thrown (appended with text describing the offending options).
PERFORMANCE
Listing optional link descriptor DDOs requires additional overhead if any are set in the links retrieved (there is *no* overhead if none are set in the links actually listed). By default, this setting does not include listing descriptor DDOs. Unless you need the descriptor nodes listed, leave linksDescriptors(boolean linksDescriptorsRequested) set to false. Set linksDescriptors() to true if you do want them listed. For any item that links with descriptor items set, one more call is made for all descriptors for that item (inbound and outbound combined / optimized together this time) to complete the PID information. For each item, one additional query is performed to fully populate descriptor DDOs for inbound and outbound links combined, if any are needed. For example, consider the case of 100 select 100 root components used earlier, but this time you also request descriptor nodes, and consider a case where each item has links with descriptor nodes. 100 additional calls are made to complete descriptor item information, one call for each item (regardless of inbound or outbound directions), and totaling 303 calls.
For more links listing performance considerations, refer to DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested).
DATA STRUCTURES
Descriptor items are populated in memory as the "link item" reference in DKLink objects. Refer to the SLinksICM API education sample for more details.
Links data structures are explained in more detail in DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested).
See DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested)
Parameters:
linksDescriptorsRequested
- If 'true', you request descriptor item DDOs listed when links are listed for any directly selected DDO. If 'false', you do not request the optional descriptor DDO to be listed (if one exists for any links listed).
linksDescriptors
- public boolean linksDescriptors( )
See DKRetrieveOptionsICM::linksDescriptors(boolean linksDescriptorsRequested)
linksTypeFilter
- public void linksTypeFilter(java.lang.String linkTypeNameRequested)
- throws DKUsageError
- java.lang.Exception
If list links requested (inbound or outbound), list only links of
the specified link type name or specify '*' for all link types.
This setting simply filters links that are retrieved through other
link list requests, such as linksOutbound() and linksInbound().
By default all links are listed regardless of type when this option is used alone. However, if you only need one link type, you can save time transferring unnecessary data across the network and unnecessary memory usage to populate links of other link types.
For more information on link types, refer to the SLinkTypeDefinitionCreationICM and SLinkTypeDefinitionRetrievalICM API education samples.
DEFAULT: '*' (all link types considered / not filtering for a specific link type name)
PRECEDENCE
This setting only applies when used in conjunction with listing links (DKRetrieveOptionsICM::linksInbound(boolean), linksOutbound(boolean), linksLevelTwo(boolean), linksLevelTwoCount(boolean), and linksInboundFolderSources(boolean)). This is simply a filter to limit the scope of what is retrieved from the other link-related link retrieve option settings. If no links are listed, there is no need to consider a specific link type.
Since this setting relies on linksOutbound() and linksInbound() requests, first review DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested) and DKRetrieveOptionsICM::linksInbound(boolean linksInboundRequested).
This does not request data, but only filters data selected by other options, this setting is simply ignored if no link information is retrieved. No exception is thrown.
PERFORMANCE
If multiple link types exist, you can same a small amount of network traffic and a measurable improvement in the number of objects created and memory used if a number of links exist for other link types if you only have plans to use links of one type.
If you only have one links of one link type, there is no performance impact unless the link type you selected is not the link type of your links. Even if there is no current difference, specifying the link type that your application is interested in helps it maintain optimal performance should another application (or another part of your application) adds new links types or creates links of different link types in the future. The current code of your application would continue to only retrieve links of types it is interested in. However, you must also balance general purpose processing in case it were better for your application logic to handle all link types in case they were added by another application in the future. Should you add links of another link type in the future, you must remember to assess whether the logic currently using this setting still should only see one link type of if it should handle all link types generically. This depends on your application and the semantics you enforce for link types.
DATA STRUCTURES
This setting only filters links listed through other links settings. No new data structures are populated. See DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested) for details on listed links data structures.
BEHAVIOR NOTES
When linksInbound(true) or linksOutbound(true), all existing links in the respective directions are cleared from the DKLinkCollections in the directly-selected DKDDOs. The linkTypeFilter(String linkTypeNameRequested) does not mean that existing links of other types will remain as if to only refresh the specified link type. Within link collections, outdated link information is not mixed with new link information in within the same direction (inbound or outbound). If you previously had links of several link types populated in your DKDDO and then re-retrieved or refreshed with a specific link type requested, all existing links will be cleared in the direction (inbound or outbound) requested.
By default all links are listed regardless of type when this option is used alone. However, if you only need one link type, you can save time transferring unnecessary data across the network and unnecessary memory usage to populate links of other link types.
For more information on link types, refer to the SLinkTypeDefinitionCreationICM and SLinkTypeDefinitionRetrievalICM API education samples.
DEFAULT: '*' (all link types considered / not filtering for a specific link type name)
PRECEDENCE
This setting only applies when used in conjunction with listing links (DKRetrieveOptionsICM::linksInbound(boolean), linksOutbound(boolean), linksLevelTwo(boolean), linksLevelTwoCount(boolean), and linksInboundFolderSources(boolean)). This is simply a filter to limit the scope of what is retrieved from the other link-related link retrieve option settings. If no links are listed, there is no need to consider a specific link type.
Since this setting relies on linksOutbound() and linksInbound() requests, first review DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested) and DKRetrieveOptionsICM::linksInbound(boolean linksInboundRequested).
This does not request data, but only filters data selected by other options, this setting is simply ignored if no link information is retrieved. No exception is thrown.
PERFORMANCE
If multiple link types exist, you can same a small amount of network traffic and a measurable improvement in the number of objects created and memory used if a number of links exist for other link types if you only have plans to use links of one type.
If you only have one links of one link type, there is no performance impact unless the link type you selected is not the link type of your links. Even if there is no current difference, specifying the link type that your application is interested in helps it maintain optimal performance should another application (or another part of your application) adds new links types or creates links of different link types in the future. The current code of your application would continue to only retrieve links of types it is interested in. However, you must also balance general purpose processing in case it were better for your application logic to handle all link types in case they were added by another application in the future. Should you add links of another link type in the future, you must remember to assess whether the logic currently using this setting still should only see one link type of if it should handle all link types generically. This depends on your application and the semantics you enforce for link types.
DATA STRUCTURES
This setting only filters links listed through other links settings. No new data structures are populated. See DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested) for details on listed links data structures.
BEHAVIOR NOTES
When linksInbound(true) or linksOutbound(true), all existing links in the respective directions are cleared from the DKLinkCollections in the directly-selected DKDDOs. The linkTypeFilter(String linkTypeNameRequested) does not mean that existing links of other types will remain as if to only refresh the specified link type. Within link collections, outdated link information is not mixed with new link information in within the same direction (inbound or outbound). If you previously had links of several link types populated in your DKDDO and then re-retrieved or refreshed with a specific link type requested, all existing links will be cleared in the direction (inbound or outbound) requested.
Parameters:
linkTypeNameRequested
- Specify the name of a defined link type in the system that you want to limit link listing to only that link type. Specify "*" to request all link types (or no specific link type name). Any name specified other than special keyword "*" should be a valid name defined in the system. You should choose among the list of link types returned from DKDatastoreDefICM::listLinkTypes().
Throws:
DKMessageId.DK_CM_MSG_INVPARM
- DKUsageError with ID DKMessageId.DK_CM_MSG_INVPARM (DGL0303A) if the linkTypeNameRequested parameter specified is invalid because no real value was specified. The invalid parameter text is appended with message from ID DKMessageIdICM.DK_ICM_MSG_LINK_TYPE_NAME_NOT_SPECIFIED (DGL5144A) if the link type name was empty ("").
DKMessageIdICM.DK_ICM_MSG_VALID_LINKTYPENAME_NOT_FOUND
- DKUsageError with ID DKMessageIdICM.DK_ICM_MSG_VALID_LINKTYPENAME_NOT_FOUND (DGL3846A) if the linkTypeNameRequested parameter specified cannot be found in the system. Verify correct spelling and capitalization. Use only defined names listed by DKDatstoreDefICM::listLinkTypes().
java.lang.Exception
- propagated from DKDatastoreDefICM::getLinkTypeIDByName(String linkTypeName). linksTypeFilter
- public java.lang.String linksTypeFilter( )
See DKRetrieveOptionsICM::linksType(boolean linksTypeRequested)
linksLevelTwo
- public void linksLevelTwo(boolean linksLevelTwoRequested)
If already listing the first level of links, this setting requests the second level
of links for any inbound or outbound link list request.
If you plan on retrieving multiple levels of links, you can significantly optimize performance using the linksLevelTwo() setting to reduce the number of calls (by 1/1000 in an extreme example) compared to simply calling retrieve with the links list options requested. Two levels can be obtained during the same call to the server that obtains one level of links.
If you want to retrieve the whole link tree, you can utilize the two-level links list setting (but remember links & folder relationships can be cyclic).
Since this setting relies on linksOutbound() and linksInbound() requests, first review DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested) and DKRetrieveOptionsICM::linksInbound(boolean linksInboundRequested).
JAVA ONLY
This option is not available in the C++ API. The C++ API assumes the default value for this option and it is not possible to request two levels of links at once.
DEFAULT: false
PRECEDENCE
This setting only applies when used in conjunction with the first level of links requests, linksInbound() and linksOutbound(), which control whether links are listed in general. If no links are listed at the first level, there is no need to populate a second level of links because there is no first level in the data structure to store a second level.
Since this setting relies on linksOutbound() and linksInbound() requests, first review DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested) and DKRetrieveOptionsICM::linksInbound(boolean linksInboundRequested).
This setting is also filtered by specific link type requests by DKRetrieveOptionsICM::linksTypeFilter(). Also, whether or not the descriptor DDOs ("link items") associated with each link are retrieved depend on the DKRetrieveOptionsICM::linksDescriptors(boolean) setting.
If linksLevelTwo(true) but no first level of links requested (both linksInbound(false) and linksOutbound(false)), DKUsageError is thrown with Error ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) and appended with the offending options.
You can request only one of linksLevelTwo(true) or linksLevelTwoCount(true), not both. If both linksLevelTwo(true) and linksLevelTwoCount(true), DKUsageError is thrown with Error ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) and appended with the offending options. More details on the error is provided in the BEHAVIOR NOTES section.
PERFORMANCE
First, you must understand the performance implications of the first level of links.
See DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested)
Retrieving two levels of links at once is significantly faster than retrieving links one level at a time by making only one call to the server for both levels instead of one level. Of course if you do not need two levels of links, it is unnecessary to incur the additional network traffic to read the second level of links even if performed during the same call or for the memory structures to store the information in the DKDDO. If you remember the number of calls explained in linksOutbound() for one level, you can see how many additional calls are needed to retrieve the second level (on a single-item basis and for each requested direction (inbound & outbound)).
Consider just the case of retrieving 100 items with attributes, inbound links, and outbound links. linksOutbound(bool) explained how that requires about 203 calls to the server. Suppose each of those returned 10 inbound links and 10 outbound links. If absolutely wanted to retrieve the both levels for all those items and links at once and optimize retrieval, suppose you choose to make two separate retrieve calls, once for the first level of links and attributes (about 203 calls to the server internally) and then packaged up a new DKSequentialCollection with all of your source DDOs for any inbound links and target DDOs for any outbound links and called retrieve again, requesting their first level of links (no attributes for an equivalent comparison). This would require another 100*10=1,000 calls to retrieve inbound links for all 100 original items' 10 inbound linked source DDOs each and another 100*10=1,000 to retrieve the outbound links for all 100 original items' 10 outbound linked target DDOs. Now 2,203 calls were made to the sever. If you instead made only one retrieve call and requested two levels of links, two levels of links are retrieved in the original calls for each of the 100 items for link information. Now you avoided the extra 2,000 calls and instead obtained the desired result with only 203 calls by using this setting.
If you only need the count of the second level of children, you can save unnecessary network and memory structure overhead to transfer and store the additional information. See DKRetrieveOptionsICM::linksLevelTwoCount(boolean linksLevelTwoRequested) for more info.
Additional detailed explanations and performance case examples are located in online support document 1177743.
See online support document 1177743
DATA STRUCTURES
First, you must understand how the first level of links are structured.
See DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested)
The second level of links are populated just as the first level of links are populated in their respective parent DKDDOs. However, the second level of links are populated in their corresponding parent DKDDOs which are the listed source or target references (depending on whether it is an inbound or outbound link) within the listed links under the directly selected DKDDO. For example, linksOutbound(true) populates a directly selected DKDDO with DKLinkCollections which in turn contain DKLink objects. Those DKLink objects contain a blank target DKDDO reference with completed PID information. *If* this setting is used, then the target DKDDO reference that originally only had completed PID information (and was otherwise blank), now had DKLinkCollections of its own with DKLink objects and target DKDDOs for the next generation of links from the target item. The second generation target DDO is a blank DKDDO with completed PID information (no further DKLinkCollections) until you make another retrieve call passing in that DKDDO.
Links data structures are explained in more detail in DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested).
BEHAVIOR NOTES
If both linksLevelTwo(true) and linksLevelTwoCount(true), the following exception is thrown from the retrieve call:
DKUsageError is thrown with Error ID
This feature requires server level of V8.3 Fix Pack 4 (8.3.00.400) or greater. If the connected library server is not upgraded to V8.3 Fix Pack 4 or later, a DKUsageError is thrown with Error ID
If you plan on retrieving multiple levels of links, you can significantly optimize performance using the linksLevelTwo() setting to reduce the number of calls (by 1/1000 in an extreme example) compared to simply calling retrieve with the links list options requested. Two levels can be obtained during the same call to the server that obtains one level of links.
If you want to retrieve the whole link tree, you can utilize the two-level links list setting (but remember links & folder relationships can be cyclic).
Since this setting relies on linksOutbound() and linksInbound() requests, first review DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested) and DKRetrieveOptionsICM::linksInbound(boolean linksInboundRequested).
JAVA ONLY
This option is not available in the C++ API. The C++ API assumes the default value for this option and it is not possible to request two levels of links at once.
DEFAULT: false
PRECEDENCE
This setting only applies when used in conjunction with the first level of links requests, linksInbound() and linksOutbound(), which control whether links are listed in general. If no links are listed at the first level, there is no need to populate a second level of links because there is no first level in the data structure to store a second level.
Since this setting relies on linksOutbound() and linksInbound() requests, first review DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested) and DKRetrieveOptionsICM::linksInbound(boolean linksInboundRequested).
This setting is also filtered by specific link type requests by DKRetrieveOptionsICM::linksTypeFilter(). Also, whether or not the descriptor DDOs ("link items") associated with each link are retrieved depend on the DKRetrieveOptionsICM::linksDescriptors(boolean) setting.
If linksLevelTwo(true) but no first level of links requested (both linksInbound(false) and linksOutbound(false)), DKUsageError is thrown with Error ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) and appended with the offending options.
You can request only one of linksLevelTwo(true) or linksLevelTwoCount(true), not both. If both linksLevelTwo(true) and linksLevelTwoCount(true), DKUsageError is thrown with Error ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) and appended with the offending options. More details on the error is provided in the BEHAVIOR NOTES section.
PERFORMANCE
First, you must understand the performance implications of the first level of links.
See DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested)
Retrieving two levels of links at once is significantly faster than retrieving links one level at a time by making only one call to the server for both levels instead of one level. Of course if you do not need two levels of links, it is unnecessary to incur the additional network traffic to read the second level of links even if performed during the same call or for the memory structures to store the information in the DKDDO. If you remember the number of calls explained in linksOutbound() for one level, you can see how many additional calls are needed to retrieve the second level (on a single-item basis and for each requested direction (inbound & outbound)).
Consider just the case of retrieving 100 items with attributes, inbound links, and outbound links. linksOutbound(bool) explained how that requires about 203 calls to the server. Suppose each of those returned 10 inbound links and 10 outbound links. If absolutely wanted to retrieve the both levels for all those items and links at once and optimize retrieval, suppose you choose to make two separate retrieve calls, once for the first level of links and attributes (about 203 calls to the server internally) and then packaged up a new DKSequentialCollection with all of your source DDOs for any inbound links and target DDOs for any outbound links and called retrieve again, requesting their first level of links (no attributes for an equivalent comparison). This would require another 100*10=1,000 calls to retrieve inbound links for all 100 original items' 10 inbound linked source DDOs each and another 100*10=1,000 to retrieve the outbound links for all 100 original items' 10 outbound linked target DDOs. Now 2,203 calls were made to the sever. If you instead made only one retrieve call and requested two levels of links, two levels of links are retrieved in the original calls for each of the 100 items for link information. Now you avoided the extra 2,000 calls and instead obtained the desired result with only 203 calls by using this setting.
If you only need the count of the second level of children, you can save unnecessary network and memory structure overhead to transfer and store the additional information. See DKRetrieveOptionsICM::linksLevelTwoCount(boolean linksLevelTwoRequested) for more info.
Additional detailed explanations and performance case examples are located in online support document 1177743.
See online support document 1177743
DATA STRUCTURES
First, you must understand how the first level of links are structured.
See DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested)
The second level of links are populated just as the first level of links are populated in their respective parent DKDDOs. However, the second level of links are populated in their corresponding parent DKDDOs which are the listed source or target references (depending on whether it is an inbound or outbound link) within the listed links under the directly selected DKDDO. For example, linksOutbound(true) populates a directly selected DKDDO with DKLinkCollections which in turn contain DKLink objects. Those DKLink objects contain a blank target DKDDO reference with completed PID information. *If* this setting is used, then the target DKDDO reference that originally only had completed PID information (and was otherwise blank), now had DKLinkCollections of its own with DKLink objects and target DKDDOs for the next generation of links from the target item. The second generation target DDO is a blank DKDDO with completed PID information (no further DKLinkCollections) until you make another retrieve call passing in that DKDDO.
Links data structures are explained in more detail in DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested).
BEHAVIOR NOTES
If both linksLevelTwo(true) and linksLevelTwoCount(true), the following exception is thrown from the retrieve call:
DKMessageId.DK_CM_MSG_BADOPTVALUE
DKUsageError is thrown with Error ID
DKMessageId.DK_CM_MSG_BADOPTVALUE
(DGL0314A) and appended with text identifying the offending options,
"[ DKRetrieveOptionsICM.linksLevelTwo(true) DKRetrieveOptionsICM.linksLevelTwoCount(true) ]"
.
This feature requires server level of V8.3 Fix Pack 4 (8.3.00.400) or greater. If the connected library server is not upgraded to V8.3 Fix Pack 4 or later, a DKUsageError is thrown with Error ID
DKMessageId.DK_CM_MSG_BADOPTVALUE
(DGL0314A) and appended
with text identifying the offending option and level,
"[ DKRetrieveOptionsICM.linksLevelTwo(true) DKDatastoreICM{"<your datastore name>" V"<your library server version>" <8.3.00.400} ]"
.
Parameters:
linksLevelTwoRequested
- If 'true', you request the second level of links to be listed when links are listed and found for any directly selected DDO. If 'false', you do not request the second level of links to be listed.
linksLevelTwo
- public boolean linksLevelTwo()
See DKRetrieveOptionsICM::linksLevelTwo(boolean linksLevelTwoRequested)
linksLevelTwoCount
- public void linksLevelTwoCount( boolean linksLevelTwoCountRequested)
If already listing the first level of links, this setting requests the second level
of links count for any inbound or outbound link list request. If you need to know
the count for the next level, but do not need the sub-links themselves for all linked items,
this setting minimizes unnecessary network transfer, memory structure overhead, and optimizes
the request into the original calls for the first level of links (no additional server
calls made).
This setting is most often used if an application needs to determine whether or not links (or folder contents) exist under an item. For example, an application might use this setting to know whether to place a "[+]" sign in front of a folder or document. Listing the second level of links for all first level links can be far more expensive than necessary if only one or two will actually be traversed, perhaps when one folder out of 100 is selected by a user in an application. Using this option (or levelTwo) if absolutely necessary to retrieve two levels or level-one plus level-two count, this can significantly reduce the number of calls (by 1/1000 in an extreme example) compared to simply calling retrieve again with the links list option for the targets (or sources) of the first level of links.
DEFAULT: false
PRECEDENCE
This setting only applies when used in conjunction with the first level of links requests, linksInbound() and linksOutbound(), which control whether links are listed in general. If no links are listed at the first level, there is no need to populate a second level of links because there is no first level in the data structure to store a second level.
Since this setting relies on linksOutbound() and linksInbound() requests, first review DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested) and DKRetrieveOptionsICM::linksInbound(boolean linksInboundRequested).
This setting is also filtered by specific link type requests by DKRetrieveOptionsICM::linksTypeFilter().
If linksLevelTwoCount(true) but no first level of links requested (both linksInbound(false) and linksOutbound(false)), DKUsageError is thrown with Error ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) and appended with the offending options.
You can request only one of linksLevelTwo(true) or linksLevelTwoCount(true), not both. If both linksLevelTwo(true) and linksLevelTwoCount(true), DKUsageError is thrown with Error ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) and appended with the offending options. More details on the error is provided in the BEHAVIOR NOTES section.
PERFORMANCE
First, you must understand the performance implications of the first level of links.
See DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested)
The second level count performance implications are very similar to the linksLevelTwo() setting, except that only a count is needed. If you only need the count, there is additional saving from network traffic and memory structure overhead if you did not otherwise need the second generation of link objects.
See DKRetrieveOptionsICM::linksLevelTwo(boolean linksLevelTwoRequested)
Assuming you need the first level of links retrieved for all items selected for retrieval, this is the fastest way to determine the count (or existence) of the next level of links. However, remember that the first level of links has its own significant performance considerations (see linksOutbound()). Depending on your application, it might be better to reconsider listing links at the first level, instead use an alternative (online document 1166065) for an existential check, and list links only for those directly selected for expansion by an end user. For more details on this alternative, see DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested).
Calculation of the second level links count is not free, and although the data structures and network traffic is minimal, additional server processing overhead is incurred.
Additional detailed explanations and performance case examples are located in online support document 1177748.
See online support document 1177748
DATA STRUCTURES
First, you must understand how the first level of links are structured.
See DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested)
The second level links count is populated in their corresponding parent DKDDOs which are the listed source or target references (depending on whether it is an inbound or outbound link) within the listed links under the directly selected DKDDO.
The separate inbound and outbound link counts are stored as properties in the respective DKDDO. The property named with constant DKConstant.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 constant DKConstant.DK_CM_PROPERTY_LINKS_INBOUND_SELECTED_COUNT contains the count of the number of inbound links of the link type(s) selected for retrieval. Note that the folder contents counts are included with the outbound selected count.
BEHAVIOR NOTES
If both linksLevelTwo(true) and linksLevelTwoCount(true), the following exception is thrown from the retrieve call:
DKUsageError is thrown with Error ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) and appended with text identifying the offending options,
This setting is most often used if an application needs to determine whether or not links (or folder contents) exist under an item. For example, an application might use this setting to know whether to place a "[+]" sign in front of a folder or document. Listing the second level of links for all first level links can be far more expensive than necessary if only one or two will actually be traversed, perhaps when one folder out of 100 is selected by a user in an application. Using this option (or levelTwo) if absolutely necessary to retrieve two levels or level-one plus level-two count, this can significantly reduce the number of calls (by 1/1000 in an extreme example) compared to simply calling retrieve again with the links list option for the targets (or sources) of the first level of links.
DEFAULT: false
PRECEDENCE
This setting only applies when used in conjunction with the first level of links requests, linksInbound() and linksOutbound(), which control whether links are listed in general. If no links are listed at the first level, there is no need to populate a second level of links because there is no first level in the data structure to store a second level.
Since this setting relies on linksOutbound() and linksInbound() requests, first review DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested) and DKRetrieveOptionsICM::linksInbound(boolean linksInboundRequested).
This setting is also filtered by specific link type requests by DKRetrieveOptionsICM::linksTypeFilter().
If linksLevelTwoCount(true) but no first level of links requested (both linksInbound(false) and linksOutbound(false)), DKUsageError is thrown with Error ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) and appended with the offending options.
You can request only one of linksLevelTwo(true) or linksLevelTwoCount(true), not both. If both linksLevelTwo(true) and linksLevelTwoCount(true), DKUsageError is thrown with Error ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) and appended with the offending options. More details on the error is provided in the BEHAVIOR NOTES section.
PERFORMANCE
First, you must understand the performance implications of the first level of links.
See DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested)
The second level count performance implications are very similar to the linksLevelTwo() setting, except that only a count is needed. If you only need the count, there is additional saving from network traffic and memory structure overhead if you did not otherwise need the second generation of link objects.
See DKRetrieveOptionsICM::linksLevelTwo(boolean linksLevelTwoRequested)
Assuming you need the first level of links retrieved for all items selected for retrieval, this is the fastest way to determine the count (or existence) of the next level of links. However, remember that the first level of links has its own significant performance considerations (see linksOutbound()). Depending on your application, it might be better to reconsider listing links at the first level, instead use an alternative (online document 1166065) for an existential check, and list links only for those directly selected for expansion by an end user. For more details on this alternative, see DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested).
Calculation of the second level links count is not free, and although the data structures and network traffic is minimal, additional server processing overhead is incurred.
Additional detailed explanations and performance case examples are located in online support document 1177748.
See online support document 1177748
DATA STRUCTURES
First, you must understand how the first level of links are structured.
See DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested)
The second level links count is populated in their corresponding parent DKDDOs which are the listed source or target references (depending on whether it is an inbound or outbound link) within the listed links under the directly selected DKDDO.
The separate inbound and outbound link counts are stored as properties in the respective DKDDO. The property named with constant DKConstant.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 constant DKConstant.DK_CM_PROPERTY_LINKS_INBOUND_SELECTED_COUNT contains the count of the number of inbound links of the link type(s) selected for retrieval. Note that the folder contents counts are included with the outbound selected count.
Property Name : DK_CM_PROPERTY_LINKS_OUTBOUND_SELECTED_COUNT Property Value: Integer with count Property Name : DK_CM_PROPERTY_LINKS_INBOUND_SELECTED_COUNT Property Value: Integer with countLinks data structures are explained in more detail in DKRetrieveOptionsICM::linksOutbound(boolean linksOutboundRequested).
BEHAVIOR NOTES
If both linksLevelTwo(true) and linksLevelTwoCount(true), the following exception is thrown from the retrieve call:
DKMessageId.DK_CM_MSG_BADOPTVALUE
DKUsageError is thrown with Error ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) and appended with text identifying the offending options,
"[ DKRetrieveOptionsICM.linksLevelTwo(true) DKRetrieveOptionsICM.linksLevelTwoCount(true) ]"
Parameters:
linksLevelTwoCountRequested
- If 'true', you request the second level links count to be listed when links are listed and found for any directly selected DDO. If 'false', you do not request the second level links count to be listed.
linksLevelTwoCount
- public boolean linksLevelTwoCount( )
See DKRetrieveOptionsICM::linksLevelTwoCount(boolean linksLevelTwoCountRequested)
partsList
- public void partsList(boolean partsListRequested)
Request the document parts listed (table of contents (TOC)) for any directly
selected component DDOs that happens to be a root component of a
"document" classified item type.
Item types are defined with one of four possible classifications, Standard/Non-Resource, Resource, Document, and Part. For items created for "document" classified item types, the root component DDOs can have "document parts", similar to resource items most likely with resource content, except that they are owned and controlled through a parent document. This setting requests that any document parts be listed.
This setting only "lists" parts (also considered a table of contents), blank part DKDDOs with completed PID information that is sufficient for subsequent retrieve, update, or delete requests. This setting does not populate any data for the part DDOs, such as attributes, properties, or resource content. You can call multi-item retrieve passing the parts collection and any retrieve options in a subsequent call or you can optimize attribute and content retrieval in one call by using the DKRetrieveOptionsICM::partsAttributes() and DKRetrieveOptionsICM::resourceContent() settings.
For more information on item types, classifications, and document parts, refer to the SItemTypeCreationICM API education sample.
For more information on using documents and parts, refer to the SDocModelItemICM API education sample.
DEFAULT: false
PRECEDENCE
This setting is independent with one exception.
If a projection list (DKProjectionListICM) is specified (through DKRetrieveOptionsICM::attributeFilters(DKProjectionListICM)) and if the projection list omits projections for directly-selected base DDOs, DDOs of that type are not retrieved, no existence check is performed, and no parts are listed for DDOs of that type. (Note that even if the directly selected component type is filtered out by an omitted projection, if children are requested, and one or more children exist, and are children not filtered out by omitted projections, those particular items are considered validated and parts can be listed.) No exception is thrown if the directly-selected parent document DDOs are filtered out by the projection causing the parts list to not be retrieved.
PERFORMANCE
Retrieving the list (TOC) of parts requires a separate call to the server for each "document"-classified DDO that is in the directly-selected collection submitted to retrieve. You should only retrieve the parts list if you need the part list at this time and only for the document(s) that the parts list is truly needed. Unnecessary calls to the server can be noticeably expensive, especially if you have a collection of items that results in a separate call for each individual item to retrieve data that cannot be optimized under multi-item retrieve, such as parts lists.
For example, if you submitted 100 components to multi-item retrieve, and if all 100 are from "document"-classified item types, then 100 additional calls are made on top of processing for other data requested in the options as well as at least a multi-item existence check for the document DDOs.
Typically, applications should only request parts lists on a single-item basis only when needed (such as when selected for viewing by a user). For example, if an application were to perform a query and display results, the parts list is typically not needed to simply display results and therefore no parts list should be requested. When a user selects one of the results to view, call retrieve and request the parts list for the single item, but only if you application is going to use the parts list in the subsequent display to the user.
If there happen to be no DDOs from "document"-classified item types in the selected DDOs for retrieval, this setting does not incur any measurable cost.
DATA STRUCTURES
Document parts listed are added to their respective parent DKDDO as a DKParts (dkCollection interface), for any selected DKDDO that is both a root component and represents a "document" classified item type. Document parts appear as a DKDDO "data item" in the attribute namespace (DKConstant::DK_CM_NAMESPACE_ATTR) named DKConstant::DK_CM_DKPARTS ("DKParts"). (ddo.dataId(DKConstant.DK_CM_NAMESPACE_ATTR,DKConstant.DK_CM_DKPARTS)) This "data item" has data item type DK_CM_DATAITEM_TYPE_COLLECTION_XDO. The value of this data item is a DKParts object (dkCollection interface) that contains blank DKDDOs with completed PID information for each document part.
Remember, you can iterate through all "data items" in a DKDDO by looping through all data item IDs from '0' to "ddo.dataCount()" (across all "data item" namespaces which can include other "data items" such as child collections, link collections, and other attributes but can be identified by a type indicator).
You should always first make sure the DKParts attribute exists first due to various retrieve options or in case some DKDDOs do have their parts retrieved yet, or some are child components, document parts themselves, or DKDDOs from other non-"document" classified item types.
To determine if any attribute exists, first look up the "data item" ID using ddo.dataId(DKConstant.DK_CM_NAMESPACE_ATTR,<your attribute name String>). (For example ddo.dataId(DKConstant.DK_CM_NAMESPACE_ATTR,DKConstant.DK_CM_DKPARTS); ) If the ID returned is '-1', no data item by that name exists. Once you have a valid ID or if you are listing through each ID, you can obtain the individual data item name ("ddo.getDataName(dataid)"), value ("ddo.getData(dataid)"), and value type ((short) ddoItem.getDataPropertyByName(dataid,DK_CM_PROPERTY_TYPE)) to help you cast or otherwise handle correctly. Part collections appear with data item type DK_CM_DATAITEM_TYPE_COLLECTION_XDO. (Details on detecting and handling all types explained in the SItemRetrievalICM sample.)
Depending on the XDO classification (not to be confused with item type classification) of the document part item type (see SItemTypeCreationICM API education sample for details), the actual resource item or part instances are a subclass of DKDDO. All parts and resource items are typically instances of the DKLobICM subclass of DKDDO (but you should cast by XDO type or by part type that your application is familiar with). All predefined XDO classes that support resource content are instances of DKLobICM or subclassed extensions of DKLobICM. Depending on the XDO classification, part types and resource items are instances of DKLobICM (for LOB), DKTextICM (for TEXT), DKImageICM (for IMAGE), DKStreamICM (for STREAM), DKVideoStreamICM (for VIDEO STREAM), or other subclasses for any application defined and implemented XDO Classes and part-classified item type definitions.
You can programmatically determine which subclass to cast to based on XDO classification. For all predefined XDO classifications, you could assume a DKLobICM instance at a minimum that you could cast to. The safest programmatic solution is to assume a DKDDO instance at a minimum for all item types. As a DKDDO, look up the "object type",
For examples and details accessing parts, refer to the SDocModelItemICM API education samples.
BEHAVIOR NOTES
If the item types of the DDOs selected are not "document" classified, or if no part types are selected in the item type (item type relations), or if a document happens to have no children, the call returns without error. No exceptions are thrown.
When using the DKRetrieveOptionsICM interface, the parts are never listed unless requested. Under the old bitwise 'int' retrieve options or default if no options specified, if you used single-item retrieve (DKDDO.retrieve(), DKLobICM.retrieve(), or DKDatastoreICM.retrieveObject(dkDataObject)), parts were always listed and parts attributes & properties retrieved (but no parts resource content) unless you specified DKConstant.DK_CM_CONTENT_ATTRONLY. For compatibility with existing applications, if you use the old bitwise 'int' options or rely on defaults, parts are always listed (and parts attributes and properties retrieved) unless you used option DKConstant.DK_CM_CONTENT_ATTRONLY, the only option that excluded parts listing when using single-item retrieve. Multi-item retrieve and query operations are not affected (they do not automatically include parts listing or parts attributes & properties by default). In all cases, if you use a DKRetrieveOptionsICM interface with your retrieve request, the partsList(false) and partsAttributes(false) settings are honored and parts lists and attributes are not retrieved unless you specifically requested them.
When using the DKRetrieveOptionsICM interface to pass options, retrieve omits the useless, empty, special child collection named "ICMParts1006" (or any with similar names) for special system child component types that can appear in "document" classified item types. When using the old bitwise 'int' retrieve options (or defaults if no options specified), a special (but useless) child collection with a name similar to "ICMParts10__" might be added in many cases and should be ignored (do not use). For more information on the "ICMParts10__" child collection, see the "BEHAVIOR NOTES" section of DKRetrieveOptionsICM::childListOneLevel(boolean).
When using the DKRetrieveOptionsICM interface to pass options, the listed part DDOs contain only the essential PID information for subsequent retrieve requests on the part DDOs. No additional attributes or properties are populated. Note that when using bitwise 'int' retrieve option DKConstant.DK_CM_CONTENT_YES with multi-item retrieve (DKDatastoreICM::retrieveObjects(dkCollection)) or query (DKDatastoreICM::evaluate() or execute()), the parts are listed, but the part DDOs have all attributes initialized, but not set to their accurate values. The ACL Name and Semantic Type properties are added to the DKDDO, but they are simply initialized, but the values are incorrect. Subsequent retrieve requests for attributes refresh the DDOs with the correct values. When using DKRetrieveOptionsICM options the part DDOs are not initialized beyond the PID and no inaccurate values are set.
Item types are defined with one of four possible classifications, Standard/Non-Resource, Resource, Document, and Part. For items created for "document" classified item types, the root component DDOs can have "document parts", similar to resource items most likely with resource content, except that they are owned and controlled through a parent document. This setting requests that any document parts be listed.
This setting only "lists" parts (also considered a table of contents), blank part DKDDOs with completed PID information that is sufficient for subsequent retrieve, update, or delete requests. This setting does not populate any data for the part DDOs, such as attributes, properties, or resource content. You can call multi-item retrieve passing the parts collection and any retrieve options in a subsequent call or you can optimize attribute and content retrieval in one call by using the DKRetrieveOptionsICM::partsAttributes() and DKRetrieveOptionsICM::resourceContent() settings.
For more information on item types, classifications, and document parts, refer to the SItemTypeCreationICM API education sample.
For more information on using documents and parts, refer to the SDocModelItemICM API education sample.
DEFAULT: false
PRECEDENCE
This setting is independent with one exception.
If a projection list (DKProjectionListICM) is specified (through DKRetrieveOptionsICM::attributeFilters(DKProjectionListICM)) and if the projection list omits projections for directly-selected base DDOs, DDOs of that type are not retrieved, no existence check is performed, and no parts are listed for DDOs of that type. (Note that even if the directly selected component type is filtered out by an omitted projection, if children are requested, and one or more children exist, and are children not filtered out by omitted projections, those particular items are considered validated and parts can be listed.) No exception is thrown if the directly-selected parent document DDOs are filtered out by the projection causing the parts list to not be retrieved.
PERFORMANCE
Retrieving the list (TOC) of parts requires a separate call to the server for each "document"-classified DDO that is in the directly-selected collection submitted to retrieve. You should only retrieve the parts list if you need the part list at this time and only for the document(s) that the parts list is truly needed. Unnecessary calls to the server can be noticeably expensive, especially if you have a collection of items that results in a separate call for each individual item to retrieve data that cannot be optimized under multi-item retrieve, such as parts lists.
For example, if you submitted 100 components to multi-item retrieve, and if all 100 are from "document"-classified item types, then 100 additional calls are made on top of processing for other data requested in the options as well as at least a multi-item existence check for the document DDOs.
Typically, applications should only request parts lists on a single-item basis only when needed (such as when selected for viewing by a user). For example, if an application were to perform a query and display results, the parts list is typically not needed to simply display results and therefore no parts list should be requested. When a user selects one of the results to view, call retrieve and request the parts list for the single item, but only if you application is going to use the parts list in the subsequent display to the user.
If there happen to be no DDOs from "document"-classified item types in the selected DDOs for retrieval, this setting does not incur any measurable cost.
DATA STRUCTURES
Document parts listed are added to their respective parent DKDDO as a DKParts (dkCollection interface), for any selected DKDDO that is both a root component and represents a "document" classified item type. Document parts appear as a DKDDO "data item" in the attribute namespace (DKConstant::DK_CM_NAMESPACE_ATTR) named DKConstant::DK_CM_DKPARTS ("DKParts"). (ddo.dataId(DKConstant.DK_CM_NAMESPACE_ATTR,DKConstant.DK_CM_DKPARTS)) This "data item" has data item type DK_CM_DATAITEM_TYPE_COLLECTION_XDO. The value of this data item is a DKParts object (dkCollection interface) that contains blank DKDDOs with completed PID information for each document part.
Remember, you can iterate through all "data items" in a DKDDO by looping through all data item IDs from '0' to "ddo.dataCount()" (across all "data item" namespaces which can include other "data items" such as child collections, link collections, and other attributes but can be identified by a type indicator).
You should always first make sure the DKParts attribute exists first due to various retrieve options or in case some DKDDOs do have their parts retrieved yet, or some are child components, document parts themselves, or DKDDOs from other non-"document" classified item types.
To determine if any attribute exists, first look up the "data item" ID using ddo.dataId(DKConstant.DK_CM_NAMESPACE_ATTR,<your attribute name String>). (For example ddo.dataId(DKConstant.DK_CM_NAMESPACE_ATTR,DKConstant.DK_CM_DKPARTS); ) If the ID returned is '-1', no data item by that name exists. Once you have a valid ID or if you are listing through each ID, you can obtain the individual data item name ("ddo.getDataName(dataid)"), value ("ddo.getData(dataid)"), and value type ((short) ddoItem.getDataPropertyByName(dataid,DK_CM_PROPERTY_TYPE)) to help you cast or otherwise handle correctly. Part collections appear with data item type DK_CM_DATAITEM_TYPE_COLLECTION_XDO. (Details on detecting and handling all types explained in the SItemRetrievalICM sample.)
Depending on the XDO classification (not to be confused with item type classification) of the document part item type (see SItemTypeCreationICM API education sample for details), the actual resource item or part instances are a subclass of DKDDO. All parts and resource items are typically instances of the DKLobICM subclass of DKDDO (but you should cast by XDO type or by part type that your application is familiar with). All predefined XDO classes that support resource content are instances of DKLobICM or subclassed extensions of DKLobICM. Depending on the XDO classification, part types and resource items are instances of DKLobICM (for LOB), DKTextICM (for TEXT), DKImageICM (for IMAGE), DKStreamICM (for STREAM), DKVideoStreamICM (for VIDEO STREAM), or other subclasses for any application defined and implemented XDO Classes and part-classified item type definitions.
You can programmatically determine which subclass to cast to based on XDO classification. For all predefined XDO classifications, you could assume a DKLobICM instance at a minimum that you could cast to. The safest programmatic solution is to assume a DKDDO instance at a minimum for all item types. As a DKDDO, look up the "object type",
ddo.getObjectType()
or
ddo.getPidObject().getObjectType()
. Using the "object type", look up the
item type view definition, DKItemTypeViewDefICM itemTypeViewDef = ((DKDatstoreDefICM)ddo.getDatastore().datastoreDef()).retrieveItemTypeView(objectType);
.
Resource content is limited to item types with classifications
"resource" or "document part" (DKConstantICM.DK_ICM_ITEMTYPE_CLASS_RESOURCE_ITEM
or DK_ICM_ITEMTYPE_CLASS_DOC_PART) which you can detect using
DKItemTypeViewDefICM::getClassification(). All part item types always
have item type classification "document part" (DK_ICM_ITEMTYPE_CLASS_DOC_PART).
Only root components and document parts have resource content and therefore
only these are subclassed to the DKLobICM interface. Next, use the
DKItemTypeViewDefICM::getXDOClassID() or getXDOClassName() methods and
compare value to DKConstantICM.DK_ICM_XDO_<XDO type>_CLASS_ID or
DKConstantICM.DK_ICM_XDO_<XDO type>_CLASS_NAME (all constant values detailed
in sample SItemTypeCreationICM documentation which help you know which further
subclasses you can cast down to (more on class hierarchy in the SResourceItemCreationICM
sample). By default, definitions are cached in memory and do not require
additional server calls to perform this check. In C++, definitions are copied
to protect memory management, therefore you should still minimize memory usage
where possible.
For examples and details accessing parts, refer to the SDocModelItemICM API education samples.
BEHAVIOR NOTES
If the item types of the DDOs selected are not "document" classified, or if no part types are selected in the item type (item type relations), or if a document happens to have no children, the call returns without error. No exceptions are thrown.
When using the DKRetrieveOptionsICM interface, the parts are never listed unless requested. Under the old bitwise 'int' retrieve options or default if no options specified, if you used single-item retrieve (DKDDO.retrieve(), DKLobICM.retrieve(), or DKDatastoreICM.retrieveObject(dkDataObject)), parts were always listed and parts attributes & properties retrieved (but no parts resource content) unless you specified DKConstant.DK_CM_CONTENT_ATTRONLY. For compatibility with existing applications, if you use the old bitwise 'int' options or rely on defaults, parts are always listed (and parts attributes and properties retrieved) unless you used option DKConstant.DK_CM_CONTENT_ATTRONLY, the only option that excluded parts listing when using single-item retrieve. Multi-item retrieve and query operations are not affected (they do not automatically include parts listing or parts attributes & properties by default). In all cases, if you use a DKRetrieveOptionsICM interface with your retrieve request, the partsList(false) and partsAttributes(false) settings are honored and parts lists and attributes are not retrieved unless you specifically requested them.
When using the DKRetrieveOptionsICM interface to pass options, retrieve omits the useless, empty, special child collection named "ICMParts1006" (or any with similar names) for special system child component types that can appear in "document" classified item types. When using the old bitwise 'int' retrieve options (or defaults if no options specified), a special (but useless) child collection with a name similar to "ICMParts10__" might be added in many cases and should be ignored (do not use). For more information on the "ICMParts10__" child collection, see the "BEHAVIOR NOTES" section of DKRetrieveOptionsICM::childListOneLevel(boolean).
When using the DKRetrieveOptionsICM interface to pass options, the listed part DDOs contain only the essential PID information for subsequent retrieve requests on the part DDOs. No additional attributes or properties are populated. Note that when using bitwise 'int' retrieve option DKConstant.DK_CM_CONTENT_YES with multi-item retrieve (DKDatastoreICM::retrieveObjects(dkCollection)) or query (DKDatastoreICM::evaluate() or execute()), the parts are listed, but the part DDOs have all attributes initialized, but not set to their accurate values. The ACL Name and Semantic Type properties are added to the DKDDO, but they are simply initialized, but the values are incorrect. Subsequent retrieve requests for attributes refresh the DDOs with the correct values. When using DKRetrieveOptionsICM options the part DDOs are not initialized beyond the PID and no inaccurate values are set.
Parameters:
partsListRequested
- If 'true', you request listing document parts any directly selected DDO that happens to be of a "document" classified item type. If 'false', you do not request listing document parts.
partsList
- public boolean partsList()
See DKRetrieveOptionsICM::partsList(boolean partListRequested)
partsAttributes
- public void partsAttributes(boolean partsAttributesRequested)
Request user and system attributes for document parts retrieved under
the directly selected component DDOs if the "parts list / TOC"
options are requested. The "parts list" option (partsList()
retrieves only blank DDOs with completed PID information. This option
populates those DDOs with attributes. Furthermore, system-attributes
that for resource content are retrieved in this call which can save
a separate call to retrieve resource meta information if needed later.
This setting relies on partsList() requests. First review DKRetrieveOptionsICM::partsList(boolean partsListRequested).
This option only applies to document parts indirectly retrieved through the parts list retrieve option and populated within the directly selected DDOs. This does not retrieve any attributes for DDOs directly specified in a list of DDOs to retrieve, even if one of the directly selected DDOs happens to be a document part. Use baseAttributes() to request attributes on directly selected DDOs. Furthermore, this option does not request attributes for linked items, folder contents, or otherwise referenced components that are not retrieved as parts through the "parts list" retrieve options.
This option is also responsible for loading values for resource content system attributes accessed through the DKLobICM interface for document parts listed under directly selected parent documents (root components of "document"-classified item types) by the partsList(boolean) option that support resource content. For example, this setting loads the mime type, original file name, and content size that can be accessed through the DKLobICM interface (more details in the "DATA STRUCTURES" section). Note that this setting does not load such data for directly selected document parts or resource items submitted directly to retrieve. Use baseAttributes(boolean) to load such data for directly selected document parts.
DEFAULT: false
PRECEDENCE
This setting applies only to parts listed through a parts list request in the same retrieve call. If you already retrieved or listed the parts and want to simply retrieve attributes for the parts, submit the parts directly to retrieve through multi-item retrieve (DKDatastoreICM::retrieveObjects(dkCollection,DKNVPair[])). For directly-selected DDOs (including any parts directly submitted to retrieve), use the baseAttributes(boolean) setting to retrieve attributes.
This setting depends on the parts list retrieve options which controls population of the parts collection and parts DDOs. Parts attributes are populated only for parts listed. If no parts are listed, there are no parts for which to retrieve attributes. For example, if partsList(false), then there are no parts for which attributes can be retrieved.
If partsAttributes(true) and partsList(false), DKUsageError with error ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) is thrown (appended with text describing the offending options).
PERFORMANCE
Retrieving the attributes of parts already included through the partsList() setting costs some additional processing, network traffic, and memory to store the attributes retrieved. However, this operation is combined with normal children retrieval and is supported under multi-item retrieve performance. The performance of this operation is very similar to simply retrieving child attributes for one more child component type. As a general rule, you should retrieve only the data you need. Omitting the parts list is equivalent to specifying attribute filters (Projection List) and filtering out user-defined attributes for one child component type.
If there happen to be zero parts found by the partsList(true) request, there is no cost to for partsAttributes(true) since no additional requests are attempted if no parts are found.
DATA STRUCTURES
First, the DKDDO instances affected are only those populated in parts collections by the DKRetrieveOptionsICM::partsList(boolean) request.
See "DATA STRUCTURES" section for method DKRetrieveOptionsICM::partsList(boolean partsListRequested).
The same data structures apply as described in DKRetrieveOptionsICM::baseAttributes(boolean baseAttributesRequested), except that the DKDDO instances affected are those populated in parts collections, as described in DKRetrieveOptionsICM::partsList(boolean partsListRequested).
See "DATA STRUCTURES" section for method DKRetrieveOptionsICM::baseAttributes(boolean baseAttributesRequested).
BEHAVIOR NOTES
If the item types of the DDOs selected are not "document" classified, or if no part types are selected in the item type (item type relations), or if a document happens to have no children, the call returns without error. No exceptions are thrown.
When using the DKRetrieveOptionsICM interface, the parts are never listed unless requested. Under the old bitwise 'int' retrieve options or default if no options specified, if you used single-item retrieve (DKDDO.retrieve(), DKLobICM.retrieve(), or DKDatastoreICM.retrieveObject(dkDataObject)), parts were always listed and parts attributes & properties retrieved (but no parts resource content) unless you specified DKConstant.DK_CM_CONTENT_ATTRONLY. For compatibility with existing applications, if you use the old bitwise 'int' options or rely on defaults, parts are always listed (and parts attributes and properties retrieved) unless you used option DKConstant.DK_CM_CONTENT_ATTRONLY, the only option that excluded parts listing when using single-item retrieve. Multi-item retrieve and query operations are not affected (they do not automatically include parts listing or parts attributes & properties by default). In all cases, if you use a DKRetrieveOptionsICM interface with your retrieve request, the partsList(false) and partsAttributes(false) settings are honored and parts lists and attributes are not retrieved unless you specifically requested them.
When parts attributes are requested through DKRetrieveOptionsICM, multi-item retrieve is used to optimize all parts listed through the partsList(true) request for all documents submitted to retrieve. Retrieving parts attributes for each part is optimized by retrieving all in one call (or a minimal number of calls in batches of an optimized maximum size). However, using the older bitwise 'int' retrieve options (or defaults if no options specified), when parts are retrieved, parts attributes are retrieved on a per-part basis, with one call per document part to retrieve attributes. Parts attributes are not optimized through the older bitwise 'int' retrieve options (or defaults).
This setting relies on partsList() requests. First review DKRetrieveOptionsICM::partsList(boolean partsListRequested).
This option only applies to document parts indirectly retrieved through the parts list retrieve option and populated within the directly selected DDOs. This does not retrieve any attributes for DDOs directly specified in a list of DDOs to retrieve, even if one of the directly selected DDOs happens to be a document part. Use baseAttributes() to request attributes on directly selected DDOs. Furthermore, this option does not request attributes for linked items, folder contents, or otherwise referenced components that are not retrieved as parts through the "parts list" retrieve options.
This option is also responsible for loading values for resource content system attributes accessed through the DKLobICM interface for document parts listed under directly selected parent documents (root components of "document"-classified item types) by the partsList(boolean) option that support resource content. For example, this setting loads the mime type, original file name, and content size that can be accessed through the DKLobICM interface (more details in the "DATA STRUCTURES" section). Note that this setting does not load such data for directly selected document parts or resource items submitted directly to retrieve. Use baseAttributes(boolean) to load such data for directly selected document parts.
DEFAULT: false
PRECEDENCE
This setting applies only to parts listed through a parts list request in the same retrieve call. If you already retrieved or listed the parts and want to simply retrieve attributes for the parts, submit the parts directly to retrieve through multi-item retrieve (DKDatastoreICM::retrieveObjects(dkCollection,DKNVPair[])). For directly-selected DDOs (including any parts directly submitted to retrieve), use the baseAttributes(boolean) setting to retrieve attributes.
This setting depends on the parts list retrieve options which controls population of the parts collection and parts DDOs. Parts attributes are populated only for parts listed. If no parts are listed, there are no parts for which to retrieve attributes. For example, if partsList(false), then there are no parts for which attributes can be retrieved.
If partsAttributes(true) and partsList(false), DKUsageError with error ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) is thrown (appended with text describing the offending options).
PERFORMANCE
Retrieving the attributes of parts already included through the partsList() setting costs some additional processing, network traffic, and memory to store the attributes retrieved. However, this operation is combined with normal children retrieval and is supported under multi-item retrieve performance. The performance of this operation is very similar to simply retrieving child attributes for one more child component type. As a general rule, you should retrieve only the data you need. Omitting the parts list is equivalent to specifying attribute filters (Projection List) and filtering out user-defined attributes for one child component type.
If there happen to be zero parts found by the partsList(true) request, there is no cost to for partsAttributes(true) since no additional requests are attempted if no parts are found.
DATA STRUCTURES
First, the DKDDO instances affected are only those populated in parts collections by the DKRetrieveOptionsICM::partsList(boolean) request.
See "DATA STRUCTURES" section for method DKRetrieveOptionsICM::partsList(boolean partsListRequested).
The same data structures apply as described in DKRetrieveOptionsICM::baseAttributes(boolean baseAttributesRequested), except that the DKDDO instances affected are those populated in parts collections, as described in DKRetrieveOptionsICM::partsList(boolean partsListRequested).
See "DATA STRUCTURES" section for method DKRetrieveOptionsICM::baseAttributes(boolean baseAttributesRequested).
BEHAVIOR NOTES
If the item types of the DDOs selected are not "document" classified, or if no part types are selected in the item type (item type relations), or if a document happens to have no children, the call returns without error. No exceptions are thrown.
When using the DKRetrieveOptionsICM interface, the parts are never listed unless requested. Under the old bitwise 'int' retrieve options or default if no options specified, if you used single-item retrieve (DKDDO.retrieve(), DKLobICM.retrieve(), or DKDatastoreICM.retrieveObject(dkDataObject)), parts were always listed and parts attributes & properties retrieved (but no parts resource content) unless you specified DKConstant.DK_CM_CONTENT_ATTRONLY. For compatibility with existing applications, if you use the old bitwise 'int' options or rely on defaults, parts are always listed (and parts attributes and properties retrieved) unless you used option DKConstant.DK_CM_CONTENT_ATTRONLY, the only option that excluded parts listing when using single-item retrieve. Multi-item retrieve and query operations are not affected (they do not automatically include parts listing or parts attributes & properties by default). In all cases, if you use a DKRetrieveOptionsICM interface with your retrieve request, the partsList(false) and partsAttributes(false) settings are honored and parts lists and attributes are not retrieved unless you specifically requested them.
When parts attributes are requested through DKRetrieveOptionsICM, multi-item retrieve is used to optimize all parts listed through the partsList(true) request for all documents submitted to retrieve. Retrieving parts attributes for each part is optimized by retrieving all in one call (or a minimal number of calls in batches of an optimized maximum size). However, using the older bitwise 'int' retrieve options (or defaults if no options specified), when parts are retrieved, parts attributes are retrieved on a per-part basis, with one call per document part to retrieve attributes. Parts attributes are not optimized through the older bitwise 'int' retrieve options (or defaults).
Parameters:
partsAttributesRequested
- If 'true', you request user and system attributes for document parts listed by other parts list requests. If 'false', you do not request attributes to be populated in document parts of directly selected DDOs (if parts list requested).
partsAttributes
- public boolean partsAttributes( )
See DKRetrieveOptionsICM::partsAttributes(boolean partAttributesRequested)
partsPropertyAclName
- public void partsPropertyAclName( boolean partsPropertyAclNameRequested)
Retrieve the ACL Name property / system-attribute for any document
part listed under parent documents directly-selected for retrieval
and listed through the from a request to partsList(true).
This setting specifically controls whether the following DDO property is populated in the document parts within the DKParts collections under the directly-selected DDOs:
This setting only populates the ACL Name property in document parts that are listed when you request DKRetrieveOptionsICM::partsList(true) for directly-selected "document"-classified itemtypes that have non-zero document parts counts. This setting has no effect over any directly-selected components in your collection submitted to retrieve, regardless of whether they happen to be document parts. For all directly-selected components (regardless of whether document parts or not), the ACL Name property must be requested through base attribute and property settings, such as basePropertyAclName(boolean).
"Core" properties of parts that are persisted just like attributes in the same table are automatically included with the partsAttributes(boolean partsAttributesRequested) setting if set to true. The ACL Name property is not included by default both because it is typically infrequently used by applications and it requires additional overhead processing the value, including a measurable definition lookup that incurs a measurable performance hit if that definition set had not yet been cached (such as ACL name).
Depending on your access control configuration and data model, access might not be controlled by the parts ACL. It could instead be controlled by the parent document's ACL, item type ACL, system ACL, or perhaps other ACLs (if any). Request the document parts ACL properties only if you plan on using it. Note that you do not need to retrieve it for it to be enforced.
DEFAULT: false
PRECEDENCE
This setting only applies if partsList(true) and operates independently from any partsAttributes(boolean) setting. You can request the parts ACL Name property independently from the partsAttributes(boolean) setting. However, this setting can only populate the ACL Name property in parts listed by a partsList(true) request in the same retrieve call. If you have already retrieved the parts list, you can submit the parts directly to multi-item retrieve (DKDatastoreICM::retrieveObjects(dkCollection,DKNVPair[]) and request basePropertyAclName(true) instead.
If partsList(false) and partsPropertyAclName(true), DKUsageError with error ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) is thrown (appended with text describing the offending options).
PERFORMANCE
If also requested partsAttributes(true) or resourceContent(true), a small, but measurable ACL name lookup is required to populate the ACL name from an ACL code. If the ACL names have not yet been accessed and cached, this lookup can be more noticeable. Since this is typically not used all the time by applications, it is better to omit this property unless you have plans to use it. This is the primary purpose for why the ACL Name property request is separated from the parts attributes request.
If you partsAttributes(false) and resourceContent(false), then the partsPropertyAclName(true) request costs measurably more than the difference on top of processing had you already chosen partsAttributes(true) or resourceContent(true). The cost to retrieve the ACL name alone in many cases should be slightly less than partsAttributes(true), unless the ACL names have not yet been accessed and cached, which could take longer than a partsAttributes(true) request on its own. Typically (especially for all pre-defined part types), document parts have only system attributes/properties and perhaps a few user attributes (if any). Under typical cases, partsPropertyAclName(true) might overlap with most of the partsAttributes(true) processing, saving only a small amount of memory and processing if partsAttributes(false). Setting partsAttributes(false), partsPropertyAclName(false), and partsResourceContent(false) is much faster.
If there happen to be zero parts found by the partsList(true) request, there is no cost to for partsPropertyAclName(true) since no additional requests are attempted if no parts are found.
DATA STRUCTURES
First, the DKDDO instances affected are only those populated in parts collections by the DKRetrieveOptionsICM::partsList(boolean) request.
See "DATA STRUCTURES" section for method DKRetrieveOptionsICM::partsList(boolean partsListRequested).
The same data structures apply as described in DKRetrieveOptionsICM::basePropertyAclName(boolean basePropertyAclNameRequested), except that the DKDDO instances affected are those populated in parts collections, as described in DKRetrieveOptionsICM::partsList(boolean partsListRequested).
See "DATA STRUCTURES" section for method DKRetrieveOptionsICM::baseAttributes(boolean baseAttributesRequested).
BEHAVIOR NOTES
The behavior when not requested varies from the behavior when the old bitwise 'int' retrieve options were used. When partsPropertyAclName(false), the parts ACL Name property will not be retrieved. Under the older bitwise 'int' options, the option DKConstant.DK_CM_CONTENT_RETRIEVE_IGNORE_ACL_NAME (65536) had no effect on parts attributes and instead only controlled the ACL Name for directly-selected DDOs, not parts retrieved under documents.
This setting specifically controls whether the following DDO property is populated in the document parts within the DKParts collections under the directly-selected DDOs:
- DKConstantICM.DK_ICM_PROPERTY_ACL (
"SYSROOTATTRS.ACLCODE"
) = <String
> - ACL Name (not code) governing access to this item.
This setting only populates the ACL Name property in document parts that are listed when you request DKRetrieveOptionsICM::partsList(true) for directly-selected "document"-classified itemtypes that have non-zero document parts counts. This setting has no effect over any directly-selected components in your collection submitted to retrieve, regardless of whether they happen to be document parts. For all directly-selected components (regardless of whether document parts or not), the ACL Name property must be requested through base attribute and property settings, such as basePropertyAclName(boolean).
"Core" properties of parts that are persisted just like attributes in the same table are automatically included with the partsAttributes(boolean partsAttributesRequested) setting if set to true. The ACL Name property is not included by default both because it is typically infrequently used by applications and it requires additional overhead processing the value, including a measurable definition lookup that incurs a measurable performance hit if that definition set had not yet been cached (such as ACL name).
Depending on your access control configuration and data model, access might not be controlled by the parts ACL. It could instead be controlled by the parent document's ACL, item type ACL, system ACL, or perhaps other ACLs (if any). Request the document parts ACL properties only if you plan on using it. Note that you do not need to retrieve it for it to be enforced.
DEFAULT: false
PRECEDENCE
This setting only applies if partsList(true) and operates independently from any partsAttributes(boolean) setting. You can request the parts ACL Name property independently from the partsAttributes(boolean) setting. However, this setting can only populate the ACL Name property in parts listed by a partsList(true) request in the same retrieve call. If you have already retrieved the parts list, you can submit the parts directly to multi-item retrieve (DKDatastoreICM::retrieveObjects(dkCollection,DKNVPair[]) and request basePropertyAclName(true) instead.
If partsList(false) and partsPropertyAclName(true), DKUsageError with error ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) is thrown (appended with text describing the offending options).
PERFORMANCE
If also requested partsAttributes(true) or resourceContent(true), a small, but measurable ACL name lookup is required to populate the ACL name from an ACL code. If the ACL names have not yet been accessed and cached, this lookup can be more noticeable. Since this is typically not used all the time by applications, it is better to omit this property unless you have plans to use it. This is the primary purpose for why the ACL Name property request is separated from the parts attributes request.
If you partsAttributes(false) and resourceContent(false), then the partsPropertyAclName(true) request costs measurably more than the difference on top of processing had you already chosen partsAttributes(true) or resourceContent(true). The cost to retrieve the ACL name alone in many cases should be slightly less than partsAttributes(true), unless the ACL names have not yet been accessed and cached, which could take longer than a partsAttributes(true) request on its own. Typically (especially for all pre-defined part types), document parts have only system attributes/properties and perhaps a few user attributes (if any). Under typical cases, partsPropertyAclName(true) might overlap with most of the partsAttributes(true) processing, saving only a small amount of memory and processing if partsAttributes(false). Setting partsAttributes(false), partsPropertyAclName(false), and partsResourceContent(false) is much faster.
If there happen to be zero parts found by the partsList(true) request, there is no cost to for partsPropertyAclName(true) since no additional requests are attempted if no parts are found.
DATA STRUCTURES
First, the DKDDO instances affected are only those populated in parts collections by the DKRetrieveOptionsICM::partsList(boolean) request.
See "DATA STRUCTURES" section for method DKRetrieveOptionsICM::partsList(boolean partsListRequested).
The same data structures apply as described in DKRetrieveOptionsICM::basePropertyAclName(boolean basePropertyAclNameRequested), except that the DKDDO instances affected are those populated in parts collections, as described in DKRetrieveOptionsICM::partsList(boolean partsListRequested).
See "DATA STRUCTURES" section for method DKRetrieveOptionsICM::baseAttributes(boolean baseAttributesRequested).
BEHAVIOR NOTES
The behavior when not requested varies from the behavior when the old bitwise 'int' retrieve options were used. When partsPropertyAclName(false), the parts ACL Name property will not be retrieved. Under the older bitwise 'int' options, the option DKConstant.DK_CM_CONTENT_RETRIEVE_IGNORE_ACL_NAME (65536) had no effect on parts attributes and instead only controlled the ACL Name for directly-selected DDOs, not parts retrieved under documents.
Parameters:
partsPropertyAclNameRequested
- If 'true', you request the ACL Name property to be populated in any parts listed through the partsList() setting. If 'false', you do not request this property in the parts listed.
partsPropertyAclName
- public boolean partsPropertyAclName( )
See DKRetrieveOptionsICM::partsPropertyAclName(boolean partsPropertyAclNameRequested).
resourceContent
- public void resourceContent(boolean resourceContentRequested)
[Single-Item Retrieve Only]
Request resource content for any resource items and document parts
(including parts listed through partsList(boolean) for any
directly-selected parent documents. Resource content is
available on "resource" and "part" classified item types through the
Resource content can only be requested when using single-item retrieve (
See section "PERFORMANCE" for further explanation and section "BEHAVIOR NOTES" for details on exception thrown.
This setting does include resource content for any DDO directly selected that happens to be of "resource" or "part" classified item types. Also included are document parts listed through the DKRetrieveOptionsICM::partsList(boolean partListRequested) retrieve option that are populated under their directly selected parent DDOs in DKParts collections.
Item types are defined with one of four possible classifications, Standard/Non-Resource, Resource, Document, and Part. "resource" and "part" types have resource content, both of which are nearly identical in functionality and interface, except that resource items are standalone items with one resource content stored in the root component while documents from "document" classified item types can contain essentially a collection of resource items (called parts in this case) that are managed through the parent document.
There are many ways to set and retrieve content, including direct to/from local files, input streams, binary arrays in memory, third party FTP servers synchronously and asynchronously, or even read resource content through a URL. Various location-specific retrieve methods on the
Some examples of location-specific retrieve methods include:
Some examples of default in-memory retrieve methods include:
More details on how to detect subclasses such as
DEFAULT: false
PRECEDENCE
This setting is independent of other options for retrieving resource content into directly selected DDOs, with two exceptions.
If a projection list (DKProjectionListICM) is specified (through DKRetrieveOptionsICM::attributeFilters(DKProjectionListICM)) and if the projection list omits projections for directly-selected base DDOs, DDOs of that type are not retrieved, no existence check is performed, and no parts are listed for DDOs of that type. (Note if children are requested, exist, and are not filtered out by omitted projections, those particular items are considered validated and parts can be listed. No exception is thrown as a result of resource content not retrieved for directly-selected DDOs filtered out as a result of projection lists.
However, omitting projections for resource items and document parts directly submitted to retrieve (not applicable to those retrieved through partsList(true) requests) is currently not allowed in order to ensure it is consistently supported through all possible retrieve interfaces. You can still use attribute filters when using resourceContent(true) requests, however, you cannot omit projections for "resource" or "part" classified item type DDOs that you submit directly to retrieve. You can still omit child types and other item type classifications. If you submit DDOs to retrieve, request resourceContent(true), and request attributeFilters(DKProjectionListICM) that are not 'null', and if any of your "resource" or "part" classified DDOs do not have a corresponding projection (after expanding general or wildcard projections), a DKUsageError is thrown with ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) and appended with details of the disallowed options and projections combination.
If you wish to retrieve resource content into memory for document parts listed under directly selected DDOs through the partsList(boolean partsListRequested) option, then partsList(true) is required, otherwise if partsList(false) there are not parts listed under the parents to retrieve resource content into. If no resource items or parts happen to appear in the directly selected DDOs and if no document-classified items are directly selected or if partsList(false), then this setting has no effect.
Although you do not need to request baseAttributes(true) when requesting resourceContent(true), If you choose to specify attribute filters (projection list), you must not omit system attributes from any projection for root component type views of "resource" or "document part" classified item types. You can use projection lists, however simply be sure to include the
If there are no applicable resource items or document parts, this setting has no effect.
If a resource content-specific retrieve method is used that implicitly implies that resource content is desired, you must request resource content. Supplying
PERFORMANCE
Minimize requests to requesting resourceContent(true) unless you need the content at this time and plan on using it. Retrieving resource content can be very expensive and should be limited to only when needed. Consider deferring retrieving resource content until actually needed and only for the items or document parts need. For example, if performing a query and displaying results to the user, typically you should not request resource content. Then, perhaps when a user selects one of the results to view, retrieve the resource content for the single item when requested. Requesting resource content can result in multiple additional calls and with significant I/O and memory considerations.
Resource content should be limited to a single-item basis (
If no directly selected DDOs have a resource content interface (no resource items or document parts directly-selected) and none can have document parts (root components of "document"-classified item types) or DKRetrieveOptionsICM::partsList(false)), then no resource content is attempted and no measurable cost is incurred (perhaps except for an existence check if nothing else requested).
However, if there are any "resource" or "part" classified items directly selected or if "document" classified items exist and partsList(true), then additional processing is incurred.
If no attributes for the applicable DKDDOs are yet retrieved, the server is called to gather resource content information (system attributes) before accessing the binary content. If you include base attributes or parts attributes (if parts list requested) for the applicable DKDDOs, no additional calls are needed. If you previously retrieved attributes for the applicable DKDDOs that you are now re-retrieving, this time for resource content, the resource content information (system attributes) are refreshed (re-retrieved) with a separate call to the library server in case the resource content has changed. If you are certain that the resource content has not changed, you should use a behavior optimization request skipping refresh (re-retrieve) of resource content meta-data system attributes if already retrieved previously if resource content was requested. Use behaviorSkipResourceAttrRefresh(boolean).
See DKRetrieveOptionsICM::behaviorSkipResourceAttrRefresh(boolean)
Retrieving the resource content-related system-attributes is optimized through multi-item retrieve for both directly-selected DDOs and any parts listed through the partsList(true) setting. Although any additional calls are measurable, the number of calls is minimized gathering multiple resource items into one call. However, the system-attributes for directly-selected DDOs are retrieved separately from the system attributed needed from any document parts listed through the partsList(true) setting. Both independently utilize multi-item retrieve to optimize, but cannot be optimized together into a single call. Therefore, at a minimum, one call is needed for the system-attributes for all directly-selected DDO resource items and documents parts and another call is needed for the system-attributes for all parts listed through partsList(true). If large numbers exist, multi-item retrieve might make additional calls optimized in batches up to a maximum optimized size. However, the necessary system-attributes for resource content are included with any baseAttributes(true) or partsAttributes(true) requests and if either baseAttributes(true) or partsAttributes(true), no separate calls are made for each respectively.
Finally, the content is streamed from the object server into local memory on a per-object basis as a result of this call (unless the object size for any individual object is zero bytes). For each resource content object (for each directly selected resource item and document part as well as for each part listed by a partsList(true)), separate calls are made specifically for the resource content unless that size for any given object is currently zero-bytes according to the system attributes. Multiple calls can be very expensive. You should minimize the number of calls (and the amount of data transferred per call). For example, if you were retrieving a resource item, on top of any other data you requested through other options, if it has a non-zero content size, retrieving the content into memory requires one additional, but expensive call due to potentially significant I/O and memory needs. Similarly (if multi-item retrieve supported resource content requests), if you were to retrieve such 100 resource items and request resource content, if all have non-zero content sizes, on top of any other data you requested, content retrieval would require 100 object server calls with potentially significant I/O and memory implications. If you were retrieving a document with partsList(true) and suppose each document had 3 parts each with non-zero content, then 3 additional calls could be made with potentially significant I/O and memory needs. Similarly (if multi-item retrieve supported resource content requests), if you had 100 of these documents, 300 additional potential I/O & memory intensive calls would be made if you requested resource content.
Additionally, streaming large objects across the network and storing all the binary data in memory has significant performance implications to consider. Retrieving resource content for multiple items can require significant network time and local memory to store the binary data for all objects. Resource content should only be retrieved if and when actually needed. Typically, resource content should be accessed only when a user selects an item or document to view. Again, applications typically should only request resource content when using single-item retrieve.
DATA STRUCTURES
Resource content is stored directly in the DKLobICM subclass of DKDDO. All resource items and document parts are actually instances of DKLobICM or further subclass. The DKDDOs impacted are those directly selected that happen to be from "resource" or "part" classified itemtypes, or parts retrieved through the partsList(boolean partsListRequested) setting for any directly selected root component from a "document" classified item type. See DKRetrieveOptionsICM::partsList(boolean partListRequested) for data structures under documents.
Depending on the XDO classification (not to be confused with item type classification) of the item type (see SItemTypeCreationICM API education sample for details), the actual resource item or part instances are a subclass of DKDDO. All parts and resource items are typically instances of the DKLobICM subclass of DKDDO (but you should cast by XDO type or by part type that your application is familiar with). All predefined XDO classes that support resource content are instances of DKLobICM or subclassed extensions of DKLobICM. Depending on the XDO classification, part types and resource items are instances of DKLobICM (for LOB), DKTextICM (for TEXT), DKImageICM (for IMAGE), DKStreamICM (for STREAM), DKVideoStreamICM (for VIDEO STREAM), or other subclasses for any application defined and implemented XDO Classes and part-classified item type definitions.
You can programmatically determine which subclass to cast to based on XDO classification. Assume a DKDDO instance at a minimum for all item types. As a DKDDO, look up the "object type",
To access content loaded in memory, use the DKLobICM.setContent()/getContent() interfaces. Additionally you can write from memory to file and read from file into memory using DKLobiCM.setContentToClientFile()/getContentFromClientFile(). Remember that there are many ways to set and retrieve content described earlier. This section describes working with the in-memory retrieval.
For more information and interfaces accessing content, refer to the SResourceItemCreationICM and SResourceItemRetrievalICM API education samples as well as the Application Programming Reference for the DKLobICM interface (and other subclass interfaces).
BEHAVIOR NOTES
If DKRetrieveOptionsICM.resourceContent(true) attempted with any multi-item retrieve function (directly or indirectly such as through query), the following exception is thrown.
DKMessageId.DK_CM_MSG_BADOPTVALUE
DKUsageError with ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) if multi-item retrieve disallows any particular retrieve option request. The message text is appended with error message from ID DKMessageId.DK_CM_MSG_FUNCTION_NOTSUPP (DGL0482A) and appended with the offending method and option value. The following are invalid function + option combinations that are not supported.
If using the older bitwise 'int' retrieve options (or defaults if no options specified), multi-item retrieve simply ignored any request for content (such as through option DKConstant.DK_CM_CONTENT_YES) and no exception was thrown.
DKLobICM
interface (subclass of DKDDO
).
Resource content can only be requested when using single-item retrieve (
DKLobICM.retrieve(...)
, DKDDO.retrieve(...)
,
and DKDatastoreICM.retrieveObject(dkDataObject,DKNVPair[]w/DKRetrieveOptionsICM)
).
For reasons explained in detail in the "PERFORMANCE" section below,
you cannot request resource content when using multi-item retrieve
(DKDatastoreICM::retrieveObjects(dkCollection,DKNVPair[])
or indirectly through query / DKDatstoreICM.evaluate() or execute()
)
or an exception is thrown when the option is detected by multi-item
retrieve.
See section "PERFORMANCE" for further explanation and section "BEHAVIOR NOTES" for details on exception thrown.
This setting does include resource content for any DDO directly selected that happens to be of "resource" or "part" classified item types. Also included are document parts listed through the DKRetrieveOptionsICM::partsList(boolean partListRequested) retrieve option that are populated under their directly selected parent DDOs in DKParts collections.
Item types are defined with one of four possible classifications, Standard/Non-Resource, Resource, Document, and Part. "resource" and "part" types have resource content, both of which are nearly identical in functionality and interface, except that resource items are standalone items with one resource content stored in the root component while documents from "document" classified item types can contain essentially a collection of resource items (called parts in this case) that are managed through the parent document.
There are many ways to set and retrieve content, including direct to/from local files, input streams, binary arrays in memory, third party FTP servers synchronously and asynchronously, or even read resource content through a URL. Various location-specific retrieve methods on the
DKLobICM
subclass of DKDDO
(or further subclasses) determine the means through which resource
content is returned. By default, resource content is loaded into
memory if no other location-specific retrieve method is used.
Some examples of location-specific retrieve methods include:
DKLobICM.getInputStream(DKNVPair options, int offset, int length)
DKLobICM.retrieve(String targetLocalFileName, DKNVPair[] options)
DKLobICM.retrieve(DKThirdPartyServerDef, DKNVPair[] options)
Some examples of default in-memory retrieve methods include:
DKLobICM.retrieve(DKNVPair[] options)
DKKDDO.retrieve(DKNVPair[] options)
DKDatastoreICM.retrieveObject(DKDDO,DKNVPair[] options)
More details on how to detect subclasses such as
DKLobICM
is
provided in the "DATA STRUCTURES" section below. For more
information on other interfaces, refer to the SResourceItemCreationICM,
SResourceItemRetrievalICM, SResourceItem3rdPartyIngest,
SResourceItem3rdPartyRetrieve, and SDocModelItemICM API education samples
as well as the Application Programming Reference for the
DKLobICM
interface (and other subclasses of
DKLobICM
).
DEFAULT: false
PRECEDENCE
This setting is independent of other options for retrieving resource content into directly selected DDOs, with two exceptions.
If a projection list (DKProjectionListICM) is specified (through DKRetrieveOptionsICM::attributeFilters(DKProjectionListICM)) and if the projection list omits projections for directly-selected base DDOs, DDOs of that type are not retrieved, no existence check is performed, and no parts are listed for DDOs of that type. (Note if children are requested, exist, and are not filtered out by omitted projections, those particular items are considered validated and parts can be listed. No exception is thrown as a result of resource content not retrieved for directly-selected DDOs filtered out as a result of projection lists.
However, omitting projections for resource items and document parts directly submitted to retrieve (not applicable to those retrieved through partsList(true) requests) is currently not allowed in order to ensure it is consistently supported through all possible retrieve interfaces. You can still use attribute filters when using resourceContent(true) requests, however, you cannot omit projections for "resource" or "part" classified item type DDOs that you submit directly to retrieve. You can still omit child types and other item type classifications. If you submit DDOs to retrieve, request resourceContent(true), and request attributeFilters(DKProjectionListICM) that are not 'null', and if any of your "resource" or "part" classified DDOs do not have a corresponding projection (after expanding general or wildcard projections), a DKUsageError is thrown with ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) and appended with details of the disallowed options and projections combination.
If you wish to retrieve resource content into memory for document parts listed under directly selected DDOs through the partsList(boolean partsListRequested) option, then partsList(true) is required, otherwise if partsList(false) there are not parts listed under the parents to retrieve resource content into. If no resource items or parts happen to appear in the directly selected DDOs and if no document-classified items are directly selected or if partsList(false), then this setting has no effect.
Although you do not need to request baseAttributes(true) when requesting resourceContent(true), If you choose to specify attribute filters (projection list), you must not omit system attributes from any projection for root component type views of "resource" or "document part" classified item types. You can use projection lists, however simply be sure to include the
DKConstantICM.DK_ICM_SYSTEM_ATTRS
keyword in any
projection for root components of "resource" or "document part"
classified item types when you request resourceContent(true).
Omitting the system attributes prevents the retrieve operation
from retrieving necessary system resource attributes. If blocked,
a DKUsageError exception with error ID
DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) is thrown appended with
the offending options. Additionally, if a general projection ("*")
is provided, it must not exclude system attributes when requesting
resourceContent(true) or the same exception is thrown. This ensures
consistent behavior for any call with the same options and filters.
If there are no applicable resource items or document parts, this setting has no effect.
If a resource content-specific retrieve method is used that implicitly implies that resource content is desired, you must request resource content. Supplying
DKRetrieveOptionsICM.resourceContent(false)
(excluding resource content) contradicts the intent implied by the choice
of method, such as by specifying partial content byte offsets and lengths
or specifying a target file name. When resource content is excluded
but a retrieve method is used that implies resource content is desired,
DKUsageError with error ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A)
is thrown (appended with text describing the offending options).
For example, if DKRetrieveOptionsICM.resourceContent(false)
is used with any of the following methods, this usage error is reported.
DKLobICM.getInputStream(DKNVPair options, int offset, int length)
DKLobICM.retrieve(String targetLocalFileName, DKNVPair[] options)
DKLobICM.retrieve(DKThirdPartyServerDef, DKNVPair[] options)
DKLobICM.retrieve(DKNVPair[] options,long offset,long length)
DKLobICM.retrieve(DKNVPair[] options,String targetLocalFileName,long offset,long length)
PERFORMANCE
Minimize requests to requesting resourceContent(true) unless you need the content at this time and plan on using it. Retrieving resource content can be very expensive and should be limited to only when needed. Consider deferring retrieving resource content until actually needed and only for the items or document parts need. For example, if performing a query and displaying results to the user, typically you should not request resource content. Then, perhaps when a user selects one of the results to view, retrieve the resource content for the single item when requested. Requesting resource content can result in multiple additional calls and with significant I/O and memory considerations.
Resource content should be limited to a single-item basis (
DKLobICM.retrieve(...)
, DKDDO.retrieve(...)
,
and DKDatastoreICM.retrieveObject(dkDataObject,DKNVPair[]w/DKRetrieveOptionsICM)
),
when you retrieve just one resource item or document (perhaps when
a user selects a document to view). Due to performance considerations
when using multi-item retrieve
(DKDatastoreICM::retrieveObjects(dkCollection,DKNVPair[])
or indirectly through query / DKDatstoreICM.evaluate() or execute()
),
the resourceContent(true)
request is not accepted by
multi-item retrieve and throws a exception to ensure understanding
of performance implications. If you must retrieve multiple items
with resource content at once, use single-item retrieve instead by
iterating over your collection. Any multi-item meta-data optimization
of using multi-item retrieve is usually inconsequential relative
the size of the server calls for the individual resource content objects
and their I/O and memory implications. The total cost should be
sufficiently similar (when resource content requested)
if you iterate over your own collection and call single-item retrieve
rather than multi-item retrieve. Note that under any other case
than when resource content requested, multi-item retrieve can include
significant savings and should be used. If multi-item retrieve is used
with resourceContent(true)
, a DKUsageError
is
thrown with error ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A)
and appended with offending function + option. See BEHAVIOR NOTES
for more details on exception.
If no directly selected DDOs have a resource content interface (no resource items or document parts directly-selected) and none can have document parts (root components of "document"-classified item types) or DKRetrieveOptionsICM::partsList(false)), then no resource content is attempted and no measurable cost is incurred (perhaps except for an existence check if nothing else requested).
However, if there are any "resource" or "part" classified items directly selected or if "document" classified items exist and partsList(true), then additional processing is incurred.
If no attributes for the applicable DKDDOs are yet retrieved, the server is called to gather resource content information (system attributes) before accessing the binary content. If you include base attributes or parts attributes (if parts list requested) for the applicable DKDDOs, no additional calls are needed. If you previously retrieved attributes for the applicable DKDDOs that you are now re-retrieving, this time for resource content, the resource content information (system attributes) are refreshed (re-retrieved) with a separate call to the library server in case the resource content has changed. If you are certain that the resource content has not changed, you should use a behavior optimization request skipping refresh (re-retrieve) of resource content meta-data system attributes if already retrieved previously if resource content was requested. Use behaviorSkipResourceAttrRefresh(boolean).
See DKRetrieveOptionsICM::behaviorSkipResourceAttrRefresh(boolean)
Retrieving the resource content-related system-attributes is optimized through multi-item retrieve for both directly-selected DDOs and any parts listed through the partsList(true) setting. Although any additional calls are measurable, the number of calls is minimized gathering multiple resource items into one call. However, the system-attributes for directly-selected DDOs are retrieved separately from the system attributed needed from any document parts listed through the partsList(true) setting. Both independently utilize multi-item retrieve to optimize, but cannot be optimized together into a single call. Therefore, at a minimum, one call is needed for the system-attributes for all directly-selected DDO resource items and documents parts and another call is needed for the system-attributes for all parts listed through partsList(true). If large numbers exist, multi-item retrieve might make additional calls optimized in batches up to a maximum optimized size. However, the necessary system-attributes for resource content are included with any baseAttributes(true) or partsAttributes(true) requests and if either baseAttributes(true) or partsAttributes(true), no separate calls are made for each respectively.
Finally, the content is streamed from the object server into local memory on a per-object basis as a result of this call (unless the object size for any individual object is zero bytes). For each resource content object (for each directly selected resource item and document part as well as for each part listed by a partsList(true)), separate calls are made specifically for the resource content unless that size for any given object is currently zero-bytes according to the system attributes. Multiple calls can be very expensive. You should minimize the number of calls (and the amount of data transferred per call). For example, if you were retrieving a resource item, on top of any other data you requested through other options, if it has a non-zero content size, retrieving the content into memory requires one additional, but expensive call due to potentially significant I/O and memory needs. Similarly (if multi-item retrieve supported resource content requests), if you were to retrieve such 100 resource items and request resource content, if all have non-zero content sizes, on top of any other data you requested, content retrieval would require 100 object server calls with potentially significant I/O and memory implications. If you were retrieving a document with partsList(true) and suppose each document had 3 parts each with non-zero content, then 3 additional calls could be made with potentially significant I/O and memory needs. Similarly (if multi-item retrieve supported resource content requests), if you had 100 of these documents, 300 additional potential I/O & memory intensive calls would be made if you requested resource content.
Additionally, streaming large objects across the network and storing all the binary data in memory has significant performance implications to consider. Retrieving resource content for multiple items can require significant network time and local memory to store the binary data for all objects. Resource content should only be retrieved if and when actually needed. Typically, resource content should be accessed only when a user selects an item or document to view. Again, applications typically should only request resource content when using single-item retrieve.
DATA STRUCTURES
Resource content is stored directly in the DKLobICM subclass of DKDDO. All resource items and document parts are actually instances of DKLobICM or further subclass. The DKDDOs impacted are those directly selected that happen to be from "resource" or "part" classified itemtypes, or parts retrieved through the partsList(boolean partsListRequested) setting for any directly selected root component from a "document" classified item type. See DKRetrieveOptionsICM::partsList(boolean partListRequested) for data structures under documents.
Depending on the XDO classification (not to be confused with item type classification) of the item type (see SItemTypeCreationICM API education sample for details), the actual resource item or part instances are a subclass of DKDDO. All parts and resource items are typically instances of the DKLobICM subclass of DKDDO (but you should cast by XDO type or by part type that your application is familiar with). All predefined XDO classes that support resource content are instances of DKLobICM or subclassed extensions of DKLobICM. Depending on the XDO classification, part types and resource items are instances of DKLobICM (for LOB), DKTextICM (for TEXT), DKImageICM (for IMAGE), DKStreamICM (for STREAM), DKVideoStreamICM (for VIDEO STREAM), or other subclasses for any application defined and implemented XDO Classes and part-classified item type definitions.
You can programmatically determine which subclass to cast to based on XDO classification. Assume a DKDDO instance at a minimum for all item types. As a DKDDO, look up the "object type",
ddo.getObjectType()
or
ddo.getPidObject().getObjectType()
. Using the "object type", look up the
item type view definition, DKItemTypeViewDefICM itemTypeViewDef = ((DKDatstoreDefICM)ddo.getDatastore().datastoreDef()).retrieveItemTypeView(objectType);
.
Resource content is limited to item types with classifications
"resource" or "document part" (DKConstantICM.DK_ICM_ITEMTYPE_CLASS_RESOURCE_ITEM
or DK_ICM_ITEMTYPE_CLASS_DOC_PART) which you can detect using
DKItemTypeViewDefICM::getClassification(). Only root components and document
parts have resource content and therefore only these are subclassed to the
DKLobICM interface. Next, use the DKItemTypeViewDefICM::getXDOClassID() or
getXDOClassName() methods and compare value to
DKConstantICM.DK_ICM_XDO_<XDO type>_CLASS_ID or
DKConstantICM.DK_ICM_XDO_<XDO type>_CLASS_NAME (all constant values detailed
in sample SItemTypeCreationICM documentation which help you know which further
subclasses you can cast down to (more on class hierarchy in the SResourceItemCreationICM
sample). By default, definitions are cached in memory and do not require
additional server calls to perform this check. In C++, definitions are copied
to protect memory management, therefore you should still minimize memory usage
where possible.
To access content loaded in memory, use the DKLobICM.setContent()/getContent() interfaces. Additionally you can write from memory to file and read from file into memory using DKLobiCM.setContentToClientFile()/getContentFromClientFile(). Remember that there are many ways to set and retrieve content described earlier. This section describes working with the in-memory retrieval.
For more information and interfaces accessing content, refer to the SResourceItemCreationICM and SResourceItemRetrievalICM API education samples as well as the Application Programming Reference for the DKLobICM interface (and other subclass interfaces).
BEHAVIOR NOTES
If DKRetrieveOptionsICM.resourceContent(true) attempted with any multi-item retrieve function (directly or indirectly such as through query), the following exception is thrown.
DKMessageId.DK_CM_MSG_BADOPTVALUE
DKUsageError with ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) if multi-item retrieve disallows any particular retrieve option request. The message text is appended with error message from ID DKMessageId.DK_CM_MSG_FUNCTION_NOTSUPP (DGL0482A) and appended with the offending method and option value. The following are invalid function + option combinations that are not supported.
"DKDatastoreICM.retrieveObjects(dkCollection,DKNVPair[]) + DKRetrieveOptionsICM.resourceContent(true)"
- multi-item retrieve does not accept DKRetrieveOptionsICM.resourceContent(true).
If using the older bitwise 'int' retrieve options (or defaults if no options specified), multi-item retrieve simply ignored any request for content (such as through option DKConstant.DK_CM_CONTENT_YES) and no exception was thrown.
Parameters:
resourceContentRequested
- If 'true', you request resourceContent retrieved into memory for resource items and document parts. If 'false', you do not request resource content loaded into local memory at this time (if resource items or document parts directly selected or if a document-classified item is selected and parts list requested).
resourceContent
- public boolean resourceContent( )
See DKRetrieveOptionsICM::resourceContent(boolean resourceContentRequested)
behaviorIgnoreNoneFoundError
- public void behaviorIgnoreNoneFoundError( boolean behaviorIgnoreNoneFoundErrorRequested)
Request that no exception is thrown if none of the selected DDOs are found
(or otherwise not a single selected DDO was retrieved successfully). Otherwise
if none of the selected DDOs are found, a DKDataObjectNotFound exception
with error ID DKMessageId.DK_CM_MSG_DATAOBJECT_NOTFOUND (DGL0491A) is thrown.
Using single-item retrieve, when the single DKDDO directly specified cannot be found in the system based on the PID or seen by the current user, an exception is thrown stating that the component was not found. Using multi-item retrieve, when no single DKDDO in the entire collection could be found, an exception is thrown stating that the component(s) were not found. During multi-item retrieve, if 99 out of 100 fail, but 1 out of 100 is found, no exception is thrown, but the 99 failed DDOs have been flagged as failed. If all 100 fail, then a Not Found error is reported. Indicators are provided to identify which DDOs were successfully retrieved and which were not (see "DETECTING INDIVIDUAL DDO SUCCESS/FAILURE" section further below).
For example, an application might remember PID strings to existing items, recreate blank DDOs from PID strings, and attempt to retrieve. Alternatively, an application might attempt to refresh an existing created earlier, traversed to through links or references, retrieved as a document part or child component, or obtained from a previous query. Perhaps the component DDOs or entire item has since been deleted (perhaps by another user or application) or the current user does not have access to the item.
This option only ignores valid and plausible PIDs for components that could possibly be found through the current session. This option does not prevent other exceptions related to basic PID validation up front. If you are likely to attempt retrieval of completely invalid PIDs that could not possibly exist (with impossible version numbers, incomplete PIDs, or object types that do not exist in this system), consider avoiding scenarios that result in invalid PIDs or filter out invalid PIDs prior to retrieval to avoid the system detecting and reporting an error. Avoid manipulating PID information and avoid piecing together PID information yourself (use only full PIDs and pid strings) to avoid possibly having an invalid PID. If it is plausible that the object type no longer exists, first iterate through your items and look up the entity type definition for each object type to ensure it exists in the current system. Most applications simply attempt previously valid PIDs which requires no extra tasks before submitting.
This option is not configurable when using query, which can in turn call multi-item retrieve on the caller's behalf. Query automatically overrides this setting since query never reports a Not Found Error. Query sets DKRetrieveOptionsICM::behaviorIgnoreNotFoundError(true) during its calls because some queries can return PIDs that are filtered out in some cases. Note there is no security issue. Simply stated, some component DKDDOs are filtered after the initial query that obtains the list of PIDs.
DETECTING INDIVIDUAL DDO SUCCESS/FAILURE
During multi-item retrieve, if 99 out of 100 fail, but 1 out of 100 is found, no exception is thrown, but indicators are provided to identify which DDOs were successfully retrieved and which were not. In this example, the 99 failed DDOs have been flagged as failed and one successfully DDO is flagged as successful. Details on detecting the indicators/flags are detailed in the "DATA STRUCTURES" section below.
See DATA STRUCTURES section.
DEFAULT: false (reports Not Found Errors) (Query overrides to 'true').
RECOMMENDED
TRUE (no Not Found Errors) for multi-item retrieve.
FALSE (reports Not Found Errors) for single-item retrieve.
See PERFORMANCE section for more details.
PRECEDENCE
When using query (DKDatstoreICM::execute(), evaluate(), and executeWithCallback() this setting is overridden to 'true' and any 'false' setting is ignored when used through query. Query always returns empty results instead of not found errors.
This option is independent, except that if nothing is selected for retrieval, there is no reason to call the server. No existence check is made. Therefore this option would be ignored. For example, if every setting was set to 'false', this option is ignored. No exception is thrown.
PERFORMANCE
By default (false), when reporting Not Found Errors, there is a very small, but measurable performance cost incurred to validating that at least one of the submitted results was found. When using multi-item retrieve, this check can become noticeable as the number of retrieved items increases (especially when more than 100). The relative cost of this check is a tiny fraction of the overall call to the server and populating the results, but is typically an unnecessary cost when using multi-item retrieve. Retrieve simply iterates over the original set of submitted DDOs prior to returning and validates that at least one indicates a success/fail status as DK_CM_SUCCESS. Consider that the application should iterate over the results and check the success/fail status itself if it is plausible that there were duplicates or individual items might no longer found or not accessible to the user because if just 1 of 1,000 were successful, no error is reported. The Not Found Error is only reported if all were unsuccessful. Therefore, in the case of multi-item retrieve, the built-in check to report an error is unnecessary since the application should already handle the case of 999 out of 1,000 not found or retrieved. The error is just the case where 1,000 out of 1,000 not found. While typically barely noticeable (if at all), it is often better to simply save the unnecessary cost when using multi-item retrieve or especially with larger numbers of items. Therefore, for multi-item retrieve it is recommended that you set this option to 'true' unless you prefer an exception and accept the small performance cost.
For single-item retrieve, it is recommended that you set this option to 'false' (default), except if the remaining comments in this section apply. For single items, it is typically more intuitive if the object informs you when it is no longer valid rather than returning without error. For example,
Exceptions should always be truly exceptional cases and should not be used for routine programming logic expecting exceptions. There is some overhead to the throw and catch logic. Your logs might also be filled with unnecessary error debugging information. It is better to avoid this error if you expect this situation to occur with some frequency in your application.
Typically, DDOs are found through query, updated and refreshed by users, and Not Found errors are rare.
Avoid attempting retrieve of completely invalid PIDs and catching and ignoring all errors. Use this option to ignore the not found errors automatically when a valid PID is no longer accessible. Otherwise a usage error is assumed by the system and error information is generated, processed, and logged to disk (if error logging enabled (typical)) which incurs a performance cost. Avoid using exceptions to handle routine cases.
DATA STRUCTURES
This is a behavior setting and does not cause changes to data structures based on its enablement or disablement. However, regardless of this the actual value of this behavior setting, there are related data structures used for indicating which DDOs were successfully retrieved and which failed. Each directly selected DKDDO submitted to retrieve will contain two useful DDO properties (See "DKRetrieveOptionsICM::baseAttributes(boolean) section "DATA STRUCTURES" for more information on accessing DDO properties in general).
First, DDO property named DKConstant.DK_CM_PROPERTY_LAST_OPERATION ("last_operation") has a DKNVPair value. The DKNVPair's name field (DKNVPair.getName()) specifies the last persistence operation performed on the DDO, which in this case should be DKConstant.DK_CM_LAST_OP_RETRIEVE ("RETRIEVE") and the value field (DKNVPair.getValue()) specifies success or failure through value constants DKConstant.DK_CM_SUCCESS ("SUCCESS") or DKConstant.DK_CM_FAIL ("FAIL"). Note that it is also might be possible to determine which retrieve option was last used to retrieve each DKDDO if enabled through behaviorRecordLastRetrieveOption(boolean).
See DKRetrieveOptionsICM::behaviorRecordLastRetrieveOptions(boolean) for details regarding enabling and accessing.
Lookup the DDO property by ID first to determine if it exists using
When using query (DKDatastoreICM::evaluate(), execute(), executeWithCallback()) and if you use the old bitwise 'int' option DKConstant.DK_CM_CONTENT_IDONLY, these two properties might not appear in the DDOs returned from query since query might detect that there is nothing to retried and skip any indirect retrieve processing that otherwise includes these properties as part of retrieve processing.
When using a DKRetrieveOptionsICM instance that does not request anything to retrieve or if you use retrieve directly and specify the old bitwise 'int' option DKConstant.DK_CM_CONTENT_IDONLY, these two properties are set, but the success/failure status will indicate DK_CM_FAIL to indicate that no server call was made to check anything. Although reported as FAILED, the operation essentially completed successfully, doing nothing as requested, but the DDOs were not validated for valid PIDs or for existence or access by the current user in the connected datastore. No call to the server was made for the DDOs. If you request nothing (IDONLY), there was nothing to be retrieved (since the DDO already includes the PID) and the validity of the PID and existence or access to the item based on that PID is not verified. The function returns without error.
VALIDATING PIDS
If you want to validate the PID, you issue a query (DKDatastoreICM::evaluate(), execute(), executeWithCallback()) with all retrieve options set to false with a query string similar to
MINIMUM SETTINGS TO FORCE SERVER CALL
If nothing is requested in the retrieve options when using the DKRetrieveOptionsICM interface, retrieve honors the "nothing" request and returns without error. No server call is made because nothing was requested and the success/fail indicator for the last operation property is marked as failed. Perhaps you might want to force a call such as to re-validate the PIDs, but not actually retrieve anything. If you truly do not want to retrieve anything, then you should not call retrieve. However, if you still want to use retrieve and want the bare minimum settings to still invoke a retrieve call, request baseAttributes(true) and specify an attribute filters (projection list) to only retrieve the system properties by specifying the attributeFilter(DKProjectionListICM) setting with one wildcard projection for type '*' with special keyword DKConstantICM.DK_ICM_SYSTEM_ATTRS as the only requested attributes. This enables the most minimal retrieval of information to validate the PID.
BEHAVIOR NOTES
If none of the selected DDOs are found, a DKDataObjectNotFound exception with error ID
When using the new options, the same error message and exception class is always thrown as indicated above. However, when using the old deprecated bitwise 'int' retrieve options, the actual exception class, message, and ID varies depending on which method you call and the number of objects within. For example, when using the deprecated bitwise 'int' options, any of the following can be thrown.
This option only ignores valid and plausible PIDs for components that could possibly be found through the current session. This option does not prevent other exceptions related to basic PID validation up front. For example, regardless of this option's setting, you can receive exceptions such as DKUsageError "DGL3974A: Invalid DB2 Content Manager PID" if the PID is incomplete or contains impossible values, such as a negative version number. If the object type is not defined as a component type or component type view in the current system, you can still get exceptions reporting an invalid component type. Use only full PID objects or PID strings. Do not manipulate or piece together your own PIDs. In general, do not use PIDs from one system on another.
Using single-item retrieve, when the single DKDDO directly specified cannot be found in the system based on the PID or seen by the current user, an exception is thrown stating that the component was not found. Using multi-item retrieve, when no single DKDDO in the entire collection could be found, an exception is thrown stating that the component(s) were not found. During multi-item retrieve, if 99 out of 100 fail, but 1 out of 100 is found, no exception is thrown, but the 99 failed DDOs have been flagged as failed. If all 100 fail, then a Not Found error is reported. Indicators are provided to identify which DDOs were successfully retrieved and which were not (see "DETECTING INDIVIDUAL DDO SUCCESS/FAILURE" section further below).
For example, an application might remember PID strings to existing items, recreate blank DDOs from PID strings, and attempt to retrieve. Alternatively, an application might attempt to refresh an existing created earlier, traversed to through links or references, retrieved as a document part or child component, or obtained from a previous query. Perhaps the component DDOs or entire item has since been deleted (perhaps by another user or application) or the current user does not have access to the item.
This option only ignores valid and plausible PIDs for components that could possibly be found through the current session. This option does not prevent other exceptions related to basic PID validation up front. If you are likely to attempt retrieval of completely invalid PIDs that could not possibly exist (with impossible version numbers, incomplete PIDs, or object types that do not exist in this system), consider avoiding scenarios that result in invalid PIDs or filter out invalid PIDs prior to retrieval to avoid the system detecting and reporting an error. Avoid manipulating PID information and avoid piecing together PID information yourself (use only full PIDs and pid strings) to avoid possibly having an invalid PID. If it is plausible that the object type no longer exists, first iterate through your items and look up the entity type definition for each object type to ensure it exists in the current system. Most applications simply attempt previously valid PIDs which requires no extra tasks before submitting.
This option is not configurable when using query, which can in turn call multi-item retrieve on the caller's behalf. Query automatically overrides this setting since query never reports a Not Found Error. Query sets DKRetrieveOptionsICM::behaviorIgnoreNotFoundError(true) during its calls because some queries can return PIDs that are filtered out in some cases. Note there is no security issue. Simply stated, some component DKDDOs are filtered after the initial query that obtains the list of PIDs.
DETECTING INDIVIDUAL DDO SUCCESS/FAILURE
During multi-item retrieve, if 99 out of 100 fail, but 1 out of 100 is found, no exception is thrown, but indicators are provided to identify which DDOs were successfully retrieved and which were not. In this example, the 99 failed DDOs have been flagged as failed and one successfully DDO is flagged as successful. Details on detecting the indicators/flags are detailed in the "DATA STRUCTURES" section below.
See DATA STRUCTURES section.
DEFAULT: false (reports Not Found Errors) (Query overrides to 'true').
RECOMMENDED
TRUE (no Not Found Errors) for multi-item retrieve.
FALSE (reports Not Found Errors) for single-item retrieve.
See PERFORMANCE section for more details.
PRECEDENCE
When using query (DKDatstoreICM::execute(), evaluate(), and executeWithCallback() this setting is overridden to 'true' and any 'false' setting is ignored when used through query. Query always returns empty results instead of not found errors.
This option is independent, except that if nothing is selected for retrieval, there is no reason to call the server. No existence check is made. Therefore this option would be ignored. For example, if every setting was set to 'false', this option is ignored. No exception is thrown.
PERFORMANCE
By default (false), when reporting Not Found Errors, there is a very small, but measurable performance cost incurred to validating that at least one of the submitted results was found. When using multi-item retrieve, this check can become noticeable as the number of retrieved items increases (especially when more than 100). The relative cost of this check is a tiny fraction of the overall call to the server and populating the results, but is typically an unnecessary cost when using multi-item retrieve. Retrieve simply iterates over the original set of submitted DDOs prior to returning and validates that at least one indicates a success/fail status as DK_CM_SUCCESS. Consider that the application should iterate over the results and check the success/fail status itself if it is plausible that there were duplicates or individual items might no longer found or not accessible to the user because if just 1 of 1,000 were successful, no error is reported. The Not Found Error is only reported if all were unsuccessful. Therefore, in the case of multi-item retrieve, the built-in check to report an error is unnecessary since the application should already handle the case of 999 out of 1,000 not found or retrieved. The error is just the case where 1,000 out of 1,000 not found. While typically barely noticeable (if at all), it is often better to simply save the unnecessary cost when using multi-item retrieve or especially with larger numbers of items. Therefore, for multi-item retrieve it is recommended that you set this option to 'true' unless you prefer an exception and accept the small performance cost.
For single-item retrieve, it is recommended that you set this option to 'false' (default), except if the remaining comments in this section apply. For single items, it is typically more intuitive if the object informs you when it is no longer valid rather than returning without error. For example,
ddo.retrieve(...)
will report a Not
Found Error with default options if the "ddo" object is no longer found
since you performed a persistent operation directly on the object, which
is typically more intuitive. Since retrieve options treated the same
among all retrieve methods for consistent behavior, for this reason the
DKRetrieveOptionsICM defaults to 'false' for this option. However,
even with single-item retrieve, if it is plausible that the item does
not exist or is not accessible to the user, you should avoid routine
exception logic and set this option to 'true'.
Exceptions should always be truly exceptional cases and should not be used for routine programming logic expecting exceptions. There is some overhead to the throw and catch logic. Your logs might also be filled with unnecessary error debugging information. It is better to avoid this error if you expect this situation to occur with some frequency in your application.
Typically, DDOs are found through query, updated and refreshed by users, and Not Found errors are rare.
Avoid attempting retrieve of completely invalid PIDs and catching and ignoring all errors. Use this option to ignore the not found errors automatically when a valid PID is no longer accessible. Otherwise a usage error is assumed by the system and error information is generated, processed, and logged to disk (if error logging enabled (typical)) which incurs a performance cost. Avoid using exceptions to handle routine cases.
DATA STRUCTURES
This is a behavior setting and does not cause changes to data structures based on its enablement or disablement. However, regardless of this the actual value of this behavior setting, there are related data structures used for indicating which DDOs were successfully retrieved and which failed. Each directly selected DKDDO submitted to retrieve will contain two useful DDO properties (See "DKRetrieveOptionsICM::baseAttributes(boolean) section "DATA STRUCTURES" for more information on accessing DDO properties in general).
First, DDO property named DKConstant.DK_CM_PROPERTY_LAST_OPERATION ("last_operation") has a DKNVPair value. The DKNVPair's name field (DKNVPair.getName()) specifies the last persistence operation performed on the DDO, which in this case should be DKConstant.DK_CM_LAST_OP_RETRIEVE ("RETRIEVE") and the value field (DKNVPair.getValue()) specifies success or failure through value constants DKConstant.DK_CM_SUCCESS ("SUCCESS") or DKConstant.DK_CM_FAIL ("FAIL"). Note that it is also might be possible to determine which retrieve option was last used to retrieve each DKDDO if enabled through behaviorRecordLastRetrieveOption(boolean).
See DKRetrieveOptionsICM::behaviorRecordLastRetrieveOptions(boolean) for details regarding enabling and accessing.
Lookup the DDO property by ID first to determine if it exists using
short propId = ddo.propertyId(DKConstant.DK_CM_PROPERTY_LAST_OPERATION);
If the property ID is '0', the property does not exist in the particular DKDDO.
If you determine you have a valid property ID, you can access the property value
by ID using Object value = ddo.getProperty(propId)
and cast the
value accordingly.
When using query (DKDatastoreICM::evaluate(), execute(), executeWithCallback()) and if you use the old bitwise 'int' option DKConstant.DK_CM_CONTENT_IDONLY, these two properties might not appear in the DDOs returned from query since query might detect that there is nothing to retried and skip any indirect retrieve processing that otherwise includes these properties as part of retrieve processing.
When using a DKRetrieveOptionsICM instance that does not request anything to retrieve or if you use retrieve directly and specify the old bitwise 'int' option DKConstant.DK_CM_CONTENT_IDONLY, these two properties are set, but the success/failure status will indicate DK_CM_FAIL to indicate that no server call was made to check anything. Although reported as FAILED, the operation essentially completed successfully, doing nothing as requested, but the DDOs were not validated for valid PIDs or for existence or access by the current user in the connected datastore. No call to the server was made for the DDOs. If you request nothing (IDONLY), there was nothing to be retrieved (since the DDO already includes the PID) and the validity of the PID and existence or access to the item based on that PID is not verified. The function returns without error.
VALIDATING PIDS
If you want to validate the PID, you issue a query (DKDatastoreICM::evaluate(), execute(), executeWithCallback()) with all retrieve options set to false with a query string similar to
//ddoObjectType[@ITEMID="yourItemId" AND @COMPONENTID="yourComponentId"
AND @VERSIONID="yourVersionId"
(inserting PID values by accessing
values from DKDDO::getPidObject(), casting to DKPidICM, and accessing
DKPidICM methods. You can use parentheses and OR
together
multiple DDO lookups in a single query. Query will return any valid DDOs
with completed PIDs that exist with the specified IDs.
MINIMUM SETTINGS TO FORCE SERVER CALL
If nothing is requested in the retrieve options when using the DKRetrieveOptionsICM interface, retrieve honors the "nothing" request and returns without error. No server call is made because nothing was requested and the success/fail indicator for the last operation property is marked as failed. Perhaps you might want to force a call such as to re-validate the PIDs, but not actually retrieve anything. If you truly do not want to retrieve anything, then you should not call retrieve. However, if you still want to use retrieve and want the bare minimum settings to still invoke a retrieve call, request baseAttributes(true) and specify an attribute filters (projection list) to only retrieve the system properties by specifying the attributeFilter(DKProjectionListICM) setting with one wildcard projection for type '*' with special keyword DKConstantICM.DK_ICM_SYSTEM_ATTRS as the only requested attributes. This enables the most minimal retrieval of information to validate the PID.
BEHAVIOR NOTES
If none of the selected DDOs are found, a DKDataObjectNotFound exception with error ID
DKMessageId.DK_CM_MSG_DATAOBJECT_NOTFOUND
(DGL0491A) is thrown.
If at least one succeeds, no exception is ever thrown in any case
pertaining to "not found" errors.
When using the new options, the same error message and exception class is always thrown as indicated above. However, when using the old deprecated bitwise 'int' retrieve options, the actual exception class, message, and ID varies depending on which method you call and the number of objects within. For example, when using the deprecated bitwise 'int' options, any of the following can be thrown.
DKDataObjectNotFound
with error IDDKMessageId.DK_CM_MSG_DATAOBJECT_NOTFOUND
(DGL0491A).DKDataObjectNotFound
with error IDDKMessageId.DK_ICM_MSG_MSGID_NOT_FOUND
(DGL3601A) and server return code '7044' (indicating an internal server error).DKUsageError
with error IDDKMessageIdICM.DK_ICM_MSG_RC_ITEM_ID_NOT_FOUND
(DGL3626A).
This option only ignores valid and plausible PIDs for components that could possibly be found through the current session. This option does not prevent other exceptions related to basic PID validation up front. For example, regardless of this option's setting, you can receive exceptions such as DKUsageError "DGL3974A: Invalid DB2 Content Manager PID" if the PID is incomplete or contains impossible values, such as a negative version number. If the object type is not defined as a component type or component type view in the current system, you can still get exceptions reporting an invalid component type. Use only full PID objects or PID strings. Do not manipulate or piece together your own PIDs. In general, do not use PIDs from one system on another.
behaviorIgnoreNoneFoundError
- public boolean behaviorIgnoreNoneFoundError( )
See DKRetrieveOptionsICM::behaviorIgnoreNotFoundError(boolean behaviorIgnoreNotFoundErrorRequested)
behaviorRecordLastRetrieveOption
- public void behaviorRecordLastRetrieveOption( boolean behaviorRecordLastRetrieveOptionRequested)
Request the last-retrieve option to be recorded in each DKDDO
directly selected for retrieval so that when revisiting your DKDDO
objects you can detect what was last retrieve, perhaps before
determining if you want to retrieve more information. You should
only request this property if you have needs to use it. Otherwise
you can save the extra property and memory needed to clone the original
if your application has no use for this property.
This setting specifically controls whether the following DDO property is populated:
DETECTING LAST RETRIEVE OPTION USED
You can detect the last retrieve option used to retrieve any directly selected DDO. Any DKDDOs "listed" under directly selected DKDDOs, such as children, parts, linked items, and folder contents will not necessarily have any indicator unless they too have been passed directly to retrieve in additional retrieve calls. Children, parts, linked items, and folder contents can be directly selected for retrieve and for those that are retrieved directly, they too will have the last retrieve option indicator. Note that in some cases listed or otherwise indirectly retrieved DDOs can have this property in some cases and will reflect the retrieve option relative to what it retrieved in the listed DDOs, not the original retrieve option for original directly selected DDOs. For example, if partsList(true) and partsAttributes(true) or resourceContent(true), the parts DKDDOs will have a last retrieve option indicating what was retrieved in them.
JAVA ONLY
This option is not available in the C++ API. The C++ API assumes the default value for this option and it is not possible to request recording of the last retrieve option in DDOs retrieved using DKRetrieveOptionsICM instances.
DEFAULT: false
PRECEDENCE
This option is independent and always records the last retrieve option except for one case when nothing is requested and using query. Query can detect when there is nothing to retrieve and bypass retrieve. Only the actual retrieve operation populates the last retrieve option. If retrieve is bypassed, such as through query when query detects nothing of significance is requested in the options, retrieve is not called and therefore the DKDDO property is not populated. No exception is thrown.
PERFORMANCE
There are no server calls involved with or affected by this setting. This setting simply affects whether the retrieve options used for any given retrieve call are to be cloned and recorded in each DKDDO directly retrieved.
In Java, only one clone is made and the same instances is reused, but there is a slight, possibly measurable, overhead to cloning a DKRetrieveOptionsICM if it happens to contain non-null attribute filters (attributeFilters(DKProjectionListICM)!=null) and the projection list contains a large number of projections (or large numbers of attributes for projections). Regardless, if you have no use for this property, save unnecessary object creation and processing to clone and set one more property in every DKDDO directly retrieved. The performance impact in Java should be very minimal.
However, this is one property that is processed entirely on the client system. Relative to most other operations and requests, this is typically a very small performance concern. However, if you are attempting to squeeze every bit of performance and memory usage, leaving this set to 'false' can help.
DATA STRUCTURES
First, review the "DATA STRUCTURES" section of DKRetrieveOptionsICM::baseAttributes(boolean) for proper understanding of DKDDO "data items" and "properties" in order to fully understand and properly handle the last retrieve option property.
For any DKDDOs passed to retrieve, DKDDO "property" DKConstantICM.DK_ICM_PROPERTY_DDO_LASTRETRIEVE_OPTION ("last-retrieve-opt") is added. The value is either one of the following, depending on which was submitted to retrieve.
Lookup the DDO properties by ID first to determine if they exist using
BEHAVIOR NOTES
If submitting retrieve options when calling query, note that query (DKDatastoreICM::evaluate(), execute(), & executeWithCallback()) intercepts the retrieve option and if nothing is requested for retrieval among any of the options, query does not call retrieve and therefore no last retrieve option is populated since retrieve is not called.
This setting specifically controls whether the following DDO property is populated:
- DKConstantICM.DK_ICM_PROPERTY_DDO_LASTRETRIEVE_OPTION (
"last-retrieve-opt"
) = <DKRetrieveOptionsICM
|java.lang.Integer
> - Copy of last retrieve option used (details below)
DETECTING LAST RETRIEVE OPTION USED
You can detect the last retrieve option used to retrieve any directly selected DDO. Any DKDDOs "listed" under directly selected DKDDOs, such as children, parts, linked items, and folder contents will not necessarily have any indicator unless they too have been passed directly to retrieve in additional retrieve calls. Children, parts, linked items, and folder contents can be directly selected for retrieve and for those that are retrieved directly, they too will have the last retrieve option indicator. Note that in some cases listed or otherwise indirectly retrieved DDOs can have this property in some cases and will reflect the retrieve option relative to what it retrieved in the listed DDOs, not the original retrieve option for original directly selected DDOs. For example, if partsList(true) and partsAttributes(true) or resourceContent(true), the parts DKDDOs will have a last retrieve option indicating what was retrieved in them.
JAVA ONLY
This option is not available in the C++ API. The C++ API assumes the default value for this option and it is not possible to request recording of the last retrieve option in DDOs retrieved using DKRetrieveOptionsICM instances.
DEFAULT: false
PRECEDENCE
This option is independent and always records the last retrieve option except for one case when nothing is requested and using query. Query can detect when there is nothing to retrieve and bypass retrieve. Only the actual retrieve operation populates the last retrieve option. If retrieve is bypassed, such as through query when query detects nothing of significance is requested in the options, retrieve is not called and therefore the DKDDO property is not populated. No exception is thrown.
PERFORMANCE
There are no server calls involved with or affected by this setting. This setting simply affects whether the retrieve options used for any given retrieve call are to be cloned and recorded in each DKDDO directly retrieved.
In Java, only one clone is made and the same instances is reused, but there is a slight, possibly measurable, overhead to cloning a DKRetrieveOptionsICM if it happens to contain non-null attribute filters (attributeFilters(DKProjectionListICM)!=null) and the projection list contains a large number of projections (or large numbers of attributes for projections). Regardless, if you have no use for this property, save unnecessary object creation and processing to clone and set one more property in every DKDDO directly retrieved. The performance impact in Java should be very minimal.
However, this is one property that is processed entirely on the client system. Relative to most other operations and requests, this is typically a very small performance concern. However, if you are attempting to squeeze every bit of performance and memory usage, leaving this set to 'false' can help.
DATA STRUCTURES
First, review the "DATA STRUCTURES" section of DKRetrieveOptionsICM::baseAttributes(boolean) for proper understanding of DKDDO "data items" and "properties" in order to fully understand and properly handle the last retrieve option property.
For any DKDDOs passed to retrieve, DKDDO "property" DKConstantICM.DK_ICM_PROPERTY_DDO_LASTRETRIEVE_OPTION ("last-retrieve-opt") is added. The value is either one of the following, depending on which was submitted to retrieve.
-
DKRetrieveOptionsICM
(copy)
Reference to a copy of the DKRetrieveOptionsICM instance processed by retrieve if a DKRetrieveOptionsICM instance was provided to retrieve. A copy is made to reflect the actual options at the time they were retrieved in case the options object changed after. In Java, all DKDDOs directly selected and retrieved in the same call reference the same copy (for minimized object instances, memory usage, and optimized performance). In C++, all DKDDOs have their own separate copy due to memory management needs. Note that if retrieved through query, query clones and modifies the options, removing functionVersionLatest(true) if requested since it is handled by query and adding behaviorIgnoreNoneFoundError(true). -
java.lang.Integer
(copy)
Integer containing the original bitwise 'int' option specified to query, or default bitwise 'int' option if no options specified. Each DKDDO has its own java.lang.Integer. Note that if retrieved through query, query modifies the bitwise options by removing any DKContant.DK_CM_VERSION_LATEST request and adds DKContant.DK_CM_CONTENT_RETRIEVE_IGNORE_ERROR. If no options are provided to retrieve, bitwise 'int' retrieve options are default (although you are encouraged to use the new DKRetrieveOptionsICM and specify exactly what you want retrieved).
Lookup the DDO properties by ID first to determine if they exist using
short propId = ddo.propertyId(DKConstantICM.DK_ICM_PROPERTY_DDO_LASTRETRIEVE_OPTION);
If the property ID is '0', the property does not exist in the particular DKDDO.
If you determine you have a valid property ID, you can access the property value
by ID using Object value = ddo.getProperty(propId)
and cast the
value based on instanceof
checks or based on knowledge of
which option type is used exclusively by your application.
BEHAVIOR NOTES
If submitting retrieve options when calling query, note that query (DKDatastoreICM::evaluate(), execute(), & executeWithCallback()) intercepts the retrieve option and if nothing is requested for retrieval among any of the options, query does not call retrieve and therefore no last retrieve option is populated since retrieve is not called.
behaviorRecordLastRetrieveOption
- public boolean behaviorRecordLastRetrieveOption( )
See DKRetrieveOptionsICM::behaviorRecordLastRetrieveOption(boolean behaviorRecordLastRetrieveOptionRequested)
behaviorSkipExistenceCheck
- public void behaviorSkipExistenceCheck( boolean behaviorSkipExistenceCheckRequested)
Request skipping existence checks for directly selected components
if possible. Links, parts list, parts attributes, and resource
content can be retrieved without existence checks when no
attributes or children requested, saving a multi-item existence check
(was already optimized by processing many at once).
If there is anything requested to retrieve, a multi-item existence check is performed which sets the success/fail indicators on each directly-selected DDO if they exist or not. Then, any additional data requested other than attributes or children proceed only if the DDO exists (based on success/failure indicators).
However, you can skip the existence check, saving the extra server calls and thereby improving performance, but at the loss of consistent handling of non-existent DDOs and behavior abnormalities. First, it is possible that if any DDO is not found while processing the additional data requests, an exception could be thrown immediately instead of simply flagging the DDO as FAILED for its success/fail indictor. Second, the success/fail indicators for each DDO might not accurately reflect existence or success, although should typically be accurate.
For consistent handling and behavior, leave this setting set to 'false'. However, if you want to squeeze faster performance, change this setting to 'true' and (only when possible) the existence check will be skipped, saving server calls and processing.
If nothing is requested to retrieve in the retrieve options, no existence check is performed, regardless of this setting, and the base DDOs are flagged as FAILED to indicate no check was made. See behaviorIgnoreNoneFoundError(boolean) for more details on success/fail indicators and when nothing is requested, even if you are not using that setting.
See DKRetrieveOptionsICM::behaviorIgnoreNoneFoundError(boolean) (even if not using that setting)
DEFAULT: false
PRECEDENCE
This behavior only applies if you have not requested any attributes or children (baseAttributes(false), basePropertyAclName(false), basePropertyCheckedOutDetails(false), childListOneLevel(false), and childListAllLevels(false) and you have not requested any other functions (functionCheckOut(false) & functionVersionLatest(false) and you have requested data that can be retrieved separately from attributes and children such as links, parts, or resource content (linksInbound(true), linksOutbound(true), partsList(true), or resourceContent(true)).
This setting is ignored if the existence check is necessary or is implicitly combined or part of another setting you requested, such as attributes, children, function checkout, or function version latest.
No error is reported if this setting is ignored or could not be honored.
PERFORMANCE
The existence check is implicitly part of the base attributes (and properties) requests and does not cost additional performance. However, when no base attributes or base properties are requested (baseAttributes(false), basePropertyAclName(false), and basePropertyCheckedOutDetails(false)), an existence check is included for the base DDOs.
If children are requested, the base DDO existence checks are combined with child list requests in the same call, meaning no separate server calls are needed in this case. Even when children are requested, there is additional server processing, table joins for all base DDO object types, additional cursors returned for all base DDO object types, network traffic to read results, and client side performance to read cursors and results. However, additional client-side memory usage is minimized and is temporary. The existence checks should slightly faster than retrieving a single system attribute/property for all base DDOs.
If neither attributes or children are requested, a separate multi-item existence check is required. This results in separate calls to the server for batches of base DDOs, the same way requests for attributes are combined into optimized batches to minimize number of cursors and table joins needed. For example, suppose you have 1,000 base DDOs selected and suppose the maximum batch size happens to be 300 (actual number no necessarily 300 / number used simply for demonstration purposes). Just four server calls might be needed to check all 1,000 DDOs, processed as batches of 300, 300, 300, and 100. Each server call incurs a performance cost and within each call additional performance is spent on table joins for each base DDO object type, returning cursors for each base DDO object type, network transfer for the results, and client-side processing of results. Memory usage is minimized and is temporary during the existence check. No additional data is saved in the base DDOs or cursor data actually retrieved is minimized. The existence checks should slightly faster than if you had requested a single system attribute/property for all base DDOs. Although optimized, if all items exist or if you can accept behavior abnormalities or inconsistent not-found handling (such as throwing exceptions on the spot), you can save these unnecessary calls.
You might consider this option when using query, which in most cases already includes the existence check implicitly since it returns only actual, existing, matching results for most cases (see "BEHAVIOR NOTES" section for further details and considerations).
DATA STRUCTURES
This is a behavior setting. Nothing is retrieved or populated by this option.
BEHAVIOR NOTES
First, this is a behavior setting. Therefore, first see behavior documentation above.
Query in most cases already includes the existence check implicitly since it returns only actual, existing, matching results for most cases (not all cases). However, it is possible that query can return inaccessible items and components that will be filtered out if retrieve completes the existence check. If you omit the existence check, query could either return items or components that will not be found on subsequent retrieve requests or if you requested only links, parts, or resource content an exception might be thrown immediately instead of simply reporting that no such results exist for the query.
If there is anything requested to retrieve, a multi-item existence check is performed which sets the success/fail indicators on each directly-selected DDO if they exist or not. Then, any additional data requested other than attributes or children proceed only if the DDO exists (based on success/failure indicators).
However, you can skip the existence check, saving the extra server calls and thereby improving performance, but at the loss of consistent handling of non-existent DDOs and behavior abnormalities. First, it is possible that if any DDO is not found while processing the additional data requests, an exception could be thrown immediately instead of simply flagging the DDO as FAILED for its success/fail indictor. Second, the success/fail indicators for each DDO might not accurately reflect existence or success, although should typically be accurate.
For consistent handling and behavior, leave this setting set to 'false'. However, if you want to squeeze faster performance, change this setting to 'true' and (only when possible) the existence check will be skipped, saving server calls and processing.
If nothing is requested to retrieve in the retrieve options, no existence check is performed, regardless of this setting, and the base DDOs are flagged as FAILED to indicate no check was made. See behaviorIgnoreNoneFoundError(boolean) for more details on success/fail indicators and when nothing is requested, even if you are not using that setting.
See DKRetrieveOptionsICM::behaviorIgnoreNoneFoundError(boolean) (even if not using that setting)
DEFAULT: false
PRECEDENCE
This behavior only applies if you have not requested any attributes or children (baseAttributes(false), basePropertyAclName(false), basePropertyCheckedOutDetails(false), childListOneLevel(false), and childListAllLevels(false) and you have not requested any other functions (functionCheckOut(false) & functionVersionLatest(false) and you have requested data that can be retrieved separately from attributes and children such as links, parts, or resource content (linksInbound(true), linksOutbound(true), partsList(true), or resourceContent(true)).
This setting is ignored if the existence check is necessary or is implicitly combined or part of another setting you requested, such as attributes, children, function checkout, or function version latest.
No error is reported if this setting is ignored or could not be honored.
PERFORMANCE
The existence check is implicitly part of the base attributes (and properties) requests and does not cost additional performance. However, when no base attributes or base properties are requested (baseAttributes(false), basePropertyAclName(false), and basePropertyCheckedOutDetails(false)), an existence check is included for the base DDOs.
If children are requested, the base DDO existence checks are combined with child list requests in the same call, meaning no separate server calls are needed in this case. Even when children are requested, there is additional server processing, table joins for all base DDO object types, additional cursors returned for all base DDO object types, network traffic to read results, and client side performance to read cursors and results. However, additional client-side memory usage is minimized and is temporary. The existence checks should slightly faster than retrieving a single system attribute/property for all base DDOs.
If neither attributes or children are requested, a separate multi-item existence check is required. This results in separate calls to the server for batches of base DDOs, the same way requests for attributes are combined into optimized batches to minimize number of cursors and table joins needed. For example, suppose you have 1,000 base DDOs selected and suppose the maximum batch size happens to be 300 (actual number no necessarily 300 / number used simply for demonstration purposes). Just four server calls might be needed to check all 1,000 DDOs, processed as batches of 300, 300, 300, and 100. Each server call incurs a performance cost and within each call additional performance is spent on table joins for each base DDO object type, returning cursors for each base DDO object type, network transfer for the results, and client-side processing of results. Memory usage is minimized and is temporary during the existence check. No additional data is saved in the base DDOs or cursor data actually retrieved is minimized. The existence checks should slightly faster than if you had requested a single system attribute/property for all base DDOs. Although optimized, if all items exist or if you can accept behavior abnormalities or inconsistent not-found handling (such as throwing exceptions on the spot), you can save these unnecessary calls.
You might consider this option when using query, which in most cases already includes the existence check implicitly since it returns only actual, existing, matching results for most cases (see "BEHAVIOR NOTES" section for further details and considerations).
DATA STRUCTURES
This is a behavior setting. Nothing is retrieved or populated by this option.
BEHAVIOR NOTES
First, this is a behavior setting. Therefore, first see behavior documentation above.
Query in most cases already includes the existence check implicitly since it returns only actual, existing, matching results for most cases (not all cases). However, it is possible that query can return inaccessible items and components that will be filtered out if retrieve completes the existence check. If you omit the existence check, query could either return items or components that will not be found on subsequent retrieve requests or if you requested only links, parts, or resource content an exception might be thrown immediately instead of simply reporting that no such results exist for the query.
Parameters:
behaviorSkipExistenceCheckRequested
- If 'true', will skip the existence check if possible and there could be inconsistencies in error handling, not found exceptions, and other behavior abnormalities. If 'false', will always perform an existence check (if anything was requested in the retrieve options).
behaviorSkipExistenceCheck
- public boolean behaviorSkipExistenceCheck( )
See DKRetrieveOptionsICM::behaviorSkipExistenceCheck(boolean behaviorSkipExistenceCheckRequested)
behaviorSkipResourceAttrRefresh
- public void behaviorSkipResourceAttrRefresh( boolean behaviorSkipResourceAttrRefreshRequested)
Request skipping refresh (re-retrieve) of resource content meta-data system attributes
if already retrieved previously if resource content was requested.
Suppose you have previously retrieved the resource item(s) or document part(s) and had requested their attributes, but had not requested resource content. When you re-retrieve and request resource content, the retrieve operation makes a new call to the library server to refresh the system attributes detailing the location and other details necessary to access the binary resource content on the object server. These resource-related system attributes are refreshed by default to ensure that the location information is current in case it had changed since you last retrieved the attributes.
However, if you know that the resource content has not changed (perhaps you had checked out (locked) the item), you can optimize performance by eliminating the separate call to the library server to refresh the resource content system-attributes if you are certain they have not changed. By skipping the refresh, the retrieve operation will assume nothing has change and retrieve the resource content from the object server based on previously retrieve information.
This scenario is typically only used when retrieving only resource content. With this behavior enabled, this considered the "CONTENT ONLY" optimization.
If it happens that you had not previously retrieved the necessary resource content system attributes, retrieve *will* call the library server and obtain the necessary system attributes for the first time. This behavior setting only eliminates a *refresh*, but will always retrieve if the necessary system attributes have never been retrieved for this instance.
You must be certain that the resource content has not changed since it will not be refreshed if you use this optimization. If the resource content has changed, the operation can return in error.
DEFAULT: false
PRECEDENCE
You must also request
This behavior only applies if you have requested resource content (DKRetrieveOptionsICM::resourceContent(true)). If there no resource content is requested, retrieve has no need to refresh resource content system attributes in the first place.
If you have included attributes for the resource item(s) or document part(s), the resource content system attributes refresh is implicitly part of the attributes request. You cannot also skip resource attribute refresh and ask for attributes at the same time. If you requested attributes, use attribute filters to filter attributes. However requesting attributes and requesting to skip RM Attributes is a conflicting option. For this reason, if you request to skip the resource attribute refresh and request another option that would force a call to retrieve the data you attempted to skip, a
If behaviorSkipResourceAttrRefresh(true) and any one of the following:
This setting applies only to directly-selected DDOs submitted to retrieve, including any resource items and document parts submitted directly. This setting does not apply to document parts listed in DKParts collections under directly-selected parent documents or for parts listed through the partsList(boolean) request in the same retrieve call. If the parts are already listed and attributes retrieved, you can submit the parts directly to multi-item retrieve (DKDatastoreICM::retrieveObjects(dkCollection,DKNVPair[])).
PERFORMANCE
Saving an unnecessary call to the library server when retrieving only resource content saves measurable performance on an enterprise system in high volumes. If you know for a fact that the resource content has not changed in the system by anyone from any connection, use this option to save unnecessary sever calls and network traffic.
DATA STRUCTURES
This is a behavior setting. Nothing is retrieved or populated by this option.
Suppose you have previously retrieved the resource item(s) or document part(s) and had requested their attributes, but had not requested resource content. When you re-retrieve and request resource content, the retrieve operation makes a new call to the library server to refresh the system attributes detailing the location and other details necessary to access the binary resource content on the object server. These resource-related system attributes are refreshed by default to ensure that the location information is current in case it had changed since you last retrieved the attributes.
However, if you know that the resource content has not changed (perhaps you had checked out (locked) the item), you can optimize performance by eliminating the separate call to the library server to refresh the resource content system-attributes if you are certain they have not changed. By skipping the refresh, the retrieve operation will assume nothing has change and retrieve the resource content from the object server based on previously retrieve information.
This scenario is typically only used when retrieving only resource content. With this behavior enabled, this considered the "CONTENT ONLY" optimization.
If it happens that you had not previously retrieved the necessary resource content system attributes, retrieve *will* call the library server and obtain the necessary system attributes for the first time. This behavior setting only eliminates a *refresh*, but will always retrieve if the necessary system attributes have never been retrieved for this instance.
You must be certain that the resource content has not changed since it will not be refreshed if you use this optimization. If the resource content has changed, the operation can return in error.
DEFAULT: false
PRECEDENCE
You must also request
DKRetrieveOptionsICM::behaviorSkipExistenceCheck(true)
if you request DKRetrieveOptionsICM::behaviorResourceAttrRefresh(true)
.
The existence check is effectively the same call to refresh the system
resource attributes which negates your request to skip the extra call.
To avoid conflicting options if behaviorResourceAttrRefresh(true)
and behaviorSkipExistenceCheck(false)
, a DKUsageError
is thrown with error ID DKMessageId.DK_CM_MSG_BADOPTVALUE
(DGL0314A) and appended with details of the conflicting options.
This behavior only applies if you have requested resource content (DKRetrieveOptionsICM::resourceContent(true)). If there no resource content is requested, retrieve has no need to refresh resource content system attributes in the first place.
If you have included attributes for the resource item(s) or document part(s), the resource content system attributes refresh is implicitly part of the attributes request. You cannot also skip resource attribute refresh and ask for attributes at the same time. If you requested attributes, use attribute filters to filter attributes. However requesting attributes and requesting to skip RM Attributes is a conflicting option. For this reason, if you request to skip the resource attribute refresh and request another option that would force a call to retrieve the data you attempted to skip, a
DKUsageError
is thrown with
error ID DKMessageId.DK_CM_MSG_BADOPTVALUE
(DGL0314A) and
appended with details of the conflicting options. Additionally, you
cannot use attribute filters (or projection lists) when attempting to
skip the resource system attribute refresh. If you request
DKRetrieveOptionsICM::behaviorSkipResourceAttrRefresh(true)
and specify a non-null DKRetrieveOptionsICM::attributeFilters(DKProjectionListICM)
,
a DKUsageError
is thrown with error ID DKMessageId.DK_CM_MSG_BADOPTVALUE
(DGL0314A) and appended with details of the conflicting options.
If behaviorSkipResourceAttrRefresh(true) and any one of the following:
- resourceContent(false)
- attributeFilters()!=null
- behaviorSkipExistenceCheck(false)
- baseAttributes(true)
- basePropertyAclName(true)
- basePropertyCheckedOutDetails(true)
- childAttributes(true)
- childListAllLevels(true)
- childListOneLevel(true)
- functionCheckOut(true)
- functionVersionLatest(true)
- linksDescriptors(true)
- linksInbound(true)
- linksInboundFolderSources(true)
- linksLevelTwo(true)
- linksLevelTwoCount(true)
- linksOutbound(true)
- partsAttributes(true)
- partsList(true)
This setting applies only to directly-selected DDOs submitted to retrieve, including any resource items and document parts submitted directly. This setting does not apply to document parts listed in DKParts collections under directly-selected parent documents or for parts listed through the partsList(boolean) request in the same retrieve call. If the parts are already listed and attributes retrieved, you can submit the parts directly to multi-item retrieve (DKDatastoreICM::retrieveObjects(dkCollection,DKNVPair[])).
PERFORMANCE
Saving an unnecessary call to the library server when retrieving only resource content saves measurable performance on an enterprise system in high volumes. If you know for a fact that the resource content has not changed in the system by anyone from any connection, use this option to save unnecessary sever calls and network traffic.
DATA STRUCTURES
This is a behavior setting. Nothing is retrieved or populated by this option.
Parameters:
behaviorSkipResourceAttrRefreshRequested
- If 'true', will skip refreshing resource content system attributes if previously retrieved for the resource item and document part instances. If the necessary system attributes are not previously retrieved, nothing is skipped. Only a refresh can be skipped. If 'false', will refresh (re-retrieve) resource content system attributes from the library sever prior to retrieving the resource content from the object server to ensure that the location information is correct.
behaviorSkipResourceAttrRefresh
- public boolean behaviorSkipResourceAttrRefresh( )
See DKRetrieveOptionsICM::behaviorSkipResourceAttrRefresh(bool behaviorSkipResourceAttrRefreshRequested)
behaviorPartsAttributesCoreOnly
- public void behaviorPartsAttributesCoreOnly( boolean behaviorPartsAttributesCoreOnly)
Request that only core parts attributes are retrieved when parts attributes are requested.
The core attributes include:
One typical scenario for using this option is when running a query or opening a folder and the application needs to display the file name and file size of the first part. This options is specified to retrieve this information without incurring the extra overhead of retrieving other attributes. In an application like this, it only needs the other attributes for the document parts if retrieving content or looking at all properties.
Applications can access the values of these core part attributes using the following methods on instances of DKLobICM which is the class used to represent parts:
With this behavior set to true, the system attributes detailing the location and other details necessary to access the binary resource content on the resource manager are not retrieved. These resource-related system attributes are not needed until content retrieval is desired. When retrieving content, these attributes will need to be populated, so the API will call the server to refresh these at that time. This works fine for most applications as the normal case is to get a large search result, but only retrieve content for a few.
DEFAULT: false
PRECEDENCE
You must also request
If behaviorPartsAttributesCoreOnly(true) and any one of the following:
PERFORMANCE
Saving unnecessary calls to the library server by retrieving only core attributes for parts improves performance significantly for large result sets. It also helps overall system performance, even for small results sets. This can also reduce network traffic.
BEHAVIOR NOTES
Note that when the file size is retrieved using this option, it may be different than the actual size when retrieved getting the content. This could happen if you have replication configured and the primary RM is down and the content in the RM has been updated on the replica. As the file size returned using this option will always be the size on the primary RM. This is done to optimize performance and is not an issue for many application.
DATA STRUCTURES
This is a behavior setting. Nothing is retrieved or populated by this option.
- Semantic Type
- Mime Type
- Original File Name
- File Size
One typical scenario for using this option is when running a query or opening a folder and the application needs to display the file name and file size of the first part. This options is specified to retrieve this information without incurring the extra overhead of retrieving other attributes. In an application like this, it only needs the other attributes for the document parts if retrieving content or looking at all properties.
Applications can access the values of these core part attributes using the following methods on instances of DKLobICM which is the class used to represent parts:
DKLobICM Value
---------------------
getSemanticType()
getMimeType()
getOrgFileName()
getSize()
With this behavior set to true, the system attributes detailing the location and other details necessary to access the binary resource content on the resource manager are not retrieved. These resource-related system attributes are not needed until content retrieval is desired. When retrieving content, these attributes will need to be populated, so the API will call the server to refresh these at that time. This works fine for most applications as the normal case is to get a large search result, but only retrieve content for a few.
DEFAULT: false
PRECEDENCE
You must also request
partsAttributes(true)
for this
behavior to apply. As this behavior only modifies the behavior of
partsAttributes(true)
, it is invalid to specify
behaviorPartsAttributesCoreOnly(true)
without also specifying partsAttributes(true)
. You must also request
partsList(true)
as this is required by
partsAttributes(true)
.
If behaviorPartsAttributesCoreOnly(true) and any one of the following:
- partsAttributes(false)
- partsList(false)
PERFORMANCE
Saving unnecessary calls to the library server by retrieving only core attributes for parts improves performance significantly for large result sets. It also helps overall system performance, even for small results sets. This can also reduce network traffic.
BEHAVIOR NOTES
Note that when the file size is retrieved using this option, it may be different than the actual size when retrieved getting the content. This could happen if you have replication configured and the primary RM is down and the content in the RM has been updated on the replica. As the file size returned using this option will always be the size on the primary RM. This is done to optimize performance and is not an issue for many application.
DATA STRUCTURES
This is a behavior setting. Nothing is retrieved or populated by this option.
Parameters:
behaviorPartsAttributesCoreOnly
- If 'true', this option will modify the behavior of the
partsAttributes(true)
option to limit the attributes that are populated in the part DDOs. This
saves server calls and can improve performance for some applications. The attributes
populated are: Semantic Type, Mime Type, File Size, Original File Name, and Part Number. behaviorPartsAttributesCoreOnly
- public boolean behaviorPartsAttributesCoreOnly( )
See DKRetrieveOptionsICM::behaviorPartsAttributesCoreOnly(boolean behaviorPartsAttributesCoreOnly)
functionCheckOut
- public void functionCheckOut(boolean functionCheckOutRequested)
Check out (lock) all items directly selected for retrieval.
Before making changes to an item, lock the item to ensure no one else
changes the item while you are still working on your changes. If you
first retrieved your item and later decided to lock it, there is a time
window in which another user could have checked out, modified, and
checked in the item between the time you retrieved but before you called
check out. Before making changes, refresh (re-retrieve) the item after
or during checkout. With this retrieve option, you can combine your
refresh/retrieve and checkout requests in one optimized call to ensure
you start your work on the latest copy.
This retrieve option is the most optimal means to lock multiple items in one server call and can be combined with a refresh in the same call to ensure your changes are based on the latest updates. If you need to simply lock individual items one at a time, you can use
Items are made up of a tree of components, one root components and any number of child components. The root component is the key to the entire item and is responsible for saving, updating, locking, and deleting items. Root components control locks for the entire item. Therefore, you can only request locks on root components. Since this locks the "item", all children as well as the root component are locked as long as you lock the root component. Additionally, document parts are owned by and controlled through the parent document's root component. If you lock a document that has parts, all parts are considered locked. Therefore, if you request check out when child components or parts are directly selected, an exception is thrown (as detailed in the "BEHAVIOR NOTES" section). You can only request checkout on root components of independent items. This method request locks on All DDOs submitted
If any item is already locked by another user, an exception is thrown (detailed in the "BEHAVIOR NOTES" section) if the current user does not have sufficient super-user privileges to override existing locks. If the current user has sufficient super-user privileges, the current user steals the lock and the item becomes locked by the current super user or administrator. All DDOs submitted will be locked by the current user as a result of a retrieve call with this option. If desired, you can easily check the lock status on items using the
Although not required, you can easily verify that you have or have not acquired a lock on each item as a result of this call without extra calls to the server by simply checking the checked out detail properties retrieved through the
DEFAULT: false
PRECEDENCE
This setting is independent and does not require any other settings to function. This setting is not affected by attribute filters or projection lists.
PERFORMANCE
This is one of the fastest ways to lock many items at once, and especially when combining with retrieve/refresh calls that are already contacting the server for the refresh. One call is almost always faster than making separate calls to lock and refresh or for locking multiple items. If you routinely use
With any operation or additional request, there is a cost to process a request in the server. This is not considered a very expensive operation.
If you routinely receive errors if the selected DDOs are already locked by another, you incur unnecessary wasteful calls that do not complete. Consider checking the checkout status first. You can easily check the lock status on items using the
Repeat lock requests by the same user for locks already obtained makes unnecessary wasteful calls. However, if you are already making a server call to retrieve or refresh data, this option is not expensive. Making separate calls to the checkout function when already locked is much more expensive. Just remember that no request is completely free of any performance consideration. However, this option is typically the most optimal.
DATA STRUCTURES
This is a function request. Nothing is retrieved or populated by this option.
BEHAVIOR NOTES
Children and document parts cannot be directly checked out independently from the root component of the item (or parent document) that contains them. If child components or document parts are submitted directly to retrieve and functionCheckOut(true) requested, DKUsageError with error ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) is thrown (appended with text describing the offending options).
In order to override the existing locks by other users, current user must have the privilege "ItemSuperCheckIn", which is include in those system admin privilege set, such as SysAdminCM, SysAdminEIP, SysAdminSuper.
If any items are already locked by another user and if the current user does not have "ItemSuperCheckIn" privilege to override the existing lock, a DKUsageError exception is thrown with error ID DKMessageIdICM.DK_ICM_MSG_RC_PRIV_GENERAL_ERROR (DGL3688A) indicating that the current user does not have the general privilege to perform this operation and will indicate which privilege is needed to override, such as "ItemSuperCheckIn", with return code 7215, and the missing privilege code is reported as the library server reason code in the exception state.
If the current user has sufficient super-user privileges to override existing locks by other users, all existing locks will be overridden and become locked by the current user. There is no notice given that a lock was overridden. If desired, you can check the checked out detail status using
Note that this behavior differs from the older bitwise 'int' retrieve option DKConstant.DK_CM_CHECKOUT:
This retrieve option is the most optimal means to lock multiple items in one server call and can be combined with a refresh in the same call to ensure your changes are based on the latest updates. If you need to simply lock individual items one at a time, you can use
DKDatastoreICM::checkOut(dkDataObject ddo)
.
Items are made up of a tree of components, one root components and any number of child components. The root component is the key to the entire item and is responsible for saving, updating, locking, and deleting items. Root components control locks for the entire item. Therefore, you can only request locks on root components. Since this locks the "item", all children as well as the root component are locked as long as you lock the root component. Additionally, document parts are owned by and controlled through the parent document's root component. If you lock a document that has parts, all parts are considered locked. Therefore, if you request check out when child components or parts are directly selected, an exception is thrown (as detailed in the "BEHAVIOR NOTES" section). You can only request checkout on root components of independent items. This method request locks on All DDOs submitted
If any item is already locked by another user, an exception is thrown (detailed in the "BEHAVIOR NOTES" section) if the current user does not have sufficient super-user privileges to override existing locks. If the current user has sufficient super-user privileges, the current user steals the lock and the item becomes locked by the current super user or administrator. All DDOs submitted will be locked by the current user as a result of a retrieve call with this option. If desired, you can easily check the lock status on items using the
DKRetrieveOptionsICM::basePropertyCheckedOutDetails(boolean)
option before requesting locks if you want to avoid potential
exceptions or overriding locks by a super user. If any are already
locked, simply create a new dkCollection
(such as by creating
a DKSequentialCollection
) and submit the subset that you
want to lock to multi-item retrieve (DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] options)
).
Although not required, you can easily verify that you have or have not acquired a lock on each item as a result of this call without extra calls to the server by simply checking the checked out detail properties retrieved through the
DKRetrieveOptionsICM::basePropertyCheckedOutDetails(boolean)
option in the same call that you request the locks.
See basePropertyCheckedOutDetails()
for more
information.
DEFAULT: false
PRECEDENCE
This setting is independent and does not require any other settings to function. This setting is not affected by attribute filters or projection lists.
PERFORMANCE
This is one of the fastest ways to lock many items at once, and especially when combining with retrieve/refresh calls that are already contacting the server for the refresh. One call is almost always faster than making separate calls to lock and refresh or for locking multiple items. If you routinely use
DKDatastoreICM::checkOut(dkDataObject ddo)
on a per-item basis. Consider combining the requests into a single call.
With any operation or additional request, there is a cost to process a request in the server. This is not considered a very expensive operation.
If you routinely receive errors if the selected DDOs are already locked by another, you incur unnecessary wasteful calls that do not complete. Consider checking the checkout status first. You can easily check the lock status on items using the
DKRetrieveOptionsICM::basePropertyCheckedOutDetails(boolean)
option before requesting locks if you want to avoid potential
exceptions or overriding locks by a super user. If any are already
locked, simply create a new dkCollection
(such as by creating
a DKSequentialCollection
) and submit the subset that you
want to lock to multi-item retrieve (DKDatastoreICM::retrieveObjects(dkCollection ddoColl,DKNVPair[] options)
).
Repeat lock requests by the same user for locks already obtained makes unnecessary wasteful calls. However, if you are already making a server call to retrieve or refresh data, this option is not expensive. Making separate calls to the checkout function when already locked is much more expensive. Just remember that no request is completely free of any performance consideration. However, this option is typically the most optimal.
DATA STRUCTURES
This is a function request. Nothing is retrieved or populated by this option.
BEHAVIOR NOTES
Children and document parts cannot be directly checked out independently from the root component of the item (or parent document) that contains them. If child components or document parts are submitted directly to retrieve and functionCheckOut(true) requested, DKUsageError with error ID DKMessageId.DK_CM_MSG_BADOPTVALUE (DGL0314A) is thrown (appended with text describing the offending options).
In order to override the existing locks by other users, current user must have the privilege "ItemSuperCheckIn", which is include in those system admin privilege set, such as SysAdminCM, SysAdminEIP, SysAdminSuper.
If any items are already locked by another user and if the current user does not have "ItemSuperCheckIn" privilege to override the existing lock, a DKUsageError exception is thrown with error ID DKMessageIdICM.DK_ICM_MSG_RC_PRIV_GENERAL_ERROR (DGL3688A) indicating that the current user does not have the general privilege to perform this operation and will indicate which privilege is needed to override, such as "ItemSuperCheckIn", with return code 7215, and the missing privilege code is reported as the library server reason code in the exception state.
If the current user has sufficient super-user privileges to override existing locks by other users, all existing locks will be overridden and become locked by the current user. There is no notice given that a lock was overridden. If desired, you can check the checked out detail status using
DKRetrieveOptionsICM::basePropertyCheckedOutDetails(boolean)
before the checkout call to determine which locks will be overridden
if the current user has sufficient super-user privileges.
Note that this behavior differs from the older bitwise 'int' retrieve option DKConstant.DK_CM_CHECKOUT:
- For child components, the checkout request is ignored for any submitted to retrieve.
- For document parts, when calling retrieve directly on a DKLobICM instance (or any super-class that results in a virtual call to DKLobICM.retrieve(...)), DKUsageError with error ID DKMessageId.DK_CM_MSG_BADOPTVALUE is thrown (but with no appended details on offending options).
- For document parts, when calling retrieve through other methods that do not result in a virtual call to DKLobICM.retrieve(...) (such as DKDatastoreICM.retrieveObject(dkDataObject), retrieveObjects(dkCollection), evaluate(), execute(), or executeWithCallback(), parts checkout proceeds and are marked as checked out, but has no effect.
Parameters:
functionCheckOutRequested
- If 'true', request checkout (locks) on all items directly selected through their root components. If 'false', do not request any change to checkout/lock state of the items selected.
functionCheckOut
- public boolean functionCheckOut( )
See DKRetrieveOptionsICM::functionCheckOut(boolean functionCheckOutRequested)
functionVersionLatest
- public void functionVersionLatest( boolean functionVersionLatestRequested)
Request the latest available version for all components directly selected,
overriding the specific version number identified in the PIDs for the
directly selected component DDOs.
This optimized latest version function requests the server to instead determine and return the latest version only, regardless of what version was originally specified.
Note that if you selected multiple versions of the same components as differently versioned DDOs, only one is retrieved and updated with the latest version. You should not use this function when more than one component version is selected. The duplicate components are flagged with errors (no exception thrown).
This function operates without error on all directly selected component DKDDOs (root components, child components, document parts) and regardless of item type version enablement settings. All components have a version, even if versioning is off for an item type. When versioning is set to "NEVER" for an item type, component DDO instances from that item type simply are version number '1'.
Documents from "document" classified item types can be versioned independently from their document parts. The document controls the list of document parts. The parts list is versioned with the document and point to a specific version of the parts which might carry the same version number as the parent document. However, parts can be versioned automatically when the parent document is versioned, which typically maintains the same version numbering between the document and its parts. When the document is directly selected, this setting does not retrieve the latest version of the part DKDDOs, just the latest version of the document's parts list, which could point to parts that are not the latest version of those parts, but the list retrieved is the correct list that matches the document version.
Separate copies of the child components are saved with each new version of an item. The child components carry the same version number as the root component (and item as a whole).
Links and folder relationships are not version-specific, and therefore always assume the latest version by default, but not related to this latest version request. The blank DKDDOs (for the targets of outbound links, source DKDDOs of inbound links, and optional descriptors) have completed PID information, but the PIDs to not point to a specific version (listed as invalid version number '0'). When these DDOs are retrieved, at that point the latest version for those DDOs is assumed regardless of this setting. This setting has no impact on link or folder relationship data structures.
Reference attribute values are a version-specific reference to another item. the version-specific reverence is an attribute value that belongs to the meta data of the component. When the component is versioned, the exact value is stored with that version. This setting has no effect on the values of reference properties. The component containing the reference attribute can be retrieved with the latest version option, but that latest component version can contain a reference attribute value that points to an older version of another item.
This retrieve option setting is functionally different than the query "latest-version(.)" function. Each serve unique purposes, but can overlap. In short, the "latest-version(.)" query function matches all other conditions against that latest version only. If not limiting by version in query and using this retrieve option setting, if any version matches the other conditions, query returns the latest version, even if the latest version did not match the other conditions.
Query returns all matching results unless you further specify conditions that limit what is returned. This means that all versions that exist are returned unless you specified the version number in predicate conditions. You can place conditions on the "VERSIONID" attribute using query operators and constructs to clarify exactly which version of any component you are referring to. You can specify the "latest-version(.)" query function. For example, "/Book[@VERSIONID = latest-version(.)]". Query returns all versions unless you clarified which specific version(s) you were referring to for the output components. For example, with query "/Book[@author="Smith"]", " query could find 100 Book items with 10 versions each, totaling 1,000 DKDDOs. If you used the functionVersionLatest() retrieve option, query will automatically optimize and return only the 100 latest versions, ignoring the 900 that are not needed that would otherwise be returned. If you instead specified query "/Book[@author="Smith" AND @VERSIONID=7]", query will only return Book version 7 if Book version 7 had author "Smith". If also used the functionVersionLatest() retrieve option, query correctly finds matching result Book version 7 while retrieve retrieves Book version 10 because latest version retrieve was requested. This demonstrates the difference between a retrieve function request and query conditions that determine matching results.
Furthermore, supposed author biographies are linked from the Book items and you use "/Book[@title="ABC"]/OUTBOUNDLINK[@LINKTYPE="Biographies"]/@TARGETITEMREF => Biography". This returns all versions of any author biography for any version of Book titled "ABC". If you specify functionVersionLatest(true), you get the latest version of any biography for authors that penned *any version* of Book "ABC". The functionVersionLatest() retrieve option applies only to the output nodes as they are retrieved and does not affect intermediate components traversed through, such as Book in this case. If you meant to only request the latest biography from the latest version of Book "ABC", you could use either query "/Book[@title="ABC" AND @VERSIONID=latest-version(.)]/OUTBOUNDLINK[@LINKTYPE="Biographies"]/@TARGETITEMREF => Biography[@VERSIONID=latest-version(.)]". with functionVersionLatest(false) or "/Book[@title="ABC" AND @VERSIONID=latest-version(.)]/OUTBOUNDLINK[@LINKTYPE="Biographies"]/@TARGETITEMREF => Biography". with functionVersionLatest(true). It is often best to fully qualify your query to avoid any confusion.
DEFAULT: false
PRECEDENCE
This setting only applies to directly-selected DDOs submitted to retrieve. This setting requests the latest version for any directly selected DDO and any children if child listing requested. This does not apply to parts, links, or resource content listed, except that the parts, links, and resource content retrieved is then based on the latest version of the directly-selected DDOs instead of the versions originally submitted.
This setting should be used in conjunction with other settings, such as baseAttributes(), childList(), partsList(), etc. This setting has no effect on linksOutbound() or linksInbound().
No exceptions are thrown as a result of this setting used in combination of other settings.
PERFORMANCE
With any operation, there is a cost to process a request in the server, but this option is not considered a very expensive operation.
This retrieve setting is relatively equal in performance to the query "latest-version(.)" function. With this retrieve options setting, query does optimize to select only one version, regardless of whether the "latest-version(.)" function is used. However, there is a functional difference mentioned earlier.
DATA STRUCTURES
Each DKDDO has a DKPidICM. You can access the PID through DKDDO::getPidObject() which returns a DKPid superclass which can be downcast to DKPidICM. DKPidICM::getVersionNumber() reports the version number as a string. Version numbers are positive integers starting at '1' (although you will find DDOs with '0' occasionally such as from links and folder relationships which will turn into the latest version when retrieved). However, when using query, you must refer to the system PID attribute "VERSIONID" which is an integer, not a string. Therefore, when querying, use integer literals, not quoted strings.
See the SItemTypeCreationICM API education sample for item type definition information regarding versioning settings. See the SItemUpdateICM API education sample for creating new versions. See the SSearchICM API education sample for querying specific versions or querying the latest version.
BEHAVIOR NOTES
The parts listed by partsList(boolean) are based on the version of the parent document. This setting does not override the version of the parts attached to the specific version of the parent document, except that the latest version of the parent document is used.
Links are not version-specific and the links lists will not be affected. When links are listed, the other DDOs associated with the link assume the latest version regardless of your functionVersionLatest(boolean) setting if they are submitted to a retrieve request later. In the meanwhile, their PIDs always list version "0" until submitted to retrieve themselves, when their version number will be updated.
This optimized latest version function requests the server to instead determine and return the latest version only, regardless of what version was originally specified.
Note that if you selected multiple versions of the same components as differently versioned DDOs, only one is retrieved and updated with the latest version. You should not use this function when more than one component version is selected. The duplicate components are flagged with errors (no exception thrown).
This function operates without error on all directly selected component DKDDOs (root components, child components, document parts) and regardless of item type version enablement settings. All components have a version, even if versioning is off for an item type. When versioning is set to "NEVER" for an item type, component DDO instances from that item type simply are version number '1'.
Documents from "document" classified item types can be versioned independently from their document parts. The document controls the list of document parts. The parts list is versioned with the document and point to a specific version of the parts which might carry the same version number as the parent document. However, parts can be versioned automatically when the parent document is versioned, which typically maintains the same version numbering between the document and its parts. When the document is directly selected, this setting does not retrieve the latest version of the part DKDDOs, just the latest version of the document's parts list, which could point to parts that are not the latest version of those parts, but the list retrieved is the correct list that matches the document version.
Separate copies of the child components are saved with each new version of an item. The child components carry the same version number as the root component (and item as a whole).
Links and folder relationships are not version-specific, and therefore always assume the latest version by default, but not related to this latest version request. The blank DKDDOs (for the targets of outbound links, source DKDDOs of inbound links, and optional descriptors) have completed PID information, but the PIDs to not point to a specific version (listed as invalid version number '0'). When these DDOs are retrieved, at that point the latest version for those DDOs is assumed regardless of this setting. This setting has no impact on link or folder relationship data structures.
Reference attribute values are a version-specific reference to another item. the version-specific reverence is an attribute value that belongs to the meta data of the component. When the component is versioned, the exact value is stored with that version. This setting has no effect on the values of reference properties. The component containing the reference attribute can be retrieved with the latest version option, but that latest component version can contain a reference attribute value that points to an older version of another item.
This retrieve option setting is functionally different than the query "latest-version(.)" function. Each serve unique purposes, but can overlap. In short, the "latest-version(.)" query function matches all other conditions against that latest version only. If not limiting by version in query and using this retrieve option setting, if any version matches the other conditions, query returns the latest version, even if the latest version did not match the other conditions.
Query returns all matching results unless you further specify conditions that limit what is returned. This means that all versions that exist are returned unless you specified the version number in predicate conditions. You can place conditions on the "VERSIONID" attribute using query operators and constructs to clarify exactly which version of any component you are referring to. You can specify the "latest-version(.)" query function. For example, "/Book[@VERSIONID = latest-version(.)]". Query returns all versions unless you clarified which specific version(s) you were referring to for the output components. For example, with query "/Book[@author="Smith"]", " query could find 100 Book items with 10 versions each, totaling 1,000 DKDDOs. If you used the functionVersionLatest() retrieve option, query will automatically optimize and return only the 100 latest versions, ignoring the 900 that are not needed that would otherwise be returned. If you instead specified query "/Book[@author="Smith" AND @VERSIONID=7]", query will only return Book version 7 if Book version 7 had author "Smith". If also used the functionVersionLatest() retrieve option, query correctly finds matching result Book version 7 while retrieve retrieves Book version 10 because latest version retrieve was requested. This demonstrates the difference between a retrieve function request and query conditions that determine matching results.
Furthermore, supposed author biographies are linked from the Book items and you use "/Book[@title="ABC"]/OUTBOUNDLINK[@LINKTYPE="Biographies"]/@TARGETITEMREF => Biography". This returns all versions of any author biography for any version of Book titled "ABC". If you specify functionVersionLatest(true), you get the latest version of any biography for authors that penned *any version* of Book "ABC". The functionVersionLatest() retrieve option applies only to the output nodes as they are retrieved and does not affect intermediate components traversed through, such as Book in this case. If you meant to only request the latest biography from the latest version of Book "ABC", you could use either query "/Book[@title="ABC" AND @VERSIONID=latest-version(.)]/OUTBOUNDLINK[@LINKTYPE="Biographies"]/@TARGETITEMREF => Biography[@VERSIONID=latest-version(.)]". with functionVersionLatest(false) or "/Book[@title="ABC" AND @VERSIONID=latest-version(.)]/OUTBOUNDLINK[@LINKTYPE="Biographies"]/@TARGETITEMREF => Biography". with functionVersionLatest(true). It is often best to fully qualify your query to avoid any confusion.
DEFAULT: false
PRECEDENCE
This setting only applies to directly-selected DDOs submitted to retrieve. This setting requests the latest version for any directly selected DDO and any children if child listing requested. This does not apply to parts, links, or resource content listed, except that the parts, links, and resource content retrieved is then based on the latest version of the directly-selected DDOs instead of the versions originally submitted.
This setting should be used in conjunction with other settings, such as baseAttributes(), childList(), partsList(), etc. This setting has no effect on linksOutbound() or linksInbound().
No exceptions are thrown as a result of this setting used in combination of other settings.
PERFORMANCE
With any operation, there is a cost to process a request in the server, but this option is not considered a very expensive operation.
This retrieve setting is relatively equal in performance to the query "latest-version(.)" function. With this retrieve options setting, query does optimize to select only one version, regardless of whether the "latest-version(.)" function is used. However, there is a functional difference mentioned earlier.
DATA STRUCTURES
Each DKDDO has a DKPidICM. You can access the PID through DKDDO::getPidObject() which returns a DKPid superclass which can be downcast to DKPidICM. DKPidICM::getVersionNumber() reports the version number as a string. Version numbers are positive integers starting at '1' (although you will find DDOs with '0' occasionally such as from links and folder relationships which will turn into the latest version when retrieved). However, when using query, you must refer to the system PID attribute "VERSIONID" which is an integer, not a string. Therefore, when querying, use integer literals, not quoted strings.
See the SItemTypeCreationICM API education sample for item type definition information regarding versioning settings. See the SItemUpdateICM API education sample for creating new versions. See the SSearchICM API education sample for querying specific versions or querying the latest version.
BEHAVIOR NOTES
The parts listed by partsList(boolean) are based on the version of the parent document. This setting does not override the version of the parts attached to the specific version of the parent document, except that the latest version of the parent document is used.
Links are not version-specific and the links lists will not be affected. When links are listed, the other DDOs associated with the link assume the latest version regardless of your functionVersionLatest(boolean) setting if they are submitted to a retrieve request later. In the meanwhile, their PIDs always list version "0" until submitted to retrieve themselves, when their version number will be updated.
Parameters:
functionVersionLatestRequested
- If 'true', requests the latest version of the item rather than the specific version indicated in the PIDs of the submitted items for retrieval. The PIDs are updated to the latest version. When used with the query operation, the query will return only the latest versions rather than all version matching the query conditions. If 'false', retrieve the specific versions indicated in the PIDs for each submitted item. When used with the query operation, all versions matching the query condition are returned.
functionVersionLatest
- public boolean functionVersionLatest( )
See DKRetrieveOptionsICM::functionVersionLatest(boolean functionVersionLatestRequested){
toString
- public java.lang.String toString( )
Request a single-line string description of this object.
This method is typically used for logging and debugging to review the
settings in this object. The length of the string can be long.
Example Output:
DKRetrieveOptionsICM(Included={<setting1>,<setting2>,...,<settingN>} Excluded={<setting1>,<setting2>,...,<settingN>})
DKRetrieveOptionsICM::toString(boolean) allows you to specify whether or not to show the exclude list for a shorter, simplified string. The toString() method shows the exclude list, simply calling toString(showExcludeList=true).
WARNING
Do not rely on exact formatting. This string representation is for debugging and logging purposes only. The format and other characteristics can change over time. Applications should not parse this text and rely on the same format in the future. Use the getProjections() method that returns a much better data structure that your application can interpret.
Example Output:
DKRetrieveOptionsICM(Included={<setting1>,<setting2>,...,<settingN>} Excluded={<setting1>,<setting2>,...,<settingN>})
DKRetrieveOptionsICM::toString(boolean) allows you to specify whether or not to show the exclude list for a shorter, simplified string. The toString() method shows the exclude list, simply calling toString(showExcludeList=true).
WARNING
Do not rely on exact formatting. This string representation is for debugging and logging purposes only. The format and other characteristics can change over time. Applications should not parse this text and rely on the same format in the future. Use the getProjections() method that returns a much better data structure that your application can interpret.
Overrides:
toString
in class java.lang.Object
Returns:
a single-line string description.
toString
- public java.lang.String toString( boolean showExcludeList)
Same as toString(), except that you can specify whether or not to print
the excluded items. This enables a shorter, simplified string, but will
not clearly show what is excluded by omission.
Request a single-line string description of this object. This method is typically used for logging and debugging to review the settings in this object. The length of the string can be long.
Example Output:
option 'true' : DKRetrieveOptionsICM(Included={<setting1>,<setting2>,...,<settingN>} Excluded={<setting1>,<setting2>,...,<settingN>})
option 'false': DKRetrieveOptionsICM{<setting1>,<setting2>,...,<settingN>}
WARNING
Do not rely on exact formatting. This string representation is for debugging and logging purposes only. The format and other characteristics can change over time. Applications should not parse this text and rely on the same format in the future. Use the getProjections() method that returns a much better data structure that your application can interpret.
Request a single-line string description of this object. This method is typically used for logging and debugging to review the settings in this object. The length of the string can be long.
Example Output:
option 'true' : DKRetrieveOptionsICM(Included={<setting1>,<setting2>,...,<settingN>} Excluded={<setting1>,<setting2>,...,<settingN>})
option 'false': DKRetrieveOptionsICM{<setting1>,<setting2>,...,<settingN>}
WARNING
Do not rely on exact formatting. This string representation is for debugging and logging purposes only. The format and other characteristics can change over time. Applications should not parse this text and rely on the same format in the future. Use the getProjections() method that returns a much better data structure that your application can interpret.
Parameters:
showExcludeList
- If 'true', shows both included and excluded lists clearly identified as shown in the "option 'true'" example above. If 'false', shows only the included list as shown in the "option 'false'" example above.
Returns:
a single-line string description.
The new instance is initialized to the defaults indicated for each setting. Generally, nothing is selected by default. Compared to the old int retrieve options, no selections is equivalent to "IDONLY".
C++
In C++, returned as a pointer to the new instance. Refer to instances only through pointers, which are tolerant to size changes as new retrieve options are added.
RetrieveOption objects cannot be instantiated through constructors in order to ensure binary compatibility when additional options are added in the future that require new member variables. Constructors allow an application to instantiate a variable using a pointer (ex: DKRetrieveOptionsICM retrieveOption() ). Such references are very sensitive to any size change in DKRetrieveOptionsICM which would break an existing compiled application if the size changes in a subsequent fix pack. Therefore, this factory method is provided which hands back pointers. The pointer size does not change and the application is tolerant of any new members or methods added.
PASSING INSTANCE TO RETRIEVE
To use this retrieve options instance with a retrieve call, pass this instance inside DKNVPair[] retrieve options, such as through DKDDO::retrieve(DKNVPair[]) or DKDatastoreICM::retrieveObjects(dkCollection,DKNVPair[]). Specify this instance in a DKNVPair with the name as constant DKConstant.DK_CM_PARM_RETRIEVE and the value as this DKRetrieveOptionsICM instance. For convenience, you can use DKRetrieveOptionsICM::dkNVPair() to return a DKNVPair[] for easy use.
See DKRetrieveOptionsICM::dkNVPair() for much more documentation and examples.