The com.simonstl.namespace package

Intro | Contents | Rules | Future | License | Download

This package provides SAX Filters for forcibly namespace-qualifying selected elements and attributes, storing context-based namespace information in attributes, for removing namespace information, and for replacing one namespace with another.

This set of tools allows developers to work with documents created by other developers who may have had a slightly different perspective on the application of Namespaces in XML. (For information on some general issues surrounding Namespaces, see Namespaces in XML: Best Practices, Risky Business and Schema Scuffles and Namespace Pains.)

The package contains seven filters. The first two add namespace information, with one namespace-qualifies unqualified child elements according to their parent or ancestor's namespace, and the other qualifying unqualified attributes to match their containing element's namespace. A third filter allows developers to add namespace-context information to unqualified elements through attributes without actually qualifying the elements. Two filters strip namespaces from elements and attributes, and two more allow replacements of namespaces with other specified namespaces.

All of the filters use similar rules and languages for definining those rules, though the rules use different namespaces (to facilitate mixing them) and the impact of those rules is quite different. (The replacement filters have a slightly different vocabulary, addressing different needs.)

Contents

Specifying rules for processing

Rules may be specified either through a Java interface (the addRule() method of NamespaceRules or ReplaceNamespaceRules) or through a rules file. (If no rules object is assigned to the qualifying or annotating filters, every element or attribute will be processed, while the stripping files will refrain from stripping namespaces. Nothing will happen to documents passing through the replacement filters if no replacements are specified.)

Rules specify which namespaces should or should not be processed. The RulesLoader will parse an XML file containing include and exclude elements in the namespaces indicating the type of rule. The rules for the filters in this package all use the same vocabulary (except for the replacement filter), but each filter uses its own namespace to identify its rules.

For example, to qualify all unqualified elements in a document except those in a namespace context of http://simonstl.com/person:

<namespaces xmlns="http://simonstl.com/ns/namespaces/elements/">
  <include nsURI="##any" />
  <exclude nsURI="http://simonstl.com/person" />
</namespaces>

Or, to strip all namespaces from attributes in a document except those regarding XLink:

<namespaces xmlns="http://simonstl.com/ns/namespaces/attributes/strip/">
  <include nsURI="##any" />
  <exclude nsURI="http://www.w3.org/1999/xlink" />
</namespaces>

Both the include and exclude elements have a nsURI attribute which contains either a namespace URI or the magic value ##any, borrowed from W3C XML Schema. ##any matches any namespace URI, while all other values match only the URIs specified. Exclusions always override inclusions, making it possible to use ##any to include all values and then use exclude on specific namespaces.

Replacements look a little different. Instead of include and exclude, a replace element contains attributes indicating what namespaces should be replaced, and what the replacement should be:

<namespaces xmlns="http://simonstl.com/ns/namespaces/elements/replace/">
<replace matchURI="http://simonstl.com/person" 
  resultURI="http://example.com/" 
  resultPrefix="example"/>
</namespaces>

In this case, any elements in the http://simonstl.com/person namespace will become members of the http://example.com/ namespace, and given the prefix example.

Future changes:

This package is fairly stable, if immature. The primary change I plan to make involves converting the rule loaders into SAX Filters, so that rule processing can be combined into multi-level processing of a single file. I'm moving most of the rule examples to RDDL files for the appropriate namespaces. Documentation is currently behind. There will eventually be some substantial refactoring to eliminate the currently huge volume of duplicate code.

License

The contents of this package are subject to the Mozilla Public License Version 1.1 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.mozilla.org/MPL/.

Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License.

The Original Code is available at http://simonstl.com/projects/fragment/original.

The Initial Developer of the Original Code is Simon St.Laurent. Portions created by Simon St.Laurent are Copyright (C) 2001 Simon St.Laurent. All Rights Reserved.

Contributor(s):

Download

• Version 0.05 - reorganized documentation, support RDDL.
• Version 0.04 - fixed ElementAnnotNamespaceFilter.
• Version 0.03 - added namespace replacement features (not yet documented), bug-prone alternative (ElementAnnotNamespaceFilter) to forced qualification.
• Version 0.02 - added namespace stripping features, fixed a bug in the attribute qualifying, updated docs
• Version 0.01 - initial release

JavaDoc for these packages is also available.

Intro | Contents | Rules | Future | License | Download