Package com.documentum.xml.xdql

Interface IDfXmlQuery

public interface IDfXmlQuery

This interface provides functionality for running queries against a repository, returning the results as XML.

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:

 <?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>
 

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.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	DF_EXEC_QUERY	Specifies that the query is critical and therefore the session should be locked.
static final String	DF_READ_QUERY	Specifies that the query uses only read access (no lock needed).

Method Summary

Modifier and Type	Method	Description
void	execute(int mode, IDfSession session)	Executes the DQL query and creates a DOM.
void	execute(String mode, IDfSession session)	Deprecated. Since 5.1. This method is deprecated to make usage consistent across the IDfXmlQuery and IDfQuery interfaces.
void	execute(String mode, String sessionId)	Executes the DQL query and creates a DOM. Use this method when executing the query within an XSL stylesheet.
Document	getXMLDOM()	Returns the XML query results as a DOM.
Document	getXMLDOM(Node start)	Returns the XML document as a DOM with the specified node as root element.
String	getXMLString()	This returns the XML document as a string.
void	getXMLString(OutputStream outputStream)	Returns the result DOM as String and writes it directly into the provided OutputStream.
void	getXMLString(PrintWriter writer)	Returns the result DOM as String and writes it directly into the provided writer.
String	getXMLString(Node start)	Returns the XML document as a string with Node as root element.
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(String encodingType)	Specifies the encoding used for included content.
void	setContentFormat(String formatList)	Specify the content rendition to to be returned.
void	setContentTag(String tagName)	Sets the element name used to hold the content in the query result.
void	setDql(String dqlStatement)	Assigns a DQL statement to a query.
void	setErrorTag(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. Broken bindings can occur when the query requests a version of the node that doesn't exist. XDQL can return such nodes using the CURRENT version of the node.
void	setLateBindingValue(String bindingLabel)	Specify the version label to use to resolve late bound nodes.
void	setLinkBase(String base)	Set the base URL for link retrieval of content.
void	setMaxRows(int numberOfRows)	Sets the maximum number of rows to return.
void	setMaxRows(Double numberOfRows)	Deprecated. DFC 5.2.5 The default value is 0 (zero), meaning that all rows will be returned.
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(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(String root)	Sets the element name to use for the root of the XML output.
void	setRowIDAttrName(String attrName)	Sets the name of the element attribute that will hold the query result's ID value.
void	setRowIDColumn(String column)	Specify the object attribute that contains a unique value for each query result.
void	setRowsetTag(String rowset)	Sets the element name to use for each row of the query result.
void	setStyleSheet(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.

Field Details

DF_READ_QUERY

static final String DF_READ_QUERY

Specifies that the query uses only read access (no lock needed).

See Also:

• Constant Field Values

DF_EXEC_QUERY

static final String DF_EXEC_QUERY

Specifies that the query is critical and therefore the session should be locked.

See Also:

• Constant Field Values

Method Details

init

void init()

Sets the default values for the IDfXmlQuery options.

setDql

void setDql(String dqlStatement)

Assigns a DQL statement to a query.

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").

Parameters:

dqlStatement - the DQL statement

execute

void execute(String mode,
 String sessionId)

Executes the DQL query and creates a DOM.
Use this method when executing the query within an XSL stylesheet.

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>
 

Parameters:

mode - the query mode (e.g. IDfXmlQuery.DF_READ_QUERY)

sessionId - DFC session identifier that has to be established (connected) before "execute" is called.

execute

void execute(int mode,
 IDfSession session)

Executes the DQL query and creates a DOM.

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();
 

Parameters:

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.

execute

void execute(String mode,
 IDfSession session)

Deprecated.

Since 5.1.
This method is deprecated to make usage consistent across the IDfXmlQuery and IDfQuery interfaces.

Executes the DQL query and creates a DOM.

Parameters:

mode - the query mode (e.g. IDfXmlQuery.DF_READ_QUERY)

session - DFC session that has to be established (connected) before "execute" is called.

See Also:

• execute(int, IDfSession)

getXMLDOM

Document getXMLDOM()

Returns the XML query results as a DOM.

Returns:

The result as a DOM (class Document)

getXMLDOM

Document getXMLDOM(Node start)
            throws DfException

Returns the XML document as a DOM with the specified node as root element.

Parameters:

start - The root node node of the DOM.

Returns:

The result as a DOM (class Document, starting at the indicated Node)

Throws:

DfException

getXMLString

String getXMLString(Node start)
             throws DfException

Returns the XML document as a string with Node as root element.

Parameters:

start - starting Node for the DOM traversal.

Returns:

The result as a String, starting with Node as the root element.

Throws:

DfException

getXMLString

String getXMLString()
             throws DfException

This returns the XML document as a string.

Returns:

The resulting DOM as a String.

Throws:

DfException

setErrorTag

void setErrorTag(String tagName)

Sets the element name used to report errors.

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.

Parameters:

tagName - the name of the element to use to report error messages.

setMaxRows

void setMaxRows(Double numberOfRows)

Deprecated.

DFC 5.2.5 The default value is 0 (zero), meaning that all rows will be returned.

NOTE 1: the result DOM is loaded into memory
NOTE 2: with virtual documents (in nested representation) MaxRows
indicates the number of elements in the nested structure rather than
the number of row elements.

Sets the maximum number of rows to return.

Parameters:

numberOfRows - number of rows to return.

setMaxRows

void setMaxRows(int numberOfRows)

Sets the maximum number of rows to return.

The default value is 0 (zero), meaning that all rows will be returned.

NOTE 1: the result DOM is loaded into memory

NOTE 2: with virtual documents (in nested representation) MaxRows
indicates the number of elements in the nested structure rather than
the number of row elements.

Parameters:

numberOfRows - number of rows to return.

setRowIDAttrName

void setRowIDAttrName(String attrName)

Sets the name of the element attribute that will hold the query result's ID value.

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>
 

Parameters:

attrName - the element attribute name.

setRowIDColumn

void setRowIDColumn(String column)

Specify the object attribute that contains a unique value for each query result.

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>
 

Parameters:

column - Name of the object attribute that uniquely identifies an object.

See Also:

• setDql(String)

setRootNode

void setRootNode(String root)

Sets the element name to use for the root of the XML output.

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>
 

Parameters:

root - name of the element to use as the root.

See Also:

• setErrorTag(String)

setRowsetTag

void setRowsetTag(String rowset)

Sets the element name to use for each row of the query result.

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>
 

Parameters:

rowset - name of the element to use for each query result.

See Also:

• setRootNode(String)

setStyleSheet

void setStyleSheet(String stylesheet)

Set stylesheet to use to transform the query results.

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://").

Parameters:

stylesheet - address of a stylesheet (r_object_id, repository-path or URL)

useLowerCaseTagNames

void useLowerCaseTagNames()

Set element names to lowercase.

When this method is called, all element names will be displayed in lowercase.
The default behavior is to not modify the given case.

See Also:

• useUpperCaseTagNames()
• useGivenCaseTagNames()

useUpperCaseTagNames

void useUpperCaseTagNames()

Set element names to uppercase.

When this method is called, all element names will be displayed in uppercase.
The default behavior is to not modify the given case.

See Also:

• useLowerCaseTagNames()
• useGivenCaseTagNames()

useGivenCaseTagNames

void useGivenCaseTagNames()

Leave element names in the given case.

This is the default behavior.
Use this method to override a previous call to useUpperCaseTagNames or useLowerCaseTagNames.

See Also:

• useUpperCaseTagNames()
• useLowerCaseTagNames()

useNullAttributeIndicator

void useNullAttributeIndicator(boolean indicator)

Specifies how an attribute with a null value should be displayed in the XML output.

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):

 <?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>
 

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/>
     </row>
 </root>
 

Parameters:

indicator - Specifies whether null attribute values should be displayed.

includeContent

void includeContent(boolean includeContent)

Include the content of the query result.

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>
 

Parameters:

includeContent - Indicates whether object content should be included.

See Also:

• setContentFormat(String)
• setContentEncoding(String)
• setContentTag(String)
• setContentAsLink(boolean)

includeDCTMChunkInfo

void includeDCTMChunkInfo(boolean includeChunkInfo)

Include the Documentum attributes in the returned result.

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>
 

Parameters:

includeChunkInfo - Include Documentum attributes in object content.

includeMetaData

void includeMetaData(boolean includeMetaData)

Currently not implemented.

Parameters:

includeMetaData - N/A

setContentFormat

void setContentFormat(String formatList)

Specify the content rendition to to be returned.

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.

Parameters:

formatList - Comma-separated list of formats or "*"

See Also:

• includeContent(boolean)
• setContentEncoding(String)
• setContentTag(String)
• setContentAsLink(boolean)

setContentTag

void setContentTag(String tagName)

Sets the element name used to hold the content in the query result.

The default element is <content>. The content element has the following attributes:

format

mime-type

encoding

Parameters:

tagName - String

See Also:

• includeContent(boolean)
• setContentFormat(String)
• setContentEncoding(String)
• setContentAsLink(boolean)

setContentEncoding

void setContentEncoding(String encodingType)

Specifies the encoding used for included content.

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

Parameters:

encodingType - content encoding value: base64, none, xml or dom.

See Also:

• includeContent(boolean)
• setContentFormat(String)
• setContentTag(String)
• setContentAsLink(boolean)

setContentAsLink

void setContentAsLink(boolean contentLink)

Includes a link to the content file, not the content itself.

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)"
If "setLinkBase" is not called, the link will be a DRL. The syntax of the DRL is:

 dctm://<docbase name:gt;/<object ID>?DMS_OBJECT_SPEC=OBJECT_ID
 

Parameters:

contentLink - include the content as a link.

See Also:

• includeContent(boolean)
• setContentFormat(String)
• setContentTag(String)
• setContentEncoding(String)
• setLinkBase(String)

setLinkBase

void setLinkBase(String base)

Set the base URL for link retrieval of content.

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>
 

Parameters:

base - String

setVirtualDocumentNested

void setVirtualDocumentNested(boolean nested)

Specifies that the results of a virtual document query should be 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.

Parameters:

nested - nest virtual document query results.

See Also:

• setMaxRows(java.lang.Double)

setRepeatingIncludeIndex

void setRepeatingIncludeIndex(boolean include)

By default an index number is included in repeating attributes.

Parameters:

include - boolean

setRepeatingAsNested

void setRepeatingAsNested(boolean nested)

Specifies that object metadata with repeating values should be nested.

Set to true by default, this will nest repeating attributes, adding the nested attribute name to the element names of the child elements.

Parameters:

nested - nest repeating elements.

See Also:

• setRepeatingAsNestedTag(String)

setRepeatingAsNestedTag

void setRepeatingAsNestedTag(String tagName)

An extension for nested repeating value element names.

 <keywords>
     <keywords-value>aaaaaa</keywords-value>
     <keywords-value>bbbbbb</keywords-value>
 </keywords>

Default is "-value".

Parameters:

tagName - extension name

See Also:

• setRepeatingAsNested(boolean)

setMetaDataAsAttributes

void setMetaDataAsAttributes(boolean includeAsAttr)

Specifies whether object metadata should be returned as XML attribute values.

The default behavior is to express metadata as elements, not attributes.
Repeating attributes are always element values.

Parameters:

includeAsAttr - return object metadata as XML attributes

setLateBindingValue

void setLateBindingValue(String bindingLabel)

Specify the version label to use to resolve late bound nodes.

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.

Parameters:

bindingLabel - - the symbolic version label to use to resolve late bound nodes

setIncludeBrokenBindings

void setIncludeBrokenBindings(boolean includeBrokenBindings)

Specifies whether to display nodes with broken bindings using the CURRENT label.
Broken bindings can occur when the query requests a version of the node that doesn't exist.
XDQL can return such nodes using the CURRENT version of the node. To require this behavior,
execute this method and pass includeBrokenBindings as true.
If the setIncludeBrokenBindings flag is set to false, nodes with broken bindings are not returned.
Default is to include broken bindings.
.

Parameters:

includeBrokenBindings - - set this to true if you want the server to attempt to resolve
broken bindings using the CURRENT label. Set this to false to omit nodes with broken bindings.

setFollowAssembly

void setFollowAssembly(boolean followAssembly)

Specifies if the assembly on the root node (if one exists) should be used as the virtual document.

The default behavior is to not follow the assembly on the root document (if one is present).

Parameters:

followAssembly - if true, the assembly specified by the root node will be used as the "virtual" document.

getXMLString

void getXMLString(PrintWriter writer)
           throws DfException

Returns the result DOM as String and writes it directly into the provided writer.

Parameters:

writer - Writer to contain the XML output.

Throws:

DfException - Returns an exception if there is a non-valid XSL (style-sheet) was specified.

See Also:

• getXMLDOM()
• getXMLDOM(Node)
• getXMLString(Node)
• getXMLString()
• getXMLString(java.io.PrintWriter)

getXMLString

void getXMLString(OutputStream outputStream)
           throws DfException

Returns the result DOM as String and writes it directly into the provided OutputStream.

Parameters:

outputStream - OutputStream to contain the XML output.

Throws:

DfException - Returns an exception if there a non-valid XSL (style-sheet) was specified.

See Also:

• getXMLDOM()
• getXMLDOM(Node)
• getXMLString(Node)
• getXMLString()
• getXMLString(java.io.PrintWriter)

setPreserveSpace

void setPreserveSpace(boolean preserve)

Specifies whether the XML content returned in the XDQL output will maintain whitespace characters.

Parameters:

preserve - Set to true if whitespace characters should be maintained.