net.sf.xolite.XMLEventParser Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of xo-lite Show documentation
This project provides a lightweight framework to serialize/deserialize (or marshall/unmarshall) java objects into XML. The implementation is based on standard SAX (Simple Api for Xml) but it follows a original approach based on the strong data encapsulation paradigm of Object Oriented (OO) programming.
The newest version!
/*-------------------------------------------------------------------------
 Copyright 2006 Olivier Berlanger

 Licensed under the Apache License, Version 2.0 (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.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
 -------------------------------------------------------------------------*/
package net.sf.xolite;


import java.util.Iterator;

import javax.xml.namespace.NamespaceContext;


/**
 * Interface for parsing XML with simplified event handling. This class is like a SAX parser keeping itself its state (locator,
 * started elements, prefix mapping, characters, ...) rather than pushing it to a client handler. The result is a simpler document
 * handler with only two methods remaining (@link XMLSerializable).
 * 
 * Although this interface is based on SAX mechanism, it's quite independent from SAX implementation. It doesn't expose any SAX
 * class or interface.
 * 
 */
public interface XMLEventParser extends NamespaceContext {

    /**
     * Get NamespacePrefixResolver mapping the prefix to the namespace URI. A copy of the current mapping object of
     * this parser at the moment of the call is returned.
     */
    public NamespaceContext getCurrentDefinedNamespaces();


    /**
     * Delegates the parsing of a XML fragment to an other SaxHandler. When this handler have finished to parse the
     * data belonging to it, it will call the endParsing(..) method and the current parser will receive again the XML
     * parsing events. 

     * This method should be called from inside a startElement(..) method, the same startElement method (with same
     * parameters) is called against the delegated (handlerOfSubElements) object by the parser.
     * 
     * @param handlerOfSubElements
     *            the XMLSerializable that will receive the next 'simplified SAX' events from the XMLEventParser.
     */
    public void delegateParsingTo(XMLSerializable handlerOfSubElements) throws XMLParseException;


    /**
     * Create the XMLSerializable object corresponding to the given XML element, delegates the parsing to it and return the created
     * object. 

     * Note: when returned the created object has not yet finished it's parsing. Only the first startElement(..) method has been
     * called on it. 

     * This method will work only if there is a factory defined and this factory knows the given element. It is equivalent to:
     * 
     *      * XMLSerializable child = parser.getFactory().createObject(uri, localName, parser);
     * parser.delegateParsingTo(child, uri, localName);
     * return child;
     * 
     */
    public XMLSerializable parseElement(String uri, String localName) throws XMLParseException;


    /**
     * Get the last object that called endParsing(..) method on the parser.
     * 
     * @return the last object that called endParsing(..) method on the parser.
     */
    public XMLSerializable getLastParsedObject() throws XMLParseException;


    /**
     * Resolve a qualified name to it's namespace URI + local name. As the SAX parser does it automatically for elements tags or
     * attributes, this method is useful only for elements/attributes values containing qualified names.
     * 
     * To map the prefix, this method will use the prefix mappings of the parsed document. If no prefix mapping is defined for a
     * given prefix, an exception is thrown. When no prefix is defined, this method will try to find the default prefix mapping, but
     * if no default mapping is defined, no exception is thrown (in this case, the URI of the returned NamespacedName
     * is null).
     * 
     * @param qName
     *            a qualified name (like: "xs:element").
     * @return NamespacedName containing the namespace URI and the local name of the given qualified name. (the prefix is not kept).
     * @throws XMLParseException
     *             If the qualified name contains a prefix not mapped to a namespace.
     */
    public NamespacedName getQualifiedName(String qName) throws XMLParseException;


    /**
     * Get the content of the text buffer. Usually, this method is called when the end of the element (containing the text) is
     * notified by a SAX event.
     * 

     *  Use the ElementText helper class to get, parse, validate and format easily the element text. 
     * 
     * 
     * Calling this method from a startElement notification is useful only when parsing XML with mixed content. In this
     * case you got the text just before the started element.
     * 
     * 
     * @return the text data of the current XML element.
     */
    public String getElementText();


    /**
     * Get a factory able to instantiate objects corresponding to XML elements. This method never returns null, if the factory is
     * not defined an exception is thrown.
     * 
     * @return a factory able to instantiate objects corresponding to XML elements.
     * @throws XMLParseException
     *             if the factory is not defined.
     */
    public XMLObjectFactory getFactory() throws XMLParseException;


    /**
     * Put a custom object in an internal Map. 

     * It can be retrieved later with getCustomObject(key) method.
     * 
     * @param key
     *            key of the custom object.
     * @param value
     *            custom object.
     */
    public void putCustomObject(Object key, Object value);


    /**
     * Get back any custom object that was put in with the putCustomObject(key, value) method.
     * 
     * @param key
     *            key of the custom object.
     * @return the custom object.
     */
    public Object getCustomObject(Object key);


    /**
     * Get the namespace URI and local name of the current element.
     * 
     * @return the namespace URI and local name of the current element.
     */
    public NamespacedName getCurrentElementName();


    /**
     * 'true' iff the startElement call is the first one called to the XMLSerializable currently receiving it. 

     * This method can be useful for recursive XML when an object can contain itself. In this case, when startElement
     * is called the parsed object can use this method to know if the notified event is the start of itself or the start of a direct
     * sub-object. 

     * Calling this method makes sense only from inside a startElement method implementation.
     * 
     * @return true iff it's the first time startElement is called against the XMLSerializable.
     */
    public boolean isFirstEvent();


    /**
     * 'true' iff the endElement call is the last one called to the XMLSerializable currently receiving it. 

     * This method can be useful for recursive XML when an object can contain itself. In this case, when endElement is
     * called, the parsed object can use this method to know if the notified event is the end of itself or the end of a direct
     * sub-object. 

     * Calling this method makes sense only from inside a endElement method implementation.
     * 
     * @return true iff it's the first time startElement is called against the XMLSerializable.
     */
    public boolean isLastEvent();


    // --------------------------------- Exception management -----------------------------------

    /**
     * Throw an exception telling that the namespace of the current element (the one that was just passed to a
     * startElement(..) or endElement(..) method) is unexpected. If the expected namespace URI is passed
     * as parameter, it is added in the message. 

     * The current location of the parser (current element tag, current line, current column, file name) is added to the message if
     * available.
     * 
     * @param expectedURI
     *            the expected namespace URI. If null, no expected namespace URI is mentioned in the exception message.
     */
    public void throwUnexpectedNamespaceException(String expectedURI) throws XMLParseException;


    /**
     * Throw an exception telling that the current element (the one that was just passed to a startElement(..) or
     * endElement(..) method) is unexpected. If the expected tags are passed as parameter, they are added in the
     * message. 

     * The current location of the parser (current element tag, current line, current column, file name) is added to the message if
     * available.
     * 
     * @param expectedTags
     *            the expected element tag(s). If you expect several different tags, you can enumerate them in this parameter (for
     *            example by separating them with commas). It is simply added in the exception message. If null, no expected tags
     *            are mentioned in the exception message.
     */
    public void throwUnexpectedElementException(String expectedTags) throws XMLParseException;


    /**
     * Throw an exception with given message and cause. 

     * The current location of the parser (current element tag, current line, current column, file name) is added to the message if
     * available.
     * 
     * @param message
     *            the exception message (rem: parser location is added).
     * @param cause
     *            the exception cause
     */
    public void throwParseException(String message, Throwable cause) throws XMLParseException;


    // --------------------------------- Attribute management -----------------------------------

    /**
     * Get an attribute value. If the requested attribute is not defined (because it is optional), null is returned.
     * 
     * @param attrName
     *            the name of the attribute.
     * @return the requested attribute value.
     */
    public String getAttributeValue(String attrName) throws XMLParseException;


    /**
     * Get value of an attribute with namespace. If the requested attribute is not defined (because it is optional), the null is
     * returned.
     * 
     * This method allows to specify the namespace of the attribute. In most of the case attributes are not associated to
     * namespaces. It is not necessary because attributes definitions are, in most of the case, local to the definition of the
     * element containing it. So this method should be rarely used (use the corresponding method without namespace parameter).
     * Examples of attributes using namespaces are: 'xml:lang' or 'xmlns:prefix'. To get values of those attributes you must provide
     * the namespace URI.
     * 
     * 
     * @param attrNamespaceURI
     *            the namespace URI of the attribute.
     * @param attrName
     *            the name of the attribute.
     * @return the requested attribute value.
     */
    public String getAttributeValueNS(String attrNamespaceURI, String attrName) throws XMLParseException;


    /**
     * Get an iterator on namespaces of all the attributes present in the current element. 

     * 
     * @return Iterator on namespaces of all the attributes present in the current element.
     */
    public Iterator getAttributeNamespaceIterator() throws XMLParseException;


    /**
     * Get an iterator on names of all the attributes present in the current element and belonging to the given namespace. 

     * Use null as namespace for attributes not bound to a namespace (i.e. most of the attributes).
     * 
     * @param attrNamespaceURI
     *            namespace of the attributes or null for attributes without namespaces.
     * @return Iterator on names of all the attributes present in the current element and belonging to the given namespace.
     */
    public Iterator getAttributeNameIterator(String attrNamespaceURI) throws XMLParseException;

}