public interface IDfXmlQuery
The structure of the XML output is a root element, specified by setRootTag, followed by each query result row. The following is an example of the XML output:
There are many options available for customizing the XML output, such as specifying the whether object content should be included in the output. Each option has a default value, so you only need to set the options that you want to override.<?xml version="1.0"?> <root> <object ID="09017e1080001932"> <r_object_id>09017e1080001932</r_object_id> <object_name>catalog A</object_name> </object> <object ID="09017e10800019aa"> <r_object_id>09017e10800019aa</r_object_id> <object_name>catalog B</object_name> </object> </root>
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
DF_EXEC_QUERY
Specifies that the query is critical and therefore the session should
be locked.
|
static java.lang.String |
DF_READ_QUERY
Specifies that the query uses only read access (no lock needed).
|
Modifier and Type | Method and Description |
---|---|
void |
execute(int mode,
IDfSession session)
Executes the DQL query and creates a DOM.
|
void |
execute(java.lang.String mode,
IDfSession session)
Deprecated.
Since 5.1.
This method is deprecated to make usage consistent across the IDfXmlQuery and IDfQuery interfaces. |
void |
execute(java.lang.String mode,
java.lang.String sessionId)
Executes the DQL query and creates a DOM.
|
org.w3c.dom.Document |
getXMLDOM()
Returns the XML query results as a DOM.
|
org.w3c.dom.Document |
getXMLDOM(org.w3c.dom.Node start)
Returns the XML document as a DOM with the specified
node as root element.
|
java.lang.String |
getXMLString()
This returns the XML document as a string.
|
java.lang.String |
getXMLString(org.w3c.dom.Node start)
Returns the XML document as a string with Node as root element.
|
void |
getXMLString(java.io.OutputStream outputStream)
Returns the result DOM as String and writes it directly into the
provided OutputStream.
|
void |
getXMLString(java.io.PrintWriter writer)
Returns the result DOM as String and writes it directly into the
provided writer.
|
void |
includeContent(boolean includeContent)
Include the content of the query result.
|
void |
includeDCTMChunkInfo(boolean includeChunkInfo)
Include the Documentum attributes in the returned result.
|
void |
includeMetaData(boolean includeMetaData)
Currently not implemented.
|
void |
init()
Sets the default values for the IDfXmlQuery options.
|
void |
setContentAsLink(boolean contentLink)
Includes a link to the content file, not the content itself.
|
void |
setContentEncoding(java.lang.String encodingType)
Specifies the encoding used for included content.
|
void |
setContentFormat(java.lang.String formatList)
Specify the content rendition to to be returned.
|
void |
setContentTag(java.lang.String tagName)
Sets the element name used to hold the content in the query result.
|
void |
setDql(java.lang.String dqlStatement)
Assigns a DQL statement to a query.
|
void |
setErrorTag(java.lang.String tagName)
Sets the element name used to report errors.
|
void |
setFollowAssembly(boolean followAssembly)
Specifies if the assembly on the root node (if one exists) should be used as the virtual document.
|
void |
setIncludeBrokenBindings(boolean includeBrokenBindings)
Specifies whether to display nodes with broken bindings using the CURRENT label.
|
void |
setLateBindingValue(java.lang.String bindingLabel)
Specify the version label to use to resolve late bound nodes.
|
void |
setLinkBase(java.lang.String base)
Set the base URL for link retrieval of content.
|
void |
setMaxRows(java.lang.Double numberOfRows)
Deprecated.
DFC 5.2.5
The default value is 0 (zero), meaning that all rows will be returned.
indicates the number of elements in the nested structure rather than the number of row elements. |
void |
setMaxRows(int numberOfRows)
Sets the maximum number of rows to return.
|
void |
setMetaDataAsAttributes(boolean includeAsAttr)
Specifies whether object metadata should be returned as XML attribute values.
|
void |
setPreserveSpace(boolean preserve)
Specifies whether the XML content returned in the XDQL output will maintain whitespace characters.
|
void |
setRepeatingAsNested(boolean nested)
Specifies that object metadata with repeating values should be nested.
|
void |
setRepeatingAsNestedTag(java.lang.String tagName)
An extension for nested repeating value element names.
|
void |
setRepeatingIncludeIndex(boolean include)
By default an index number is included in repeating attributes.
|
void |
setRootNode(java.lang.String root)
Sets the element name to use for the root of the XML output.
|
void |
setRowIDAttrName(java.lang.String attrName)
Sets the name of the element attribute that will hold the query result's ID value.
|
void |
setRowIDColumn(java.lang.String column)
Specify the object attribute that contains a unique value for each query result.
|
void |
setRowsetTag(java.lang.String rowset)
Sets the element name to use for each row of the query result.
|
void |
setStyleSheet(java.lang.String stylesheet)
Set stylesheet to use to transform the query results.
|
void |
setVirtualDocumentNested(boolean nested)
Specifies that the results of a virtual document query should be nested.
|
void |
useGivenCaseTagNames()
Leave element names in the given case.
|
void |
useLowerCaseTagNames()
Set element names to lowercase.
|
void |
useNullAttributeIndicator(boolean indicator)
Specifies how an attribute with a null value should be displayed in the XML output.
|
void |
useUpperCaseTagNames()
Set element names to uppercase.
|
static final java.lang.String DF_READ_QUERY
static final java.lang.String DF_EXEC_QUERY
void init()
void setDql(java.lang.String dqlStatement)
Queries are written with the Document Query Language (DQL). Refer to the Server Reference Manual for more information about DQL statements.
According to the features activated (e.g. nesting virtual documents), certain attributes may have to be selected (e.g. "depth").
dqlStatement
- the DQL statementvoid execute(java.lang.String mode, java.lang.String sessionId)
When a transformation is performed using a DFC Transform operation (IDfXMLTransformOperation), the stylesheet is passed a parameter named "DMS_SESSION_ID", which is the string representation of the current session. Pass the value of "DMS_SESSION_ID" to this method.
The following code example demonstrates how to obtain the DMS_SESSION_ID parameter and pass it to execute() within an XSL stylesheet:
<?xml version="1.0"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:java="http://xml.apache.org/xslt/java" version="1.0"> <xsl:output method="xml" indent="yes" media-type="text/xml"/> <!-- pass dctm session as a parameter --> <xsl:param name="DMS_SESSION_ID" select="'default value'"/> <xsl:variable name="xdql" select="java:com.documentum.xml.xdql.DfXmlQuery.new()"/> <xsl:variable name="param" select="java:setDql($xdql,'select * from dm_cabinet')"/> <xsl:variable name="execute" select="java:execute($xdql,'DF_READ_QUERY',$DMS_SESSION_ID)"/> </xsl:stylesheet>
mode
- the query mode (e.g. IDfXmlQuery.DF_READ_QUERY)sessionId
- DFC session identifier that has to be established (connected) before "execute" is called.void execute(int mode, IDfSession session)
Before you call this method, you must assign a DQL statement to the query with
the setDql
method. Refer to the Server Reference Manual
for more information about DQL statements.
The following code example demonstrates how to obtain an IDfXmlQuery interface, set a DQL query, execute the query, and obtain the result:
IDfXmlQuery q = new DfXmlQuery(); q.setDql("select object_name from dm_cabinet"); q.execute(IDfQuery.DF_EXEC_QUERY, sess); FileOutputStream fos = new FileOutputStream("C:\\output.xml"); q.getXMLString(fos); fos.flush(); fos.close();
mode
- the query mode (e.g. IDfQuery.DF_READ_QUERY, IDfQuery.DF_EXEC_QUERY, etc)session
- DFC session that has to be established (connected) before
"execute" is called.void execute(java.lang.String mode, IDfSession session)
mode
- the query mode (e.g. IDfXmlQuery.DF_READ_QUERY)session
- DFC session that has to be established (connected) before "execute" is called.execute(int, IDfSession)
org.w3c.dom.Document getXMLDOM()
org.w3c.dom.Document getXMLDOM(org.w3c.dom.Node start) throws DfException
start
- The root node node of the DOM.DfException
java.lang.String getXMLString(org.w3c.dom.Node start) throws DfException
start
- starting Node for the DOM traversal.DfException
java.lang.String getXMLString() throws DfException
DfException
void setErrorTag(java.lang.String tagName)
If an error occurs during processing, this tag name is used for including error messages. The error element is the top level element and the value contains the Documentum error message. The default tag name is <error>.
The methods of the IDfXmlQuery interface do not throw exceptions. All errors that occur are reported within an <error> element in the output.
tagName
- the name of the element to use to report error messages.void setMaxRows(java.lang.Double numberOfRows)
numberOfRows
- number of rows to return.void setMaxRows(int numberOfRows)
The default value is 0 (zero), meaning that all rows will be returned.
numberOfRows
- number of rows to return.void setRowIDAttrName(java.lang.String attrName)
Each row returned in a query result must return an object attribute that has a unique value. Typically, this attribute will be r_object_id.
Call setRowIDAttrName to specify the name of the element attribute that will hold the unique ID. The default attribute name is ID.
This example shows that the row ID attribute name is RowId:
<?xml version="1.0"?> <root> <object RowId="09017e1080001932"> <r_object_id>09017e1080001932</r_object_id> <object_name>catalog A</object_name> </object> <object RowId="09017e10800019aa"> <r_object_id>09017e10800019aa</r_object_id> <object_name>catalog B</object_name> </object> </root>
attrName
- the element attribute name.void setRowIDColumn(java.lang.String column)
Each row returned in a query result must return an object attribute that has a unique value. Typically, this attribute will be r_object_id.
Call setRowIDColumn to specify the name of the object attribute contains a unique value. The default object attribute name is r_object_id.
This example shows that the object attribute name is r_object_id:
<?xml version="1.0"?> <root> <object ID="09017e1080001932"> <r_object_id>09017e1080001932</r_object_id> <object_name>catalog A</object_name> </object> <object ID="09017e10800019aa"> <r_object_id>09017e10800019aa</r_object_id> <object_name>catalog B</object_name> </object> </root>
column
- Name of the object attribute that uniquely identifies an object.setDql(String)
void setRootNode(java.lang.String root)
The default element name is root unless an error occurs. In the case of an error,
the root element is error, or whatever has been specified with setErrorTag
.
This example shows that the root element name is QueryOutput:
<?xml version="1.0"?> <QueryOutput> <object ID="09017e1080001932"> <r_object_id>09017e1080001932</r_object_id> <object_name>catalog A</object_name> </object> <object ID="09017e10800019aa"> <r_object_id>09017e10800019aa</r_object_id> <object_name>catalog B</object_name> </object> </QueryOutput>
root
- name of the element to use as the root.setErrorTag(String)
void setRowsetTag(java.lang.String rowset)
Each object returned in the query result set is represented by an element of this name.
The default element name is object.
This example shows that the element name for each query result is row:
<?xml version="1.0"?> <root> <row ID="09017e1080001932"> <r_object_id>09017e1080001932</r_object_id> <object_name>catalog A</object_name> </row> <row ID="09017e10800019aa"> <r_object_id>09017e10800019aa</r_object_id> <object_name>catalog B</object_name> </row> </root>
rowset
- name of the element to use for each query result.setRootNode(String)
void setStyleSheet(java.lang.String stylesheet)
Set a stylesheet in order to transform the query result when getXMLString(PrintWriter)
or getXMLString(OutputStream) is called.
The parameter is either a valid r_object_id
, a valid repository folder-path
in the form of a DRL (starting with "dctm://") or a URL (starting with "http://").
stylesheet
- address of a stylesheet (r_object_id, repository-path or URL)void useLowerCaseTagNames()
When this method is called, all element names will be displayed in lowercase.
The default behavior is to not modify the given case.
useUpperCaseTagNames()
,
useGivenCaseTagNames()
void useUpperCaseTagNames()
When this method is called, all element names will be displayed in uppercase.
The default behavior is to not modify the given case.
useLowerCaseTagNames()
,
useGivenCaseTagNames()
void useGivenCaseTagNames()
This is the default behavior.
Use this method to override a previous call to useUpperCaseTagNames or useLowerCaseTagNames.
useUpperCaseTagNames()
,
useLowerCaseTagNames()
void useNullAttributeIndicator(boolean indicator)
If useNullAttributeIndicator is true, the value "null is used. If useNullAttributeIndicator is false, an empty element is returned.
The default value is false.
This example shows the output for an attribute that has a null value and useNullAttributeIndicator(true):
This example shows the output for an attribute that has a null value and useNullAttributeIndicator(false):<?xml version="1.0"?> <root> <row ID="09017e1080001932"> <r_object_id>09017e1080001932</r_object_id> <object_name>catalog A</object_name> <subject>null</subject> </row> </root>
<?xml version="1.0"?> <root> <row ID="09017e1080001932"> <r_object_id>09017e1080001932</r_object_id> <object_name>catalog A</object_name> <subject/> </row> </root>
indicator
- Specifies whether null attribute values should be displayed.void includeContent(boolean includeContent)
The query must include r_object_id in the query, if the content is to be included. The content is returned within a <content> element, or whatever element is specified by setContentTag.
The default behavior is to not include the content.
This example shows the output that includes the query result content:
<?xml version="1.0"?> <root> <object ID="09017e1080002ab0"> <r_object_id>09017e1080002ab0</r_object_id> <object_name>catalogShiftJIS</object_name> <content encoding="dom" mime-type="text/xml"> <cellphone-catalog> <model> <model.name>Q-3200</model.name> <brand.name>??-Quasivox</brand.name> </model> </cellphone-catalog> </content> </object> </root>
includeContent
- Indicates whether object content should be included.setContentFormat(String)
,
setContentEncoding(String)
,
setContentTag(String)
,
setContentAsLink(boolean)
void includeDCTMChunkInfo(boolean includeChunkInfo)
When including the content of the query results, you can specify whether the Documentum attributes should be included. The default behavior is to not include the Documentum attributes.
This example shows the output that includes the Documentum attributes in the query result content:
<?xml version="1.0"?> <root> <object ID="09017e1080002ab0"> <r_object_id>09017e1080002ab0</r_object_id> <object_name>catalogShiftJIS</object_name> <content encoding="dom" mime-type="text/xml"> <cellphone-catalog dctm:obj_id="09017e1080002abe" dctm:obj_status="Read-Only" dctm:version_label="CURRENT" xmlns:dctm="http://www.documentum.com"> <model> <model.name>Q-3200</model.name> <brand.name>??-Quasivox</brand.name> </model> </cellphone-catalog> </content> </object> </root>
includeChunkInfo
- Include Documentum attributes in object content.void includeMetaData(boolean includeMetaData)
includeMetaData
- N/Avoid setContentFormat(java.lang.String formatList)
When the content of the query results is being included, you can specify the format name of the rendition to be used. To return multiple renditions, specify a comma seperated list or format names or "*" to have the primary content returned. If the content is not found an <error> is returned.
formatList
- Comma-separated list of formats or "*"includeContent(boolean)
,
setContentEncoding(String)
,
setContentTag(String)
,
setContentAsLink(boolean)
void setContentTag(java.lang.String tagName)
The default element is <content>. The content element has the following attributes:
tagName
- StringincludeContent(boolean)
,
setContentFormat(String)
,
setContentEncoding(String)
,
setContentAsLink(boolean)
void setContentEncoding(java.lang.String encodingType)
If the object content is a binary format (e.g. jpeg), set the content encoding to base64.
If the object content is XML content, encoding can be set to none, xml, or dom.
The default content encoding is base64
encodingType
- content encoding value: base64, none, xml or dom.includeContent(boolean)
,
setContentFormat(String)
,
setContentTag(String)
,
setContentAsLink(boolean)
void setContentAsLink(boolean contentLink)
When including the query result content, the content can be specified as a DRL or URL link. The URL syntax is:
($base)DMW_OBJECTID=($r_object_id)&DMW_FORMAT=($format)
$base must be set with "setLinkBase(base)"dctm://<docbase name:gt;/<object ID>?DMS_OBJECT_SPEC=OBJECT_ID
contentLink
- include the content as a link.includeContent(boolean)
,
setContentFormat(String)
,
setContentTag(String)
,
setContentEncoding(String)
,
setLinkBase(String)
void setLinkBase(java.lang.String base)
For example, you can use Rightsite to retrieve the content with the following base URL.
URL: http://host:port/rs-bin/RightSite.dll/getcontent/foo.htm?...
The link base can also be specified as a DRL:
DRL: dctm://<docbase name>
base
- Stringvoid setVirtualDocumentNested(boolean nested)
If false, virtual document query results will be returned as elements at the same level. If true, the virtual document query must include the 'depth' attribute, in order to be nested.
nested
- nest virtual document query results.setMaxRows(java.lang.Double)
void setRepeatingIncludeIndex(boolean include)
include
- booleanvoid setRepeatingAsNested(boolean nested)
Set to true by default, this will nest repeating attributes, adding the nested attribute name to the element names of the child elements.
nested
- nest repeating elements.setRepeatingAsNestedTag(String)
void setRepeatingAsNestedTag(java.lang.String tagName)
<keywords> <keywords-value>aaaaaa</keywords-value> <keywords-value>bbbbbb</keywords-value> </keywords>Default is "-value".
tagName
- extension namesetRepeatingAsNested(boolean)
void setMetaDataAsAttributes(boolean includeAsAttr)
The default behavior is to express metadata as elements, not attributes.
Repeating attributes are always element values.
includeAsAttr
- return object metadata as XML attributesvoid setLateBindingValue(java.lang.String bindingLabel)
When virtual documents are returned as part of the query, this method specifies how late bound nodes should be resolved.
Default is to return nodes with the CURRENT symbolic label.
bindingLabel
- - the symbolic version label to use to resolve late bound nodesvoid setIncludeBrokenBindings(boolean includeBrokenBindings)
includeBrokenBindings
- - set this to true if you want the server to attempt to resolvevoid setFollowAssembly(boolean followAssembly)
The default behavior is to not follow the assembly on the root document (if one is present).
followAssembly
- if true, the assembly specified by the root node will be used as the "virtual" document.void getXMLString(java.io.PrintWriter writer) throws DfException
writer
- Writer to contain the XML output.DfException
- Returns an exception if there is a non-valid XSL (style-sheet) was specified.getXMLDOM()
,
getXMLDOM(Node)
,
getXMLString(Node)
,
getXMLString()
,
getXMLString(java.io.PrintWriter)
void getXMLString(java.io.OutputStream outputStream) throws DfException
outputStream
- OutputStream to contain the XML output.DfException
- Returns an exception if there a non-valid XSL (style-sheet) was specified.getXMLDOM()
,
getXMLDOM(Node)
,
getXMLString(Node)
,
getXMLString()
,
getXMLString(java.io.PrintWriter)
void setPreserveSpace(boolean preserve)
preserve
- Set to true if whitespace characters should be maintained.Copyright 1994-2023 OpenText Corporation. All rights reserved.