XQuery Developer's Guide

Understanding Data Services Platform Annotations

This chapter describes the syntax and semantics of BEA AquaLogic Data Services Platform (DSP) annotations in data service and XQuery function library (XFL) documents. Data service and XQuery function library documents define collections of XQuery functions. Annotations are XML fragments comprising the character content of XQuery pragmas.

There are two types of annotations:

• Global annotations. These pertain to the entire data service or XFL document. Global annotations are also referred to as XDS or XFL annotations respectively.
• Local annotations. These pertain to a particular function. Local annotations are also referred to as function annotations.

This chapter includes the following topics:

• XDS Annotations
• XFL Annotations
• Function Annotations

See XML Schema for Annotations, for a listing of the XML Schema for annotations.

 

---

XDS Annotations

There is a single XDS annotation per data service document, which appears before all function annotations. The identifier for the pragma carrying the XDS annotation is xds. The qualified name of the top level element of the XML fragment corresponding to an XDS annotation has the local name xds and the namespace URI urn:annotations.ld.bea.com.

Each data service is associated with a unique target type. The prime type of the return type of every read function must match its target type. The target type of a data service is an element type whose qualified name is specified by the targetType attribute of the xds element. It is defined in a schema file associated with that data service.

The contents of the top-level xds element is a sequence of the following blocks of properties:

• General Properties
• Data Access Properties
• Target Type Properties
• Key Properties
• Relationship Properties
• Update Properties
• Security Properties

The following excerpt provides an example of an XDS annotation. In this case, the target type t:CUSTOMER associates the data service with a t:CUSTOMER type in a schema file.

(::pragma xds <x:xds xmlns:x="urn:annotations.ld.bea.com" targetType="t:CUSTOMER" xmlns:t="ld:oracleDS/CUSTOMER">

<author>Joe Public</author>
<relationalDB name="OracleDS"/>

<field type="xs:string" xpath="FIRST_NAME">
	<extension nativeFractionalDigits="0" nativeSize="64"
		nativeTypeCode="12" nativeType="VARCHAR2"
		nativeXpath="FIRST_NAME"/>
		<properties nullable="false"/>
</field>

<field type="xs:string" xpath="LAST_NAME">
	<extension nativeFractionalDigits="0" nativeSize="64"
		nativeTypeCode="12" nativeType="VARCHAR2"
		nativeXpath="LAST_NAME"/>
	<properties nullable="false"/>
</field>

<field type="xs:string" xpath="CUSTOMER_ID">
	<extension nativeFractionalDigits="0" nativeSize="64"
		nativeTypeCode="12" nativeType="VARCHAR2"
		nativeXpath="CUSTOMER_ID"/>
	<properties nullable="false"/>
</field>

<field type="xs:dateTime" xpath="CUSTOMER_SINCE">
	<extension nativeFractionalDigits="0" nativeSize="7"
		nativeTypeCode="93" nativeType="DATE"
		nativeXpath="CUSTOMER_SINCE"/>
	<properties nullable="false"/>
</field>

<field type="xs:string" xpath="EMAIL_ADDRESS">
	<extension nativeFractionalDigits="0" nativeSize="32"
		nativeTypeCode="12" nativeType="VARCHAR2"
		nativeXpath="EMAIL_ADDRESS"/>
	<properties nullable="false"/>
</field>

<key name="CUSTOMER_PK11015727676593">
	<field xpath="CUSTOMER_ID">
		<extension nativeXpath="CUSTOMER_ID"/>
	</field>
</key>

<relationshipTarget roleName="CUSTOMER_ORDER" roleNumber="2"
	XDS="ld:oracleDS/CUSTOMER_ORDER.xds" minOccurs="0"
	maxOccurs="unbounded" opposite="CUSTOMER"/>
</x:xds>::)

General Properties

There are two types of general XDS properties:

• Standard Document Properties
• User-Defined Properties

Standard Document Properties

You can specify a set of standard document properties consisting of optional XML elements containing information pertaining to the author, creation date, or version of the document. You can also use the optional element documentation to specify related documentation. The names and types of the elements in the standard document properties block, as well as examples of their use, are shown in Table 5-1.

 

 

User-Defined Properties

In addition to the standard properties, you can specify custom properties pertaining to the entire data service document using a sequence of zero (0) or more property elements. Each property element must be named using its name attribute and may contain any string content. For example:

<property name="data-refresh-rate">week</property> 

Data Access Properties

Each data service document defines one or more XQuery functions that act as either data providers or data transducers. A data provider, or data source, is a function that is declared as external; its invocation causes data from an external source to be brought into the system. A data transducer, or data view, is defined in XQuery and it typically performs transformations on data derived from data sources or other data views.

The block of data access properties allows each data service to define whether its read functions include data sources or not. When data sources are included, the data access annotation describes the type of the external source being accessed by the external functions (there may be a single external source per data service) and its connection properties. When data sources are not included, the data service is designated as a user-defined view, and no connection information is required.

A data service may also define another form of XQuery functions known as private functions. The following types of data source data services are supported:

• Relational
• Web service
• Java function
• Delimited content
• XML content

The following sections describe the data access annotation for the data service types, as well as for data services that are designated as user-defined views. You can specify only one of the annotations in each data service. If no annotation is provided, the data service is considered a user-defined view.

Relational Data Service Annotations

The data access annotation for a relational data service consists of the empty element relationalDB with a single required attribute, name, whose value should be set to the JNDI name by which the external relational source has been registered with the application server. For example:

<relationalDB name="OracleDS"/>

In addition, the relationalDB element can contain the following optional parts:

• An optional element, named properties, that exposes the values of specific settings of the Relational Database Management System (RDBMS) represented by the relational source.
• An optional attribute, named sourceBindingProviderClassName, that specifies the transformation used to determine the relational source that should be used at system runtime in the place of the statically defined source.

Native Relational Properties

The properties element is an empty element with several required and optional attributes, as outlined in Table 5-2.

 

Source Binding Provider

The value of the optional sourceBindingProviderClassName attribute should be bound to the fully-qualified name of a user-defined Java class implementing the com.bea.ld.bindings.SourceBindingProvider interface, defined by the following:

package com.bea.ld.bindings;
public interface SourceBindingProvider
{
	public String getBinding(String genericLocator, boolean isUpdate);
}

The user-defined implementation should provide the transformation that, given the statically configured relational source name (parameter genericLocator) and a Boolean flag indicating whether the relational source is accessed in query or update mode (parameter isUpdate), determines the name of the relational source name used by the system at runtime.

Note that you can use this transformation mechanism to perform credential mapping. In this case, a single set of query or update operations to be performed in the name of two distinct users U1 and U2 against the same statically-configured relational source R0, is executed against two distinct relational sources R1 and R2 respectively (where all sources R0, R1, R2 represent the same RDBMS and the security policies applied to the connection credentials used for R1 and R2 correspond to the security policies applied to the application credentials of user U1 and U2 respectively).

Note: You should set the source binding provider name uniformly across all relational data services sharing the same relational source JNDI name. Although this restriction is not enforced, its violation could result in unpredictable behavior at runtime.

Web Service Data Service Annotations

The data access annotation for a data service based on a Web service consists of the empty element webService with two required attributes, described in Table 5-3.

 

For example:

<webService targetNamespace="urn:GoogleSearch"
	wsdl="ld:google/GoogleSearch.wsdl"/>

Java Function Data Service Annotations

The data access annotation for a Java function data service consists of the empty element javaFunction with a single required attribute named class, whose value should be set to the fully qualified name of the Java class serving as the external source. For example:

<javaFunction class="com.example.Test"/>

Delimited Content Data Service Annotations

The data access annotation for a delimited content data service is the empty element delimitedFile, accepting the optional attributes described in Table 5-4.

 

For example:

<delimitedFile schema="ld:df/schemas/ALL_TYPES.xsd" hasHeader="true"
	delimiter="," file="ld:df/ALL_TYPES.csv"/>

XML Content Data Service Annotations

The data access annotation for an XML content data service is the empty element xmlFile accepting the attributes described in Table 5-5.

 

For example:

<xmlFile schema="ld:xml/somewhere/CUSTOMER.xsd"
	file="ld:xml/CUSTOMER_NESTED.xml"/>

User Defined View XDS Annotations

The data access annotation for a user-defined view data service is also known as a logical data service. It consists of the single empty element userDefinedView. For example:

<userDefinedView/>

Target Type Properties

The optional block of target type properties enables you to annotate simple valued fields in the target type of the data service with native type information pertaining to the following:

• The type of the corresponding field in the underlying external source (applicable only to data source data services)
• Information about the field's properties with respect to its update behavior. Each annotated field is represented by the element field with two required attributes, described in Table 5-6.

Table 5-6 Required Attributes for the field Element  

Attribute	Description
xpath	An XPath value pointing to the field
type	The qualified name of the field's simple XML schema or XQuery type.


 

The following excerpt provides an example of a field element definition:

<field type="xs:string" xpath="FIRST_NAME">
	<extension nativeSize="64" nativeTypeCode="12" nativeType="VARCHAR2"
		nativeXpath="FIRST_NAME"/>
	<properties nullable="false"/>
</field>

Native Type Properties

Each field element can contain an optional extension element that accepts the optional attributes described in Table 5-7.

 

Update-related Type Properties

Each field element can also contain an optional properties element that accepts the optional attributes described in Table 5-8.

 

Key Properties

The optional block of key properties enables you to specify a set of identity constraints (keys) on the data service target type. Each key is represented by the element key that accepts an optional attribute, named name, whose value should serve as an identifier for the key.

Each key element contains a sequence of one or more field elements that collectively specify the simple-valued target type fields that the key comprises. Keys may be simple (having one field) or compound (having multiple fields). Each field element is identified by the value of its required xpath attribute (behaving similarly to the xpath attribute described in Target Type Properties on page 5-11).

Furthermore, each field element may optionally contain an extension element carrying a nativeXpath attribute that behaves similarly to the nativeXpath attribute described in Native Properties on page 5-25.

The following excerpt provides an example of a key element definition:

<key name="CUSTOMER_PK11015727676593">
	<field xpath="CUSTOMER_ID">
		<extension nativeXpath="CUSTOMER_ID"/>
	</field>
</key>

Relationship Properties

The optional block of relationship properties enables you to specify a set of relationship targets. A relationship target of a data service is a data service with which first service maintains a unidirectional or bidirectional relationship. Unidirectional relationships are realized through one or more navigate functions in the first data service that returns one or more instances of objects of the second service target type. Bidirectional relationships require that reciprocal functions are present in the second data service as well.

A relationship target is represented by the element relationshipTarget that accepts the attributes described in Table 5-9.

 

Additionally, the relationshipTarget element can itself contain the element relationship which in turn contains the nested element description that contains a human readable description about the relationship.

The following excerpt provides an example of a relationshipTarget element definition:

<relationshipTarget roleName="CUSTOMER_ORDER" roleNumber="2"
	XDS="ld:oracleDS/CUSTOMER_ORDER.xds" minOccurs="0"
	maxOccurs="unbounded" opposite="CUSTOMER"/>

Update Properties

The optional block of update properties enables you to specify a set of properties that establish certain policies about updating a data service's underlying sources. In particular, you can specify the following policies:

• The data service function that should be analyzed in order to build the plan for update decomposition.
• The external Java function to use as an update exit.
• The fields to use for optimistic locking purposes.
• Whether the data service is updateable or not.

Function for Update Decomposition

You can expose data obtained through data service read functions as SDO objects that can later be updated. In order for the changes to be persisted in the original data sources, the data service should specify which read function are to be used to perform data lineage analysis. The result of this analysis is a plan that allows the update to be decomposed into subplans that can be applied on each of the underlying sources. This feature is primarily used by logical data services.

The function for update decomposition is represented by the element functionForDecomposition that accepts the required attributes described in Table 5-10.

 

When the functionForDecomposition element is not present, the first read function in the data service document is designated as the function for the update decomposition.

The following excerpt provides an example of a functionForDecomposition element definition:

<functionForDecomposition xmlns:f="ld:view/myView"
	name="f:firstNameFilter" arity="0"/> 

Java Update Exit

A data source data service that is not automatically updateable (all non-relational XDS), or a data view XDS may specify an external mechanism to use for update. Supported external mechanisms include Java classes that implement a particular interface specified in the SDO update specification.

The Java class to use as update exit is represented by the empty element javaUpdateExit that accepts the attributes described in Table 5-11.

 

The following excerpt provides an example of a functionForDecomposition element definition:

<javaUpdateExit className="com.example.Exit"/> 

Optimistic Locking Fields

SDO update assumes optimistic locking transactional semantics. The data service being updated can specify the fields that should be checked for updates during the interim using the empty element optimisticLockingFields that accepts one of the following as its content:

• An empty element, named updated, to specify only updated fields.
• An empty element, named projected, to specify all projected fields.
• One or more elements, named field, that accept a required string-valued attribute named name to specify user-specified fields.

The following excerpt provides an example of a functionForDecomposition element definition:

<optimisticLockingFields>
	<updated/>
</optimisticLockingFields>

Read-Only Data Service

You can designate a data service as read-only, in which case no updates will be allowed against the results obtained from the read functions of the service. You can use the empty element readOnly to designate a data service as read-only. For example:

<readOnly/>

Security Properties

You can use a data service to define one or more user-defined, logical protected resources. The element secureResources, containing one or more string-valued elements named secureResource, can be used for this purpose.

For example:

<secureResources>
	<secureResource>MyResource</secureResource/>
	<secureResource>MyOtherResource</secureResource/>
</secureResources>

You can link a logical resource defined using this syntax to a user-provided security policy using the DSP Console. Query content can inquire about a user's ability to access a logical resource using the built-in function isAccessAllowed().

 

---

XFL Annotations

There is a single XFL annotation per XFL document, which appears before any function annotation in the document. The identifier for the pragma carrying the XFL annotation is xfl. The qualified name of the top level element of the XML fragment corresponding to an XFL annotation has the local name xfl and the namespace URI urn:annotations.ld.bea.com.

The contents of the top-level xfl element is a sequence of the following blocks of properties.

• General Properties
• Data Access Properties

The following sections provide detailed descriptions of each block of properties, while the following excerpt provides an example of a XFL annotation, which may serve as a reference.

(::pragma xfl <x:xfl xmlns:x="urn:annotations.ld.bea.com">
<creationDate>2005-03-09T17:48:58</creationDate>
<webService targetNamespace="urn:GoogleSearch"
	wsdl="ld:google/GoogleSearch.wsdl"/>
</x:xfl>::)

General Properties

The general properties applicable to an XFL document are identical to the general properties for a data service document, as described in General Properties on page 5-4.

Data Access Properties

Each XFL document defines one or more XQuery functions that serve as library functions that can be used either inside data service documents to define read navigate or private functions, or inside other XFL documents to specify other library functions.

Since XFL documents do not have a target type, the return types of the library functions found inside these document may differ from each other. In particular, a function inside an XFL document may return a value having a simple type (or any other type). XFL functions can be external data source functions or user-defined.

The following types of XFL documents are supported:

• Relational (logical)
• Web service (logical)
• Java function (logical)
• User-defined view (logical)

You can specify only one of the annotations in each XFL. If no annotation is provided, the XFL is considered a user-defined view.

The data access properties for Relational, Web service, Java function, and user-defined view XFL documents are the same as the corresponding properties for data service documents, as described above.

 

---

Function Annotations

There is a single function annotation per data service or XFL function, which appears before the function declaration in the document. The identifier for the pragma carrying the function annotation is function. The qualified name of the top level element of the XML fragment corresponding to an XDS or XFL annotation has the local name function and the namespace URI urn:annotations.ld.bea.com.

Each data service function is classified using one of the following categories:

• Read function
• Navigate function
• Private function

The classification of an data service function is determined by the value of a required attribute kind in the function element, which accepts the values read, navigate, or private to denote the corresponding categories. Each XFL function is considered to be a library function.

The prime type of the return type of a read function must match the target type of the data service. In addition, the function element for a navigate function must carry a string-valued attribute returns whose value must match the role name of a relationship target defined in the data service. Moreover, the prime type of the return type of a navigate function must match the target type of the data service serving as the relationship target.

Finally, the namespace URIs of the qualified names of all the functions in a data service or XFL must specify the location of the data service or XFL document in the LD repository. For example:

ld:{directory path to data service folder}/{data service file name without extension}

or

lib:{directory path to XFL folder}/{XFL file name without extension}

The function element accepts the additional optional attributes described in Table 5-12.

 

The content of the top-level function element is a sequence of the following blocks of properties:

• General Properties
• UI Properties
• Cache Properties
• Signature Properties
• Native Properties

The following excerpt provides an example of a function annotation:

(::pragma function <f:function xmlns:f="urn:annotations.ld.bea.com" kind="datasource" nativeName="CUSTOMER" nativeLevel2Container="RTL" style="table">
<cacheable>
	<useCache TTL="600"/>
</cacheable>
</f:function>::)

General Properties

All standard document properties and user-defined properties defined in Standard Document Properties on page 5-4 and User-Defined Properties on page 5-4 are applicable to function annotations.

UI Properties

A set of user interface properties may be introduced by the XQuery Editor to persist location information about the graphical components representing the expression in the function body. UI properties are represented by the element uiProperties which accepts a sequence of one or more elements, named component, as its content. Each component element accepts the attributes described in Table 5-13

 

In addition, each component element may optionally contain one or more treeInfo elements containing information about the tree representation of the types pertaining to the component. In the absence of the above property, the query editor uses the default layout.

Cache Properties

You can use the optional block of cache properties to specify whether a function can be cached or not. You should specify a function whose results for the same set of arguments are intrinsically highly volatile as non-cached. On the other hand, you should specify a function whose results for the same set of arguments are either fixed or remain unchanged for a period of time as cacheable.

This property of a function is represented by the empty element nonCacheable. In the absence of the nonCacheable element, a function is considered to be potentially cacheable. The following excerpt provides an example:

<nonCacheable/>

Signature Properties

You can use the optional block of signature properties to annotate the parameters of a data service or XFL function with additional information to that provided by the function signature. These properties are applicable to data source (data service or XFL) functions.

The signature properties block is represented by the element params which accepts a sequence of one or more elements, named param, as its content. Each param element is an empty element that accepts the optional attributes described in Table 5-14.

 

The following excerpt provides an example of a params element definition:

<params>
	<param nativeType="java.lang.String"/>
	<param nativeType="java.lang.int"/>
</params>

Native Properties

You can use native properties to further annotate a data source function based on the type of the external source that it represents. There are two types of native properties pertaining to relational and Web service sources respectively:

• SQL query properties
• SOAP handler properties

SQL Query Properties

The function annotation element of a function that represents a user-defined SQL query has its style attribute set to sqlQuery and accepts a nested element, named sql. The sql element accepts string content that corresponds to the statement of the (possibly parameterized) SQL query that the function represents.

If required, the statement can be escaped inside a CDATA section to account for reserved XML characters (e.g. <, >, &). The sql element also accepts the optional attribute isSubquery whose boolean value indicates whether the SQL statement may be used as a nested SQL sub-query. If the attribute is absent, its value defaults to true.

The following excerpt provides an example of a sqlQuery element definition:

<sql isSubquery="true">
	SELECT t.FIRST_NAME FROM RTLALL.dbo.CUSTOMER t</sql>

SOAP Handler Properties

The function annotation element of a function that represents a Web service call accepts a nested element, named interceptorConfiguration. The interceptorConfiguration element accepts two required attributes, as described in Table 5-15.

 

Contact BEA |  Feedback |  Privacy  |