Overview | Package | Class | Use | Tree | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## gnu.xml.pipeline
Class NSFilter

    java.lang.Object
      |
      +--gnu.xml.pipeline.EventFilter
            |
            +--gnu.xml.pipeline.NSFilter

All Implemented Interfaces:
  ContentHandler, DeclHandler, DTDHandler, EventConsumer, LexicalHandler

public class NSFilter
extends EventFilter

This filter ensures that element and attribute names are properly prefixed, and that such prefixes are declared. Such data is critical for operations like writing XML text, and validating against DTDs: names or their prefixes may have been discarded, although they are essential to the exchange of information using XML. There are various common ways that such data gets discarded:

- By default, SAX2 parsers must discard the "xmlns*" attributes, and may also choose not to report properly prefixed names for elements or attributes. (Some parsers may support changing the namespace-prefixes value from the default to true, effectively eliminating the need to use this filter on their output.)
- When event streams are generated from a DOM tree, they may have never have had prefixes or declarations for namespaces; or the existing prefixes or declarations may have been invalidated by structural modifications to that DOM tree.
- Other software writing SAX event streams won't necessarily be worrying about prefix management, and so they will need to have a transparent solution for managing them.

This filter uses a heuristic to choose the prefix to assign to any particular name which wasn't already corectly prefixed. The associated namespace will be correct, and the prefix will be declared. Original structures facilitating text editing, such as conventions about use of mnemonic prefix names or the scoping of prefixes, can't always be reconstructed after they are discarded, as strongly encouraged by the current SAX2 defaults.

Note that this can't possibly know whether values inside attribute value or document content involve prefixed names. If your application requires using prefixed names in such locations you'll need to add some appropriate logic (perhaps adding additional heuristics in a subclass).

Version:
  $Date: 2001/11/09 22:53:17 $
Author:
  David Brownell

Fields inherited from class gnu.xml.pipeline.EventFilter
`DECL_HANDLER, FEATURE_URI, LEXICAL_HANDLER, PROPERTY_URI`

Constructor Summary
`NSFilter(EventConsumer next)` Passes events through to the specified consumer, after first processing them.

Method Summary
`void` | `endDocument()` SAX2: passes this callback to the next consumer, if any
`void` | `endElement(java.lang.String uri, java.lang.String localName, java.lang.String qName)` SAX2: passes this callback to the next consumer, if any
`void` | `endPrefixMapping(java.lang.String prefix)` This call is not passed to the next consumer in the chain.
`void` | `startDocument()` SAX2: passes this callback to the next consumer, if any
`void` | `startElement(java.lang.String uri, java.lang.String localName, java.lang.String qName, Attributes atts)` SAX2: passes this callback to the next consumer, if any
`void` | `startPrefixMapping(java.lang.String prefix, java.lang.String uri)` This call is not passed to the next consumer in the chain.

Methods inherited from class gnu.xml.pipeline.EventFilter
`attributeDecl, bind, chainTo, characters, comment, elementDecl, endCDATA, endDTD, endEntity, externalEntityDecl, getContentHandler, getDocumentLocator, getDTDHandler, getErrorHandler, getNext, getProperty, ignorableWhitespace, internalEntityDecl, notationDecl, processingInstruction, setContentHandler, setDocumentLocator, setDTDHandler, setErrorHandler, setProperty, skippedEntity, startCDATA, startDTD, startEntity, unparsedEntityDecl`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### NSFilter

    public NSFilter(EventConsumer next)

  Passes events through to the specified consumer, after first processing them.
  Parameters:
    `next` - the next event consumer to receive events.

Method Detail

### startDocument

    public void startDocument()
                       throws SAXException

  Description copied from class: `EventFilter`
  SAX2: passes this callback to the next consumer, if any
  Overrides:
    `startDocument` in class `EventFilter`
  Following copied from interface: `org.xml.sax.ContentHandler`
  Throws:
    `SAXException` - Any SAX exception, possibly wrapping another exception.
  See Also:
    `ContentHandler.endDocument()`

### startPrefixMapping

    public void startPrefixMapping(java.lang.String prefix,
                                   java.lang.String uri)
                            throws SAXException

  This call is not passed to the next consumer in the chain. Prefix declarations and scopes are only exposed in the form of attributes; this callback just records a declaration that will be exposed as an attribute.
  Overrides:
    `startPrefixMapping` in class `EventFilter`
  Following copied from interface: `org.xml.sax.ContentHandler`
  Parameters:
    `prefix` - The Namespace prefix being declared.
    `uri` - The Namespace URI the prefix is mapped to.
  Throws:
    `SAXException` - The client may throw an exception during processing.
  See Also:
    `ContentHandler.endPrefixMapping(java.lang.String)`, `ContentHandler.startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)`

### startElement

    public void startElement(java.lang.String uri,
                             java.lang.String localName,
                             java.lang.String qName,
                             Attributes atts)
                      throws SAXException

  Description copied from class: `EventFilter`
  SAX2: passes this callback to the next consumer, if any
  Overrides:
    `startElement` in class `EventFilter`
  Following copied from interface: `org.xml.sax.ContentHandler`
  Parameters:
    `uri` - The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.
    `localName` - The local name (without prefix), or the empty string if Namespace processing is not being performed.
    `qName` - The qualified name (with prefix), or the empty string if qualified names are not available.
    `atts` - The attributes attached to the element. If there are no attributes, it shall be an empty Attributes object.
  Throws:
    `SAXException` - Any SAX exception, possibly wrapping another exception.
  See Also:
    `ContentHandler.endElement(java.lang.String, java.lang.String, java.lang.String)`, `Attributes`

### endElement

    public void endElement(java.lang.String uri,
                           java.lang.String localName,
                           java.lang.String qName)
                    throws SAXException

  Description copied from class: `EventFilter`
  SAX2: passes this callback to the next consumer, if any
  Overrides:
    `endElement` in class `EventFilter`
  Following copied from interface: `org.xml.sax.ContentHandler`
  Parameters:
    `uri` - The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.
    `localName` - The local name (without prefix), or the empty string if Namespace processing is not being performed.
    `qName` - The qualified XML 1.0 name (with prefix), or the empty string if qualified names are not available.
  Throws:
    `SAXException` - Any SAX exception, possibly wrapping another exception.

### endPrefixMapping

    public void endPrefixMapping(java.lang.String prefix)
                          throws SAXException

  This call is not passed to the next consumer in the chain. Prefix declarations and scopes are only exposed in their attribute form.
  Overrides:
    `endPrefixMapping` in class `EventFilter`
  Following copied from interface: `org.xml.sax.ContentHandler`
  Parameters:
    `prefix` - The prefix that was being mapping.
  Throws:
    `SAXException` - The client may throw an exception during processing.
  See Also:
    `ContentHandler.startPrefixMapping(java.lang.String, java.lang.String)`, `ContentHandler.endElement(java.lang.String, java.lang.String, java.lang.String)`

### endDocument

    public void endDocument()
                     throws SAXException

  Description copied from class: `EventFilter`
  SAX2: passes this callback to the next consumer, if any
  Overrides:
    `endDocument` in class `EventFilter`
  Following copied from interface: `org.xml.sax.ContentHandler`
  Throws:
    `SAXException` - Any SAX exception, possibly wrapping another exception.
  See Also:
    `ContentHandler.startDocument()`

Overview | Package | Class | Use | Tree | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Source code is under GPL (with library exception) in the JAXP project at http://www.gnu.org/software/classpathx/jaxp
This documentation was derived from that source code on 2001-11-20.