INRIA
[Up]
Warning

Work in progress

This version may be updated without notice.

EXP Specification

The Extensible XML Processor

Working Draft 29 december 2007

Editor
Philippe Poulard  <Philippe · Poulard [at] sophia · inria · fr>

Copyright © INRIA

Abstract

An Extensible XML Processor (EXP) is a customizable engine that implements the Active Tags specification. EXP provides tags, attributes, functions and predefined properties to customize such an engine before its invokation, for example by specifying which catalog to use when unmarshalling an active sheet.

EXP allows to define a fine grained control of the behaviour of an Active Tags engine. Actually, it allows to bypass the modules auto-loading mechanism.

EXP may be applied to the current active sheet or used to invoke an outer active sheet. In this case, EXP may also be used to manage custom modules by defining new tags, functions, properties and providing their implementations. EXP also provide a mechanism to define macros : instead of supplying a dependant implementation, it is possible to define an active tag, an XPath function or a predefined property with other active tags.

Requirement levels

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Note that for reasons of style, these words are not capitalized in this document.

Active Tags specifications

The following specifications are part of the Active Tags technologies.

Table of contents

1 What is EXP ?
2 Processor usage

2.1 Internal tuning
2.2 Invoking
2.3 Bootstraping
2.4 Passing parameters
2.5 Miscellaneous features
3 Module definition
3.1 Implementations binding
3.1.1 Inline implementation (macro definitions)
3.1.2 Dynamic content production
3.2 Versioning
3.3 Module resolution
4 EXP module reference
4.1 Elements
4.2 Foreign attributes
4.3 Predefined properties
4.4 Extended XPath functions
4.5 Data types

Appendix

A Glossary
B Related Active Tags specifications
C Lists

C.1 Examples list
C.2 Figures list
D Active Schema for EXP


1 What is EXP ?

The Active Tags specification describes the generic behaviour of an engine that consider tags as actions to perform (such tags are active tags). As tags that are active are bound to a namespace URI, each set of tags that share the same namespace URI are belonging to a module. The Active Tags specification describes the usual behaviour of an engine, a data model, how tags of different modules may cooperate, and how modules are loaded automatically.

However, a user may find necessary to use an engine that doesn't automatically load the modules, or that must deal with specific custom modules. EXP is an Active Tags module that groups this kind of features together.

This specification describes the EXP module, that act on the engine behaviour. It describes how to invoke a processor, how to define reusable modules declarations and how to use these declarations for bootstrapping.

In addition, this specification explains how modules must define the bindings between the tags and attributes and their concrete implementation, between the predefined properties and their property resolver, and between the extended XPath functions and their implementation.

An engine that has unmarshalled an active sheet with its own settings is called a processor instance.


2 Processor usage

EXP provides various means to configure a processor for various purpose.

2.1 Internal tuning

Internal tuning means acting on the actual active sheet.

Tags that are bound to a module are active tags, and automatically unmarshalled to concrete actions when encountered. When such tags need to be inactive, it is necessary to disable the module for the tags that are using a specific prefix. Thus, the module is still available when using another prefix not disabled. Tags, foreign attributes, predefined properties and extended XPath functions that uses a disabled prefix are inactive, and may cause errors, as explained in the section "module resolution".

Two EXP foreign attributes are designed as directives that enable or disable the tags that are active, and another one that allow to specify a catalog :

@exp:disable-prefixes

This attribute contains a list of prefixes used by the tags to disable; prefixes are separated with blanks. The tags bound to a module for which their prefix is not in this list are active tags. The others are handled by the fallback module.

@exp:enable-prefixes

This attribute contains a list of prefixes used by the tags to enable; prefixes are separated with blanks. The tags bound to a module for which their prefix is in this list are active tags. The others are handled by the fallback module.

Usage

Each prefix listed in these attributes must be involved in a namespace declaration. The scope of the enable/disable directive is the whole active sheet.

Only one or zero of these attributes may be used within an active sheet. If none is used, each tag bound to a module is an active tag, others are handled by the fallback module. These attributes must be used in the root element of the active sheet.

An active sheet can't act on the EXP module on itself, that is to say on the active sheet that uses this directives. The EXP module is still active even if not specified when using @exp:enabled-prefixes, which automatically enables the prefix used in this attribute It can't be disabled with @exp:disabled-prefixes. Attempting to disable the EXP module cause a fatal error.

Prefix disabling

When the main logic procedure of the following active sheet is invoked, it is said that XCL is disabled, thus <XCL:active-sheet>, <XCL:logic> and <XCL:set> are taking in charge by the internal fallback module : they are considered as simple litteral elements. On the contrary, <xcl:for-each> is an active tag.

<?xml version="1.0" encoding="iso-8859-1"?>
<XCL:active-sheet exp:disable-prefixes="XCL" xmlns:exp="http://ns.inria.org/active-tags/exp" xmlns:xcl="http://ns.inria.org/active-tags/xcl" xmlns:XCL="http://ns.inria.org/active-tags/xcl" xmlns:sys="http://ns.inria.org/active-tags/sys"> <xcl:for-each select="{$sys:env/logic}"> <XCL:logic name="{name}"> <XCL:set name="{param}" value="{value}"/> </XCL:logic> </xcl:for-each> </XCL:active-sheet>

Although they are bound to the same namespace URI, the materials bound to the xcl prefix are active and those bound to the XCL prefix are inactive, as specified in the root element.


Note

These directives should be used for active sheets that will run on a target not known by the user.

@exp:use-catalog

This attribute contains an URI reference to the catalog to use by the actual active sheet. If several catalogs must be specified, the user have to create a catalog that refers to all its catalogs and set its URI in the attribute.

This attribute must be specified on the root element of the active sheet.

Note

If the catalog lead to a definition or a redefinition of some materials used at the same place (including the root element), the right implementation will be used, even if the version is specified.

2.2 Invoking

It is very useful to design XML documents that contains Active Tags snippet code; these XML documents became dynamic, like shown in the example below.

[TODO: XInclude the example]

Invoke example

As a single document may be invoked directly, it is necessary to build another active sheet when a collection of dynamic XML documents needs to be performed. This new active sheet would be able to browse the collection and invoke each item as an active sheet, like shown in the example below, where only one dynamic document is invoked.

The <exp:invoke> tag has been designed for this purpose.

[TODO: XInclude the example]

Invoke example

2.3 Bootstraping

When a program needs to be launched with fine grained control of its behaviour, one often uses command line options. For example :

myTool --super-option=on --another-option=useful --more-option=do_it_like_this  fileToProcess

EXP allows to express all the options needed by an Active Tags engine inside another active sheet.

Thus, an Active Tags engine could be simply launched like this, without options :

myEngine launcher.exp

The launcher.exp file is not really the file to process; it just instanciates another engine (with the real fileToProcess) with the appropriate options thanks to EXP tags and attributes.

However, implementations are still free to provide command line options or not.

To do so, the launcher simply uses the EXP tags, and eventually the XCL tags. Other modules could also be used, but the role of a launcher is just to customize a new engine that will do the job. Another advanvage nf(using a launcher, is that it is able to pass as parameters any object type, whereas a command line could only pass strings.

Particularly, a launcher may register additional modules that are not known by the default implementation. Notice that for this purpose, the implemented engine is free to use any convenient way, such as defining a specific configuration file.

Example using EXP for bootstraping
<?xml version="1.0" encoding="iso-8859-1"?>
<xcl:active-sheet xmlns:exp="http://ns.inria.org/active-tags/exp" xmlns:xcl="http://ns.inria.org/active-tags/xcl"> <exp:unmarshal name="engine" source="file:///path/to/active-sheet.xcl"> <!--supply the catalog that defines custom modules--> <xcl:param name="use-catalog" value="file:///path/to/my-resources.cat"/> </exp:unmarshal> <exp:invoke processor="{ $engine }"/> </xcl:active-sheet>

The engine to invoke will have the knowledge of custom module bindings if an Active Catalog that declares these resources has been specified, like shown above. The following example is such a catalog.

Declaring EXP modules with Active Catalog

The following document is a catalog that bind resources (module definitions and schemata) to a namespace URI :

<?xml version="1.0" encoding="iso-8859-1"?>
<cat:catalog xmlns:cat="http://ns.inria.org/active-catalog" xmlns:exp="http://ns.inria.org/active-tags/exp" xmlns:xcl="http://ns.inria.org/active-tags/xcl" xmlns:asl="http://ns.inria.org/active-schema"> <cat:resource name="http://www.acme.org/purchase-orders" selector="exp:module"
uri="file:///path/to/po-module.exp"/> <cat:resource name="http://www.acme.org/purchase-orders" selector="asl:schema"
uri="file:///path/to/po-schema.asl"/> </cat:catalog>

The customized processor instance will first registers the modules provided by the default implementation. Then, the additional modules will be registered. Notice that it is possible to override some tags of the modules provided by the default implementation : in fact, another version of the module must be specified (the version is indicated inside the module definition).

This catalog file should be placed in a directory where the Active Tags engine automatically adds the files in its own catalog list, if such feature is provided, or explicitely referenced as a parameter name "use-catalog" of the <exp:unmarshal> element.

If several catalogs have to be used, this parameter can be specified several times, but a master catalog is more appropriate. Please refer to the Active Catalog specification for further information about XML catalogs.

Note

A processor instance should always be backed by a primal catalog that defines the resources needed for the engine to work.

Note

A catalog only defines mappings ; the processor instance will use it only on module requests, that take care of module enabling/disabling.

Notice that an active sheet can also self-define a catalog to use, as explained in the "internal tuning" section.



Note

EXP is the sole module that can't be overriden. Furthermore, to escape EXP in an active sheet, it is mandatory to use a launcher that disables EXP in the outer active sheet.

External tuning

The only way to act on the EXP module in an active sheet is to use a second active sheet for bootstrapping (see the section about internal tuning).

For this purpose, <exp:unmarshal> uses the following two attributes :

Warning

Notice that @exp:disable-prefixes and @exp:enable-prefixes in one hand, and @disable-prefixes and @enable-prefixes of the <exp:unmarshal> element on the other hand are not the same attributes.

The formers (that are foreign attributes) are designed to act on the active sheet they belong (if they are active), the latters (that are not foreign attributes) are designed to act on an external active sheet.

@disable-prefixes and @enable-prefixes are taking precedence on @exp:disable-prefixes and @exp:enable-prefixes.

EXP prefix disabling

This example shows an active sheet used as an external tuning of the other active sheet of the previous "prefix disabling" example .

If the following active sheet was used to invoke the former, exp would be disabled in the invoked active sheet, and all the tags would be active tags. However, this would cause an error due to the XCL specification.

<?xml version="1.0" encoding="iso-8859-1"?>
<xcl:active-sheet xmlns:exp="http://ns.inria.org/active-tags/exp" xmlns:xcl="http://ns.inria.org/active-tags/xcl"> <exp:unmarshal disable-prefix="exp" name="proc" source="file:///path/to/active-sheet.xcl"/> <exp:invoke processor="{$proc}"/> </xcl:active-sheet>

2.4 Passing parameters

The <exp:invoke> element uses a context to pass parameters to the data set used by the invoked processor, and the <exp:exports> element to keep return values in the data set used by the invoker.

Passing parameters example
    <exp:invoke processor="{$proc}">
        <!-- the target processor will be able to use $boat-name -->
        <xcl:param name="boat-name" value="titanic"/>
        <exp:exports>
            <!-- if the target processor has created the property $captain-age
                 it is reproduced inside this launcher when exiting the target
                 processor -->
            <exp:export name="captain-age" scope="global" value="{$captain-age}"/>
            <xcl:if test="{ $boat/@has-sunk }">
                <!-- another property is created inside this launcher, but there
                     is a condition -->
                <exp:export name="casualties" scope="local" value="{ value( $boat/@casualties )}"/>
            </xcl:if>
        </exp:exports>
    </exp:invoke>

The <xcl:param> element is a convenient action to pass parameters to the processor instance to invoke.

When the invoked process ends, the $captain-age and $casulaties properties are exported to the data set in use when the processor instance was invoked ; notice that the $casulaties are set only if the boat sunk (did it ?).

2.5 Miscellaneous features

Logging

EXP allows to tune the logs at runtime. This can be done thanks to the <exp:log> active tag :

Additionally, the log output flow may be specified with the <exp:log-stream> element and its @output attribute. If the value is a string, it denotes a file to write to, otherwise it must be a reference to an output stream. A log output flow may be specified only once on behalf of a processor instance.

Fast fail

When unmarshalling, the engine usually use schemata to check the validity of tags unmarshalled by the engine. When a constraint violation is encountered, the engine must go on to report other errors. The @fail-fast attribute of the <exp:unmarshal> element is a directive that allows to stop the unmarshall phase as soon as an error occurs.

Notice that validity checking may also be turned off.


3 Module definition

This chapter introduces the structure that allows to map Active Tags materials (tags, foreign attributes, predefined properties and extended XPath functions) with their concrete implementation. See also the chapter about modularization of the Active Tags specification.

A module definition will be unmarshalled by the processor only if it is used.

3.1 Implementations binding

The <exp:module> element is used to define the Active Tags materials of the module. It is the root element of the module definition.

A processor instance will use the module bindings known by the implementation :

Of course, the self-bindings are implementation dependant ; others should be defined inside a catalog.

The <exp:module> element works with 2 usages :

In both cases, @target contains a prefix that must be bound to a namespace URI. This prefix is used for the mappings of the module, defined by the subelements.

<?xml version="1.0" encoding="iso-8859-1"?>
<exp:module target="acme" version="1.0" xmlns:exp="http://ns.inria.org/active-tags/exp" xmlns:acme="http://www.acme.org/purchase-order"> <exp:element name="acme:send-purchase-order" source="..."/> <exp:attribute name="acme:notify-customer" source="..."/> <exp:property name="acme:discount" source="..."/> <exp:function name="acme:check-customer-account" source="..."/> </exp:module>

The elements <exp:element>, <exp:attribute>, <exp:property>, and <exp:function>, may appear in any order zero or more times.

In addition :

If <exp:module> is the root of an XML active sheet, the module definition produced is set on the current object.

Additional attributes may have other roles when unmarshalling or at runtime. Please refer to the reference for the exhaustive description.

The @deferred attribute ("yes" or "no") may be used to force the module definitions to be loaded when unmarshalling. By default, the bindings are processed the first time the module is invoked.

3.1.1 Inline implementation (macro definitions)

When the @source attribute is missing, the implementation is given by the subelements of the definition ; thus, a definition can be a kind of "macro". When a macro is processed, a new data set is used, but parameters may be passed, and some properties set by the macro may also be kept (with the <exp:export> element).

The example below shows an active tag which is defined inline. This other example shows several XPath functions which are also defined inline.

Macro tag

The following definition of the custom <macro:transform-and-save> element doesn't use the @source attribute ; its implementation is defined with its subtags for parsing, transforming, and saving an XML file to a PDF file.

    <exp:element name="macro:transform-and-save"
    xmlns:io="http://ns.inria.org/active-tags/io"
    xmlns:xcl="http://ns.inria.org/active-tags/xcl"
    xmlns:serialize="http://ns.inria.org/active-tags/serialize"
    xmlns:macro="http://www.foo.com/macros">
        <xcl:parse name="xml" source="{$exp:params/file}"/>
        <xcl:transform name="fo" source="{$xml}" stylesheet="{$exp:params/xslt}"/>
        <serialize:to-pdf output="{substring-before( $exp:params/file/@absolute-path, '.xml' )}.pdf"
source="{$fo}" stylesheet="{$exp:params/xslt}"/> </exp:element>

The element previously defined is used with 2 attributes (@file and @xslt). This attributes become named items of the $exp:params predefined property.

Usage of our custom element <macro:transform-and-save> :

<?xml version="1.0" encoding="iso-8859-1"?>
<xcl:active-sheet xmlns:xcl="http://ns.inria.org/active-tags/xcl" xmlns:macro="http://www.foo.com/macros"> <xcl:logic> <!-- the same stylesheet for all XML files --> <xcl:parse-stylesheet name="xslt" source="file:///path/to/myStylesheet.xsl"/> <xcl:set name="myXMLFiles"
value="{io:file( '/path/to/my/xml/docs' )//*[@is-file][ends-with( name(), '.xml' )]}"/> <xcl:for-each name="file" select="{$myXMLFiles}"> <!-- our custom element ; check how its attributes are used in its implementation --> <macro:transform-and-save file="{$file}" xslt="{$xslt}"/> </xcl:for-each> </xcl:logic> </xcl:active-sheet>

Remember that our custom tag will be active only if a catalog that refers to its implementation has been plugged to the active sheet. Please refer to the previous chapter.

Notice that if the implementation is missing, our custom tag will be considered as a litteral ; to force the engine fails if the implementation is missing, the @exp:enable-prefixes or @exp:disable-prefixes attributes can help.

An inline implementation may use itself an element defined by an inline implementation. For this purpose, $exp:params must be saved before using, and restored after. Similarly, $exp:args must be saved before using an extended XPath function, and restored after.

The element definition must be unmarshalled only once it is invoked (unused elements won't be unmarshalled).

3.1.2 Dynamic content production

Inline implementation may be used advantageously to produce content inside a dynamic active sheet. These usage is close to "web server pages" technologies such as JSP, ASP or PHP. When a family of tags are encountered and recognized as belonging to a module, they are replaced by the result produced at runtime.

Dynamic content production

The following module defines a macro that creates a table of content. Others elements of the same module are copied with their attributes, and their content are processed.

<?xml version="1.0" encoding="iso-8859-1"?>
<exp:module target="macro" xmlns:exp="http://ns.inria.org/active-tags/exp" xmlns:xcl="http://ns.inria.org/active-tags/xcl" xmlns:macro="http://www.acme.org/active-tags/macro"> <exp:element name="macro:insert-toc"> <p>Table of content</p> <ul> <xcl:for-each name="item" select="{ $this//(h1|h2|h3) }"> <li>{ $item/text() }</li> </xcl:for-each> </ul> </exp:element> <exp:element><!-- others elements "macro:*" --> <!-- keep the content of the element that has been performed before --> <xcl:set name="content" value="{ context() }"/> <!-- copy the element... --> <xcl:element name="{ name( $exp:element ) }"> <!-- ...with all its attributes... --> <xcl:for-each name="attr" select="{ $exp:element/@* }"> <xcl:attribute name="{ name( $attr ) }" value="{ value( $attr ) }"/> </xcl:for-each> <!-- ...and its content -->{ $content }<!-- this comment prevents adding undesirable spaces --> </xcl:element> </exp:element> </exp:module>

The following active sheet uses the module defined above. When processed, the <macro:insert-toc> tag will be replaced by the table of content computed.

<?xml version="1.0" encoding="iso-8859-1"?>
<html> <body> <macro:insert-toc xmlns:macro="http://www.acme.org/active-tags/macro"/> <h1>Intro</h1> <h2>Abstract</h2> <p>...</p> <h2>Terminology</h2> <p>...</p> <h1>Outro</h1> <p>...</p> </body> </html>

Result after processing :

<?xml version="1.0" encoding="iso-8859-1"?>
<html> <body> <p>Table of content</p> <ul> <li>Intro</li> <li>Abstract</li> <li>Terminology</li> <li>Outro</li> </ul> <h1>Intro</h1> <h2>Abstract</h2> <p>...</p> <h2>Terminology</h2> <p>...</p> <h1>Outro</h1> <p>...</p> </body> </html>

3.2 Versioning

Any module must define a foreign attribute that sets the version of the module used. When used, this attribute must appear only once per module on the root element.

The name of this attribute is a qualified name; its prefix is those of the module, and its local-name is "version".

For example, exp:version="1.0" xcl:version="1.0" are valid declarations.

Some modules may oblige to use such attribute.

When not specified, the processor will use the last known version of the module.

Module designers may define a namespace URI per version of their module if they don't want to deal with versioning.

As the versionings are defined with foreign attributes, they are applied with the restrictions propers to foreign attributes :

Warning

Restrictions for foreign attributes

Foreign attributes are applied in the order they defined by their own, that is version dependant. Once found, the foreign attributes are ordered and applied; thus, if a version setting has been specified, it can be applied only on things that has not been yet resolved : the element that hosts the foreign attribute that defines a version must endorsed the version expected, whereas the other foreign attributes can't.

Versions should be specified within elements that don't use other foreign attributes of the same module. The only tolerate foreign attributes are @exp:disable-prefixes and @exp:enable-prefixes.

For exemple, foo:version="2.1" shouldn't be used in the same element that also contains foo:bar="oof-rab", because the @foo:bar attribute won't be bind to the appropriate implementation, but to a previous version of the implementation. However, in <foo:foo foo:version="2.1">, the <foo:foo> element will be unmarshalled with the implementation expected (version 2.1).

3.3 Module resolution

A module is loaded on behalf of a processor instance. A processor instance is created for each active sheet used. Each processor instance uses its own module resolution strategy according to its own settings.

A module is identified with a namespace URI. When a module request is raised, its namespace URI must be specified.

A processor instance will lookup for a module in its internal registry and with the help of its catalog lists. When a catalog lookup is performed, the lookup key is composed of the namespace URI of the module ; the type of the lookup key is exp:module. Please refer to the Active Catalog specification for further information about XML catalogs.

Module request

A module may be requested when unmarshalling or at runtime. Once a module is loaded, it can't be discarded from the processor instance that loads it.

A module request is raised when :

A request depends also on the processor instance settings, as explained below.

Resolution strategy

The resolution strategy of a module request depends on the processor instance settings (the directive that enables/disables the prefixes).


4 EXP module reference

EXP : Extensible XML Processor
EXP namespace URI : http://ns.inria.org/active-tags/exp
Usual prefix : exp
Elements Foreign attributes Predefined properties Data types
<exp:unmarshal>
<exp:invoke>
<exp:exports>
<exp:export>
<exp:module>
<exp:log>
<exp:log-stream>
<exp:element>
<exp:attribute>
<exp:property>
<exp:function>
<exp:init>
<exp:inactive-tags>
@exp:version
@exp:enable-prefixes
@exp:disable-prefixes
@exp:use-catalog
$exp:this
$exp:dataset
$exp:element
$exp:ns-fallback
$exp:params
$exp:args
#exp:x-processor-instance
#exp:x-dataset
#exp:x-module
#exp:element-definition
#exp:attribute-definition
#exp:property-definition
#exp:function-definition

Must be an adt:expression that computes an object of the type expected.
Must be a hard-coded value (litteral)
Can be either a hard-coded value or an adt:expression
This material may be missing
Denotes a value to use by default
Allows a read operation.
Allows a write operation.
Allows a rename operation.
Allows an update operation.
Allows a delete operation.

4.1 Elements

<exp:unmarshal>

Unmarshals an active sheet (in various types) to a processor instance (#exp:x-processor-instance).

processor inheritance

Only a few features are inherited from a processor that creates a child processor. Most of the behaviours are ruled by the default behaviour if not specified. Those inherited by the parent processor are only the followings :

runtime phase

Parameter nameRoleType
use-catalog A catalog reference. This parameter can be used several times for several catalog references. #xs:anyURI

After unmarshalling an active sheet, the <exp:unmarshal> element creates a #exp:x-processor-instance with the settings defined. It is put in the data set used by the host process if the @name attribute is specified.

The processor instance running may be also referred with the $exp:this predefined property in its host process.

Attributes runtime | hard-coded | both
NameTypeValue optional | default value
bothnameoptional#xs:QName The qualified name of the processor instance to create.
bothsource#xs:string The file name of the active sheet.
#xs:anyURI The URI where is located the active sheet.
#io:x-file The active sheet as a file.
#io:input The active sheet as an input stream.
#xml:document The active sheet as an XML document ready to unmarshal.
hard-codedenable-prefixesoptional#adt:NCNames The list of prefixes enabled in the active sheet to unmarshal.
hard-codeddisable-prefixesoptional#adt:NCNames The list of prefixes disabled in the active sheet to unmarshal.
hard-codedvalidateoptionalIndicates wether or not the active sheet must be validated.
#xs:stringyesdefault valueValidate the active sheet when unmarshalling.
progressPerform the validation while progressing the unmarshalling.
noDoesn't perform the validation. This should be used only if the active sheet has been previously been validated and is reputed valid.
hard-codedfail-fastoptionalThe behaviour of the processor instance when a non recoverable error occurs.
#xs:stringstopdefault valueThe processor must stop.
progressThe host processor goes on while the processor that causes the fault tries to lookup for other errors.
completeThe host processor wait until the processor that causes the fault tries to lookup for other errors.
[TODO: content definition]

<exp:invoke>

The <exp:invoke> element invokes the processor instance referred by the @processor attribute, or by the current object that must be a processor instance if this attribute is missing.

runtime phase

Before invoking, a parameter context is opened to initialize the data set that will be used by the processor instance.

After invoking, the <exp:exports> element may be used to keep properties defined by the processor instance invoked.

Attributes runtime | hard-coded | both
NameTypeValue optional | default value
runtimeprocessoroptional#exp:x-processor-instance A reference of the processor instance to invoke.
#io:x-file A file to unmarshal and invoke.
#io:input An input stream to unmarshal and invoke.
bothlogic-procedureoptionalThe name of the logic procedure to invoke. When missing, the startup behaviour is assumed.
#xs:QName The qualified name of the logic procedure to invoke.
#xs:string#defaultinvoke the default logic procedure.
#maininvoke the main logic procedure.
hard-codedsyncoptionalSpecify if the invoker instance must wait the end of the hosted instance or not.
#xs:stringyesdefault valueThe host process that invokes the processor instance wait it ends before continue.
noThe host process that invokes the processor instance goes on immediately.
[TODO: content definition]

<exp:exports>

Used as the optional last child of some elements :

<exp:exports> is a place holder for <exp:export> elements.

runtime phase

Runs the subactions. The runtime phase of this tag is launched after running its host action.

Attributes runtime | hard-coded | both
NameTypeValue optional | default value
runtimecurrent#any object The current object to export to the invoker data set.
runtimecontextExport a context to the invoker data set.
#adt:list of #any object Append all items to the context of the invoker data set.
#any object Append a single object to the invoker data set.
missing attribute The context is kept unchanged, that is to say it the same as before running the host action.
[TODO: content definition]

<exp:export>

Used as a descendant of the <exp:exports> element ; the <exp:export> element act on behalf of the host action of the <exp:exports> element it descends.

Exports a property to the data set handled by the host action, if any. The host action is the action that launched the processor in use. The data set updated is those used by the host action when the processor in use was launched.

Attributes runtime | hard-coded | both
NameTypeValue optional | default value
bothname#xs:QName The name of a property to export in the host action.
hard-codedscopeoptionalThe scope of the property to create in the host action.
#xs:stringglobaldefault valueThe created property is global.
localThe created property is local.
sharedThe created property is shared.
runtimevalue#any The value of the property to export ; property references are picked from the current data set.
[TODO: content definition]

<exp:module>

Defines a #exp:x-module.

unmarshal phase

Unmarshalling a module may be deferred. In this case, the module is unmarshalled only when a module request is launched.

runtime phase

Attributes runtime | hard-coded | both
NameTypeValue optional | default value
bothsourceoptional#xs:anyURI

The URI of the module when the definitions are externalized to a file. In this file, the root element is <exp:module>.

hard-codedtarget#adt:prefix

The prefix bound to the namespace URI of the module with a namespace declaration. The prefix is just used to retrieve the namespace URI.

hard-codedversion#xs:string

The version of the module. Versions are ordered in string order.

hard-codeddeferredoptionalIndicates if the definitions must be unmarshalled immediately or later.
#xs:stringyesdefault valueThe definitions are unmarshalled and processed only when expected. The materials of the module that are never used at runtime are neither unmarshalled. After unmarshalling a deferred module used, it is processed with an empty data set.
noThe definitions are unmarshalled immediately.
[TODO: content definition]

<exp:log>

Sets the level of the messages to log. [TODO: attributes definition] [TODO: content definition]

<exp:log-stream>

Indicates the log output stream. [TODO: attributes definition] [TODO: content definition]

<exp:element>

Defines an active tag (an element) on behalf of a module. Must be a descendant of <exp:module>.

runtime phase

invokation phase

If the implementation is given by inline tags, it will be invoked when this element is running in a processor instance that uses it.

Attributes runtime | hard-coded | both
NameTypeValue optional | default value
hard-codednameoptional#xs:QName The name of the element, that must be bound to the same namespace URI of the module it belongs. When omitted, this definition is used as the fallback definition for the module.
hard-codedsourceoptionalThe implementation of this active tag.
missing attribute The implementation is defined by subtags.
#xs:anyURI Refers to the implementation on a form that depends on the platform/language used.
[TODO: content definition]

<exp:attribute>

Defines a foreign attribute on behalf of a module. Must be a descendant of <exp:module>.

runtime phase

Attributes runtime | hard-coded | both
NameTypeValue optional | default value
hard-codednameoptional#xs:QName The name of the foreign attribute, that must be bound to the same namespace URI of the module it belongs. When omitted, this definition is used as the fallback definition for the module.
hard-codedsourceoptionalThe implementation of this foreign attribute.
missing attribute When no implementation is supplied, the foreign attribute is just a marker.
#xs:anyURI Refers to the implementation on a form that depends on the platform/language used.
[TODO: content definition]

<exp:property>

Defines a predefined property on behalf of a module. Must be a descendant of <exp:module>.

runtime phase

invokation phase

If the implementation is given by inline tags, it will be invoked when this element is running in a processor instance that uses it.

Attributes runtime | hard-coded | both
NameTypeValue optional | default value
hard-codednameoptional#xs:QName The name of the property, that must be bound to the same namespace URI of the module it belongs. When omitted, this definition is used as the fallback definition for the module.
hard-codedsourceoptionalThe implementation of this predefined property.
missing attribute The implementation is defined by subtags.
#xs:anyURI Refers to the implementation on a form that depends on the platform/language used.
[TODO: content definition]

<exp:function>

Defines an extended function on behalf of a module. Must be a descendant of <exp:module>.

runtime phase

invokation phase

If the implementation is given by inline tags, it will be invoked when this function is running in a processor instance that uses it.

Attributes runtime | hard-coded | both
NameTypeValue optional | default value
hard-codednameoptional#xs:QName The name of the element, that must be bound to the same namespace URI of the module it belongs. When omitted, this definition is used as the fallback definition for the module.
hard-codedsourceoptionalThe implementation of this function.
missing attribute The implementation is defined by subtags.
#xs:anyURI Refers to the implementation on a form that depends on the platform/language used.
[TODO: content definition]

<exp:init>

Sets the boundaries of an initialization phase of a macro definition.

The nested actions of the macro definition will be run before the nested actions of the caller tag of the macro. Then, the nested actions of the macro definition will be run.

Macro initialization

In this example, 3 sequences of actions will be run in the order indicated by the comment within.

The macro call :

    <acme:do-it>
        <!-- sequence n°2 -->
    </acme:do-it>

The macro definition :

    <exp:element name="acme:do-it">
        <exp:init>
            <!-- sequence n°1 -->
        </exp:init>
        <!-- sequence n°3 -->
    </exp:element>

<exp:inactive-tags>

Sets the boundaries of unmarshalling. Any nested nodes won't be unmarshalled. That is to say that they will be ignored.

4.2 Foreign attributes

@exp:version

The version of the EXP module to use. This attribute should be encountered before any EXP element, but it takes precedence on the element inside which it is hosted.


@exp:enable-prefixes

The list of prefixes to enable in the current active sheet. When used, the @exp:disable-prefixes attribute must be omitted.


@exp:disable-prefixes

The list of prefixes to disable in the current active sheet. When used, the @exp:enable-prefixes attribute must be omitted.


@exp:use-catalog

A reference to a catalog to apply on the actual active sheet. When used, the catalog is effective before unmarshalling all the materials not yet encountered (including the host element and its foreign attributes that have a lower priority).

4.3 Predefined properties

$exp:this

  • Property type: #exp:x-processor-instance
  • $exp:this is a reference to the processor instance. Notice that $this is a reference to the corresponding active sheet.


    $exp:dataset

  • Property type: #exp:x-dataset
  • $exp:dataset is a reference to the exp:x-dataset currently in use.


    $exp:element

  • Property type: #xml:element
  • $exp:element is set to the element that invokes an active tag defined by an inline implementation (macro tag).

    When the macro uses itself elements that are defined by an inline implementation, the $exp:element property is restored to the value before invokation.


    $exp:ns-fallback

  • Property type: #adt:map of #xs:anyURI
  • $exp:ns-fallback is a collection used to store additional namespace declarations needed at runtime.

    Namespaces must be declared for XML elements, attributes, and extended XPath functions. However, qualified names may also be used in content and attribute values; in this cases, if a namespace declaration is missing in the XML active sheet document, the property $exp:ns-fallback may be used to store dynamically additional namespace declarations.

    By default, $exp:ns-fallback is not defined. It is the user responsibility to add namespaces declarations at runtime.

    $exp:ns-fallback is a collection of named items; each item is defined by :

    Example using $exp:ns-fallback
    <?xml version="1.0" encoding="iso-8859-1"?>
    <xcl:active-sheet xmlns:exp="http://ns.inria.org/active-tags/exp" xmlns:xcl="http://ns.inria.org/active-tags/xcl"> <xcl:logic> <xcl:set name="exp:ns-fallback"> <xcl:item name="foo" value="http://www.foo.com/"/> <xcl:item name="oof" value="http://www.oof.com/"/> </xcl:set> <xcl:set name="foo:bar" value="This is valid"/> <xcl:set name="oof:rab" value="{$foo:bar}"/> </xcl:logic> </xcl:active-sheet>

    The two properties $foo:bar and $oof:rab will be bound to the right namespace URI defined by $exp:ns-fallback because the xmlns declaration is missing for the two prefixes foo and oof.

    A processor must try to bind the names used to the namespace URI declared when unmarshalling. Unresolved prefixes must be fix at runtime with the help of $exp:ns-fallback if it exists. It is a fatal error if a prefix can't be resolved at runtime.

    Warning

    It is the user responsability to define $exp:ns-fallback with the appropriate scope.

    This property doesn't fix namespaces violations when parsing the active-sheet.


    $exp:params

  • Property type: #adt:map of #any
  • $exp:params is a collection of named items. When an element has been defined with an inline implementation, each of its attribute will be used to feed $exp:params with an item :

    An item of the name xml:base is set to the current base location.

    Outside an element that has been defined with an inline implementation, $exp:params doesn't exists.


    $exp:args

  • Property type: #adt:list of #any
  • $exp:args is a collection of unnamed items. When an extended XPath function has been defined with an inline implementation, each of its arguments will be used to feed $exp:args with an item.

    Outside an extended XPath function that has been defined with an inline implementation, $exp:args doesn't exists.

    4.4 Extended XPath functions

    No additional functions are defined by this module.

    4.5 Data types

    #exp:x-processor-instance type

    The processor instance is the concrete engine obtained after unmarshalling an active sheet.

    Operation read | write | rename | update | delete
    TypeValueComment
    rename#xs:QName The new name of the processor instance.
    type()
    #xs:QName#exp:x-processor-instanceThis type
    name()
    read#xs:QName The name of the processor instance if any.
    string()
    read#xs:string The string name of the processor instance if any.
    parent::
    read#exp:x-processor-instance The processor instance that hosts this one, if any.
    child::
    read#adt:list of #exp:x-dataset The data sets known by this instance.
    attribute::
    read#adt:map of #xml:attribute A fixed set of attributes (see below).
    @active-sheet
    read#xml:document The XML document used for unmarshalling.
    @catalogs
    read#adt:list of #xs:anyURI The references of the catalogs registered to this processor instance.
    @default-action
    read#exp:element-definition The default action to perform.
    @main-action
    read#exp:element-definition The main action to perform.
    @disabled-prefixes
    read#adt:list of #adt:prefix The prefixes that has been explicitely disabled.
    @enabled-prefixes
    read#adt:list of #adt:prefix The prefixes that has been explicitely enabled.
    @modules
    read#adt:map{ of #xs:anyURI, of #xs:string} The modules known by this processor instance. The key of an entry in the map is the namespace URI of a module. The value is the version of the module.
    @procedures
    read#adt:map of #exp:element-definition

    The procedures defined for this processor instance. The key of the map is the qualified name of the procedures.

    @shared-properties
    read#adt:map of #any object The properties of the processor instance that will be shared by all data set that will run on it.
    @status
    The status of the processor instance.
    read#xs:stringrunnableready to process data sets.
    readyready to unmarshal.
    unmarshallingis currently unmarshalling its active sheet.
    failfail to unmarshal.

    #exp:x-dataset type

    The data set is used to store the properties computed at runtime.

    Operation read | write | rename | update | delete
    TypeValueComment
    rename#xs:QName The new name of the dataset.
    type()
    #xs:QName#exp:x-datasetThis type
    name()
    read#xs:QName The name of the dataset if any.
    string()
    read#xs:string The string name of the dataset if any.
    parent::
    read#exp:x-processor-instance The processor instance that uses this dataset.
    child::
    read#adt:map of #any object The properties of the dataset.
    attribute::
    read#adt:map of #xml:attribute A fixed set of attributes (see below).
    @current
    read#any object The current object.
    @context
    read#adt:list of #any object The context.
    @local-properties
    read#adt:map of #any object The local properties of the dataset.
    @global-properties
    read#adt:map of #any object The global properties of the dataset.
    @shared-properties
    read#adt:map of #any object The shared properties of the dataset.
    @main-action
    read#exp:element-definition The main action that uses this dataset, if any.

    #exp:x-module type

    A module contains the definitions of the active tags materials.

    Operation read | write | rename | update | delete
    TypeValueComment
    type()
    #xs:QName#exp:x-moduleThis type
    string()
    read#xs:string The namespace URI of the module.
    attribute::
    read#adt:map of #xml:attribute A fixed set of attributes (see below).
    @target
    read#xs:anyURI The namespace URI of the module.
    @version
    read#xs:string The version of this module.
    @versions
    read#adt:list of #exp:x-module All the versions of the module, sorted by version.
    @elements
    read#adt:list of #xs:QName The elements defined by this module.
    @attributes
    read#adt:list of #xs:QName The foreign attributes defined by this module.
    @properties
    read#adt:list of #xs:QName The predefined properties defined by this module.
    @functions
    read#adt:list of #xs:QName The extended functions defined by this module.

    #exp:element-definition type

    A formal type for the implementation of an active tag.


    #exp:attribute-definition type

    A formal type for the implementation of a foreign attribute.


    #exp:property-definition type

    A formal type for the implementation of a predefined property.


    #exp:function-definition type

    A formal type for the implementation of a function.


    Appendix

    A Glossary

    B Related Active Tags specifications

    This list is not exhaustive; it is a list of common modules usable by an engine that implements the Active Tags specifications that implementors may use. Additional modules are welcome.

    C Lists

    C.1 Examples list

    C.2 Figures list