SMILA/Documentation/XQJ Implementation

Summary

This page specifies the IT-Design and Guidelines for the XQJ (JSR-225) implementation furthermore referenced as Bdx – XQJ Implementation within this web page. The Bdx XQJ Implementation will make possible for final Java clients to use the XQJ API in order to access the Oracle Berkeley DB Xml (“embeddable XML database with XQuery based access to documents stored in containers and indexed based on their content”).

Bdx XQJ Implementation Overview

The architecture does interface data from Oracle Berkeley DB Xml to end Java clients based on the XQJ (JSR-225) specifications. The following picture outlines a simplified overview of the structure together with the focus for this document.

Bdx XQJ implementation provides part of the XQJ functionality, especially for the query support.

UML Class Diagrams

• XQJ (JSR-225) – class diagram

Fallowing two class diagrams represent the XQJ architecture as defined by the JSR-225 (http://jcp.org/en/jsr/detail?id=225)

• • XQJ Class Diagram 1

• • XQJ Class Diagram 2

Bdx XQJ Implementation

The following class diagram represents the current state of the Bdx XQJ implementation, considering as a basic priority the query functionality. Currently not all the XQJ interfaces (functionalities) have been implemented – only the necessary operations that provide query support.

Bdx XQJ Implementation – data type hierarchy

Bdx XQJ implementation provides its own type – value hierarchy for data representation. The type hierarchy is only internal used.

Currently not all the data types (values) have been implemented; just the necessary types in order to support the main querying operations for few basic XS data types.

Bdx XQJ Implementation characteristics

Package structure & nomenclature

The base package of the Bdx XQJ Implementation is: org.eclipse.eilf.xmlstorage.internal.xquery.bdx. Most of the Bdx XQJ implementation sources follow the next naming format:

• for concrete implementation of XQJ interfaces: BdxXQNameImpl;
• for sources that support the basic XQJ implementation: BdxName
• there are also sources with only the concrete class name

The type – value hierarchy implementation sources follow the next naming format:

• sources representing types: XQTypeNameType, BdxNameType
• sources representing values: XQValueNameValue

Sub-packages details:

• org.eclipse.eilf.xmlstorage.internal.xquery.bdx: contains the implementation classes of the XQJ interfaces (javax.xml.xquery);
• org.eclipse.eilf.xmlstorage.internal.xquery.bdx.bind: provides the external binding that allows client code to bind variables;
• org.eclipse.eilf.xmlstorage.internal.xquery.bdx.map: maps/converts Oracle Berkeley DB Xml from/to XQJ items;
• org.eclipse.eilf.xmlstorage.internal.xquery.bdx.message: offers localized messages support. Current Bdx XQJ Implementation version doesn’t use this functionality for all error messages. It only shows how this featuring shall be used/adapted in order to support full internationalization messages support;
• org.eclipse.eilf.xmlstorage.internal.xquery.bdx.ou: object utilities class;
• org.eclipse.eilf.xmlstorage.internal.xquery.bdx.txn: provides transaction demarcation for client code
• org.eclipse.eilf.xmlstorage.internal.xquery.bdx.type and org.eclipse.eilf.xmlstorage.internal.xquery.bdx.value provide the data type hierarchy which is internal used by the current implementation;
• org.eclipse.eilf.xmlstorage.internal.xquery.bdx.util: utility class for internal usage.

(Next versions of the Bdx XQJ Implementation will most probably have minor changes in current package structure – which will not affect the client code implementation)

Implemented functionalities

• Creating data source (BdxXQDataSourceImpl)
• Establishing connection through the data source (BdxXQConnectionImpl)
• Creating expressions
• Binding values to external values
• Executing queries (BdxXQExpressionImpl)
• Retrieving results from xquery
• Closing (release) resources

Non-implemented functionalities

• Load the XQDataSource object through JNDI
• Binding value to the context item
• Executing queries through XQPreparedExpression (BdxXQPreparedExpressionImpl exists but doesn’t provide functionality)
• Using a Result Sequence as input

Following picture outlines the non-implemented interfaces/methods by cutting the method signature / interface with a red line. All the not-implemented operations will be implemented as soon as they will be required to support different operations, different data types and value conversions.

Technical requirements and dependencies

• J2SE 5.0
• Oracle Berkeley DB Xml 2.4.13. Required jars and libraries that come with the distribution: db.jar; dbxml.jar; libdb_java46.dll, libdb46.dll, libdbxml_java24.dll, libdbxml24.dll, msvcp71.dll, msvcr71.dll, xerces-c_2_8.dll, xqilla21.dll. The DLLs are to be used on Windows operating system. For linux system the so libraries have to be built: (libdb_java-4.6.so, libdb-4.6.so, libdb_cxx-4.6.so, libdbxml_java-2.4.so, libdbxml-2.4.so, libxerces-c.so, libxqilla.so);
• javax.xml.stream
• XQJ – javax.xml.xquery
• Log4j – log4j.jar

Logging

The Apache Commons Logging library is used for logging.

Error & Message handling

Currently all the exceptions are wrapped into javax.xml.xquery.XQException. Bdx XQJ Implementation exceptions are concrete checked exceptions, which contain the initial cause (in case the exception is not recently thrown). They provide recursively call to method getCause, until a null value is returned, to navigate the chain of causes. This way client code is able to obtain the entire list of occurred exceptions. Client code shall avoid catching top-level exceptions – where it makes sense – in order to handle in the right way the XQJ exceptional operations. Current Bdx XQJ Implementation throw a new UnsupportedOperationException("Unimplemented method") exception for all unimplemented operations.

Internationalization

Bdx XQJ Implementation provides the localized messages support, but current version doesn’t use this functionality for all error messages. It only shows how this featuring shall be used / adapted in order to support full internationalization messages support. The messages are localized into properties files. The default file is ErrorMessages.properties (located under org.eclipse.eilf.xmlstorage.internal.xquery.bdx.message) which only contains two messages at the moment.

Tuning

For better performance the Oracle Berkeley DB Xml settings need to be adjusted according to the own needs. The BDB Xml settings are not currently available via Bdx XQJ Implementation. Proper configuration of JVM will improve performance, by configuring particularly parameters related to memory usage (“-Xms” initial java heap size and “-Xmx” maximum java heap size) and garbage collection.