Package org.apache.cocoon.xml.sax

Class NamespacesTable

  • public class NamespacesTable
extends java.lang.Object
    Keeps track of namespaces declarations and resolve namespaces names.

    This class also provides a very convenient and safe way of handling namespace declarations in SAX pipes. It also allows to filter duplicate namespace declarations that too often clutter up XML documents that went through several transformations, and avoid useless namespace declarations that aren't followed by element events.

    Usage example in a SAX pipe: 

       NamespacesTable namespaces = new NamespacesTable();
   ContentHandler nextHandler;

   public void startPrefixMapping(String prefix, String uri) throws SAXException {
       namespaces.addDeclaration(prefix, uri);
   }

   public void startElement(...) throws SAXException {
       // automatically start mappings for this scope
       namespaces.enterScope(nextHandler);
       nextHandler.startElement(...);
   }

   public void endElement(...) throws SAXException {
       nextHandler.endElement(...);
       // automatically end mappings for this scope
       namespaces.leaveScope(nextHandler);
   }

   public void endPrefixMapping(String prefix) throws SAXException {
       // Ignore, it is handled by leaveScope()
   }

    • Constructor Summary

      Constructors 
      Constructor Description
      NamespacesTable()
      Construct a new NamespacesTable instance.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      NamespacesTable.Declaration addDeclaration​(java.lang.String prefix, java.lang.String uri)
      Declare a new namespace prefix-uri mapping.
      void clear()
      Clear and reinitialize this namespace table before reuse.
      void enterScope()
      Enter a new scope.
      void enterScope​(org.xml.sax.ContentHandler handler)
      Start all declared mappings of the current scope and enter a new scope.
      NamespacesTable.Declaration[] getCurrentScopeDeclarations()
      Get the declarations that were declared within the current scope.
      java.lang.String getPrefix​(java.lang.String uri)
      Return one of the prefixes currently mapped to the specified URI or null.
      java.lang.String[] getPrefixes​(java.lang.String uri)
      Return an array with all prefixes currently mapped to the specified URI.
      java.lang.String getUri​(java.lang.String prefix)
      Return the URI associated with the given prefix or null if the prefix was not mapped.
      void leaveScope()
      Leave a scope.
      void leaveScope​(org.xml.sax.ContentHandler handler)
      Leave a scope.
      NamespacesTable.Declaration removeDeclaration​(java.lang.String prefix)
      Undeclare a namespace prefix-uri mapping.
      NamespacesTable.Name resolve​(java.lang.String uri, java.lang.String raw, java.lang.String prefix, java.lang.String local)
      Resolve a namespace-aware name against the current namespaces declarations.

      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • NamespacesTable

        public NamespacesTable()
        Construct a new NamespacesTable instance.

    • Method Detail

      • clear

        public void clear()
        Clear and reinitialize this namespace table before reuse.
        Since:
        2.1.8

      • addDeclaration

        public NamespacesTable.Declaration addDeclaration​(java.lang.String prefix,
                                                  java.lang.String uri)
        Declare a new namespace prefix-uri mapping.
        Returns:
        The newly added Declaration.

      • removeDeclaration

        public NamespacesTable.Declaration removeDeclaration​(java.lang.String prefix)
        Undeclare a namespace prefix-uri mapping. If the prefix was previously declared mapping another URI, its value is restored.

        When using enterScope()/leaveScope(), this method does nothing and always returns null, as declaration removal is handled in leaveScope().

        Returns:
        the removed Declaration or null.

      • enterScope

        public void enterScope()
        Enter a new scope. This starts a new, empty list of declarations for the new scope.

        Typically called in a SAX handler before sending a startElement() event.

        Since:
        2.1.8

      • enterScope

        public void enterScope​(org.xml.sax.ContentHandler handler)
                throws org.xml.sax.SAXException
        Start all declared mappings of the current scope and enter a new scope. This starts a new, empty list of declarations for the new scope.

        Typically called in a SAX handler before sending a startElement() event.

        Parameters:
        handler - the handler that will receive startPrefixMapping events.
        Throws:
        org.xml.sax.SAXException
        Since:
        2.1.8

      • leaveScope

        public void leaveScope()
        Leave a scope. The namespace declarations that occured before the corresponding enterScope() are no more visible using the resolution methods, but still available using getCurrentScopeDeclarations() until the next call to addDeclaration(String, String) or enterScope().

        Typically called in a SAX handler after sending a endElement() event.

        Since:
        2.1.8

      • leaveScope

        public void leaveScope​(org.xml.sax.ContentHandler handler)
                throws org.xml.sax.SAXException
        Leave a scope. The namespace declarations that occured before the corresponding enterScope() are no more visible using the resolution methods, but still available using getCurrentScopeDeclarations() until the next call to addDeclaration(String, String) or enterScope().

        Typically called in a SAX handler after sending a endElement() event.

        Parameters:
        handler - the handler that will receive endPrefixMapping events.
        Throws:
        org.xml.sax.SAXException
        Since:
        2.1.8

      • getCurrentScopeDeclarations

        public NamespacesTable.Declaration[] getCurrentScopeDeclarations()
        Get the declarations that were declared within the current scope.
        Returns:
        the declarations (possibly empty, but never null)
        Since:
        2.1.8

      • getUri

        public java.lang.String getUri​(java.lang.String prefix)
        Return the URI associated with the given prefix or null if the prefix was not mapped.

      • getPrefixes

        public java.lang.String[] getPrefixes​(java.lang.String uri)
        Return an array with all prefixes currently mapped to the specified URI.
        The array length might be zero if no prefixes are associated with the specified uri.
        Returns:
        A non-null String array.

      • getPrefix

        public java.lang.String getPrefix​(java.lang.String uri)
        Return one of the prefixes currently mapped to the specified URI or null.

      • resolve

        public NamespacesTable.Name resolve​(java.lang.String uri,
                                    java.lang.String raw,
                                    java.lang.String prefix,
                                    java.lang.String local)
                             throws org.xml.sax.SAXException
        Resolve a namespace-aware name against the current namespaces declarations.
        Parameters:
        uri - The namespace URI or null if not known.
        raw - The raw (complete) name or null if not known.
        prefix - The namespace prefix or null if not known.
        local - The local name or null if not known.
        Returns:
        A non-null Name.
        Throws:
        org.xml.sax.SAXException - If the name cannot be resolved.