Introduction
In order to manage potential reader expectations, it should be noted
that this article is intended to provide a flavour of XDQL and its
capabilities. XDQL provides a useful piece of bridging technolgy
between abstract query languages and the data representation language
that is XML. XML is closely coupled to XSLT and, in many applications,
to web-based output that is the result of transforming XML input into
a more palatable form. However, this article only addresses calling
XDQL from within a DFC environment. It does not address (for example)
calling XDQL from within an XSL stylesheet, or using XDSL from within
a web-application that is being used to view docbase content.
The Documentum Query Language, DQL, is a specific dialect of
Structured Query Language (SQL). It allows a caller to request
information about the internal tables that live in the database that
underpins Documentum. Conceptually, these tables are arranged as rows
of information, where the position of each column in the row indicates
a particular property. Through DQL, the caller may select some or all
rows from a table, and request that the values found in particular
columns be returned. So far, so very ordinary.
The main issue with DQL is that manipulating the information returned
as the result of executing a query is not straitforward. It is quite
hard to separate the task of fetching the information from the task of
processing it. It would certainly be difficult to perform a DQL query
(from a DFC java program) and then pass the resulting Collection
object to another programmer who didnt already know about DFC.
XDQL provides a way around these issues by taking the results of a
query and returning them as an XML structure, or document. Now XML is
not necessarily any more human-readable than DQL, but it has the major
advantage that it is a well accepted standard that is specifically
targetted at representing data, and that is precisely what the results
of executing a query are.
Further, XML is closely allied to several related technolgies such as
XSL and XPATH, both of which allow programs to process XML input in
order to either transform it or to extract subsets of the information
contained within it. This then is the power of XDQL. It is that it
allows the programmer to make use of the vast efforts that have been
poured into standard XML processing tools, and use these well-known
technologies to manipulate the results of querying the docbase.
By separating the results from their means of production, it becomes
possible to turn over major pieces of programming to groups that have
no knowledge of Documentum or DFC. Since the query results are
presented as well-formed XML document object, there is no need for the
group responsible for processing them to make any reference to DFC
whatsoever. By using XDQL it is possible to achieve separation between
the collection of data and its presentation.
Of course, tools are not generally useful in and of themselves. Their
value lies in the things that they allow their users to
achieve. Further, the usefulness of a tool has to be measured in terms
of its applicability to the task being considered. After all, a 5lb
sledgehammer is very useful when knocking walls down, but much less
handy when the user is repairing a watch.
General Features of an XDQL Query
Here is a snippet of java code that performs an XDQL query.
String queryText = "select *, keywords from dm_document where object_name = 'sample'";
DfXmlQuery query = new DfXmlQuery ();
query.init ();
query.setDql(queryText);
query.execute(DfXmlQuery.DF_READ_QUERY, session);
returns the following (as a string):
<?xml version="1.0" encoding="UTF-8"?>
<root>
<object ID="090f4634800198f2">
<r_object_id>090f4634800198f2</r_object_id>
<object_name>sample</object_name>
<title>sample title</title>
<subject>sample subject</subject>
<resolution_label></resolution_label>
<owner_name>/articles/dmin</owner_name>
<owner_permit>7</owner_permit>
<group_name>docu</group_name>
<group_permit>1</group_permit>
<world_permit>3</world_permit>
<log_entry></log_entry>
<acl_domain>/articles/dmin</acl_domain>
<acl_name>/articles/dmin_acl</acl_name>
<language_code></language_code>
<r_object_type>dm_document</r_object_type>
<r_creation_date>12/5/2001 01:41:41 PM</r_creation_date>
<r_modify_date>12/18/2001 02:15:00 PM</r_modify_date>
<a_content_type>xml</a_content_type>
<keywords>keyword#2</keywords>
<keywords>keyword#1</keywords>
</object>
</root>
It is possible to tailor the generated XML by specifying the root node
tag (defaults to <root>, the row tag (defaults to <object>), the name
and value for the row name (defaults to ‘ID’ and the value of
‘r_object_id’).
So, adding the following code to the above example:
query.setRowsetTag("RowsetTag"); // overrides 'object'
query.setRowIDColumn("object_name"); // overrides default 'r_object_id'
query.setRowIDAttrName("RowIDAttrName"); // overrides default 'ID'
query.useUpperCaseTagNames(); // overrides default 'useGivenCaseNames'
query.setRootNode("RootNode"); // overrides 'root'
produces the following output:
<?xml version="1.0" encoding="UTF-8"?>
<ROOTNODE>
<ROWSETTAG ROWIDATTRNAME="sample">
<R_OBJECT_ID>090f4634800198f2</R_OBJECT_ID>
<OBJECT_NAME>sample</OBJECT_NAME>
<TITLE>sample title</TITLE>
<SUBJECT>sample subject</SUBJECT>
<RESOLUTION_LABEL></RESOLUTION_LABEL>
<OWNER_NAME>/articles/dmin</OWNER_NAME>
<OWNER_PERMIT>7</OWNER_PERMIT>
<GROUP_NAME>docu</GROUP_NAME>
<GROUP_PERMIT>1</GROUP_PERMIT>
<WORLD_PERMIT>3</WORLD_PERMIT>
<LOG_ENTRY></LOG_ENTRY>
<ACL_DOMAIN>/articles/dmin</ACL_DOMAIN>
<ACL_NAME>/articles/dmin_acl</ACL_NAME>
<LANGUAGE_CODE></LANGUAGE_CODE>
<R_OBJECT_TYPE>dm_document</R_OBJECT_TYPE>
<R_CREATION_date>12/5/2001 01:41:41 PM</R_CREATION_date>
<R_MODIFY_date>12/18/2001 02:15:00 PM</R_MODIFY_date>
<A_CONTENT_TYPE>xml</A_CONTENT_TYPE>
<KEYWORDS>keyword#2</KEYWORDS>
<KEYWORDS>keyword#1</KEYWORDS>
</ROWSETTAG>
</ROOTNODE>
It is possible to have all of the object metadata returned as
attributes of the row object, rather than as elements as in the above
example. This can be done by:
query.setMetaDataAsAttributes(true);
producing the following:
<?xml version="1.0" encoding="UTF-8"?>
<ROOTNODE>
<ROWSETTAG ACL_DOMAIN="/articles/dmin" ACL_NAME="/articles/dmin_acl"
A_CONTENT_TYPE="xml" GROUP_NAME="docu" GROUP_PERMIT="1"
LANGUAGE_CODE="" LOG_ENTRY="" OBJECT_NAME="sample"
OWNER_NAME="/articles/dmin" OWNER_PERMIT="7" RESOLUTION_LABEL=""
ROWIDATTRNAME="sample" R_CREATION_DATE="12/5/2001 01:41:41 PM"
R_MODIFY_DATE="12/18/2001 02:15:00 PM"
R_OBJECT_ID="090f4634800198f2" R_OBJECT_TYPE="dm_document"
SUBJECT="sample subject" TITLE="sample title" WORLD_PERMIT="3">
<KEYWORDS>keyword#2</KEYWORDS>
<KEYWORDS>keyword#1</KEYWORDS>
</ROWSETTAG>
</ROOTNODE>
In order to get an index value for repeating attributes (such as the
‘keywords’ attribute) use:
query.setRepeatingIncludeIndex(true);
with the following results:
<KEYWORDS INDEX="0">keyword#2</KEYWORDS>
<KEYWORDS INDEX="1">keyword#1</KEYWORDS>
Fetching Content with an XDQL Query
A useful, although slightly quirky feature of XDQL is its capacity to
fetch the contents of a selection and return that as (amongst other
options) an XML document. while it is demonstrably possible to extract
content from the docbase, this is usually performed through specific
Documentum API calls. Usually this content retrieval is a multi-stage
process, with the first stage being the execution of a query and the
second stage being to fetch the content from the selected
objects. With XDQL these two stages are coalesced into a single stage,
with the added bonus that the contents are presented in a form
suitable for further processing.
In order to indicate that the XDQL call should return any document
content, the ‘fetchContent’ flag must be set. Also, one of the
returned attributes has to be the r_object_id of the
object.
The content encoding value needs to be set. The potential values that
may be used are ‘base64’, ‘none’, ‘xml’ and ‘dom’. An approximate
mapping for these values would be:
- base64 – for binary information
- none – for XML content
- xml – for XML content encoding special characters as entities
- dom – for XML content being included for further parsing
The content format value needs to be specified. This can be any
defined docbase format, a comma-separated list of docbase formats, or
‘*’ to indicate a default format.
query.setContentEncoding("dom");
query.setContentFormat("xml");
query.includeContent(true);
returns the following additional XML fragment:
<CONTENT ENCODING="dom" MIME-TYPE="text/xml">
<book>
<price>16.00</price>
<author>H.G. Wells</author>
<title>War of the Worlds</title>
</book>
</CONTENT>
By changing the content encoding to ‘base64’, the (reformatted)
fragment becomes:
<CONTENT ENCODING="base64"
MIME-TYPE="text/xml">PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iV
VRGLTgiPz4NCjxQcmljaW5nPg0KCTxDb3N0
PjIxNi4wMDwvQ29zdD4gDQoJPFdob2xlc2FsZT40MDAuMDA8L1dob2xlc2
FsZT4gDQoJPE1TUlA+ Njk5Ljk1PC9NU1JQPiANCjwvUHJpY2luZz4NCg==</CONTENT>
Querying Virtual Documents
An XDQL query can be constructed to extract the composition of Virtual
Document. By constructing a standard query to return some or all of
the attributes of the components of a Virtual Document, these can be
rendered into XML in the usual way.
Running the following query against a docbase containing a simple
virtual document returns the follow results:
String queryText = "select r_object_id, object_name, DEPTH from dm_document
in document id('090f46348000751d') descend";
<?xml version="1.0" encoding="UTF-8"?>
<root>
<object ID="090f46348000751d">
<r_object_id>090f46348000751d</r_object_id>
<object_name>doc1</object_name>
<depth>0</depth>
<object ID="090f463480006a2b">
<r_object_id>090f463480006a2b</r_object_id>
<object_name>doc3</object_name>
<depth>1</depth>
</object>
</object>
</root>
Stylesheet Application
The XDQL mechanism can also apply a stylesheet to the results of the
query. The stylesheet may be specified either by r_object_id, a valid
absolute folder-path or a URL.
query.setStyleSheet(“/import/test/stylesheet”);
The transformation is applied on the getXMLString(PrintWriter)
method of query object.
Limitations
XDQL was introduced in DFC 4.2, and unlike much of DFC does not have a
COM wrapper, making it inaccessible from Visual Basic, C++ and other
common scripting environments. In order to make an XDQL query, the
call needs to be made from within a Java Virtual Machine – that is,
from a java program. However, since most of the power of XDQL comes
from its ability to interoperate with XSLT, which also requires a java
environment, this limitation is not too restrictive.
XDQL is pretty good at rendering Documentum attributes as XML
attributes, and XML content in the docbase as DOM content. However, it
is not a magical tool for taking arbitrary text content and turning it
into XML. To an extent, if you wish to use XDQL fully, you should
already be storing content as XML documents.
The DFC jar embeds the Xerxes XML parsing technology and Xalan XSL
transformation technology from Apache. This makes replacing these
components with other XML parsers and transformers non-trivial.
Example
By way of illustration, let’s assume that a company keeps its
financial records as XML documents in the docbase. These individual
documents may be segmented internally through tags into sections such as
Debtors, Profit and Loss and Inventory. Each month a fresh document is
generated and placed in the docbase.
Now, in order to generate reports for circulation every quarter, or at
the end of the financial year, all that is needed is a simple program
to run an XDQL query that selects all of the finance documents for the
period in question and then applies the appropriate XSL stylesheets
(also stored in the docbase).
The stylesheet output, possibly in the form of one or more HTML
documents, may then also be stored in the docbase (protected by ACLs)
for viewing whenever necessary. Should a new report be required, and
the raw information is already present in the docbase, then all that
is necessary is for a new XSL stylesheet to be prepared and added to
the set. Of course, the simple driver program can always use DQL or
XDQL to determine the set of stylesheets to be applied.
The above example places the ‘intelligence’ – the queries – in the
driver program. While the query information has to be held somewhere,
there are in fact several alternative places that it could be
held. For example, the query could be formed and executed by the XSL
stylesheet, or stored in the docbase and found by an initial, much
simpler query. Decisions such as these are a matter of programming
style and taste. As with any tool, XDQL can be used in a wide variety
of ways and with varying degrees of effectiveness. Used well, and in
the right application, XDQL is undoubtedly a powerful addition to the
Documentum tool set.
