The com.simonstl.namespace package

See:
          Description

Packages
com.simonstl.namespace Provides utility classes used by the child elements and attributes packages.
com.simonstl.namespace.attributes A set of SAXFilters for modifying or removing the namespaces of attributes.
com.simonstl.namespace.elements A set of SAXFilters for modifying or removing the namespaces of elements.

 

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

This package contains seven filters and some supporting classes shared by all of them. The com.simonstl.namespace package contains only supporting classes, while the com.simonstl.namespace.elements and com.simonstl.namespace.attributes packages contain the actual filters.

Three classes are provided for each filter. The classes ending in NamespaceFilter are the actual SAX Filters, while classes ending RulesLoader initialize the filters according to XML-based rules. The classes ending in FilterTester allow command line testing of the filters.

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.

Namespace (click URI for info)FilterUsage
http://simonstl.com/ns/ namespaces/elements/ com.simonstl.namespace. elements.ElementNamespaceFilter for rules defining which elements should be qualified. nsURI identifies parent namespaces which should be applied to their unqualified child elements or not.
http://simonstl.com/ns/ namespaces/elements/annotate/ com.simonstl.namespace. elements.AnnotElementNamespaceFilter for rules defining which elements should be annotated with namespace context information. nsURI identifies parent namespaces which should be indicated in their unqualified child elements as an attribute or not.
http://simonstl.com/ns/ namespaces/attributes/ com.simonstl.namespace. attributes.AttributeNamespaceFilter for rules defining which attributes should be qualified with the namespace of their containing element. nsURI identifies element namespaces which should be applied to their unqualified attributes or not.
http://simonstl.com/ns/ namespaces/elements/strip/ com.simonstl.namespace. elements.ElementStripNamespaceFilter for rules defining which elements have their namespace information removed or not. nsURI identifies namespaces which should be removed or not removed.
http://simonstl.com/ns/ namespaces/attributes/strip/ com.simonstl.namespace. attributes.AttributeStripNamespaceFilter for rules defining which attributes should have their namespace information removed or not. nsURI identifies namespaces which should be removed or not removed.
http://simonstl.com/ns/ namespaces/elements/replace/ com.simonstl.namespace. elements.ElementReplNamespaceFilter for rules defining which elements have their namespace information replaced. matchURI identifies namespaces which should be replaced, resultURI specifies the replacement URI, and the optional resultPrefix allows the specification of a namespace prefix.
http://simonstl.com/ns/ namespaces/attributes/replace/ com.simonstl.namespace. attributes.AttributeReplNamespaceFilter for rules defining which attributes have their namespace information replaced. matchURI identifies namespaces which should be replaced, resultURI specifies the replacement URI, and the optional resultPrefix allows the specification of a namespace prefix.

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

JavaDoc for these packages is also available.

Intro | Contents | Rules | Future | License | Download