10.6.3 Anatomy of an RVML SAX Handler

/****************************************************************
 * Copyright (c) 2005, Kinesis Software Ltd, All rights reserved.
 ****************************************************************/
package com.kinesis.xml;
 
    
**
 * Interface for all Element handlers in KineticFusion
 */
public interface KFSaxElementHandlerType {
    /**
     * Called when a sub element is encountered for the element handled by this
     * handler. This will return the handler capable of handling the sub-element
     * or null if the sub-element handler cannot be found
     * 
     * @param namespaceURI
     * @param localName
     * @param qName
     * @param atts
     * @return The handler for processing the specified element
     * @throws Exception
     */
    public KFSaxElementHandlerType startSubElement(String namespaceURI, 
            String localName, String qName, AttributeProcessorType atts) 
            throws Exception;
 
    
    /**
     * Returns true if closure of sub element was handled successfully
     * 
     * @param namespaceURI
     * @param localName
     * @return true if closure of sub element was handled
     *                successfully
     * @throws Exception
     */
    public boolean endSubElement(String namespaceURI, String localName) 
                                                          throws Exception;
 
    
    /**
     * Add a persistent child element handler to this handler. The handler will
     * be be automatically returned when the specified element name and
     * namespace are encountered
     * 
     * @param namespace
     * @param elementName
     * @param handler
     * @return true if the ElementHandler supports the addition
     *                of persistent child element handlers
     */
        public boolean addGeneralSubElementHandler(String namespace, 
                                             String elementName,
                                             KFSaxElementHandlerType handler);
 
    
    /**
     * Add a persistent child element handler to this handler. The handler will
     * be be automatically returned when any element with the specified
     * namespace is encountered
     * 
     * @param namespace
     * @param handler
     * @return true if the ElementHandler supports the addition
     *                of persistent child namespace handlers
     */
    public boolean addGeneralSubElementHandler(String namespace, 
                                               KFSaxElementHandlerType handler);
 
    
    /**
     * Handle the current start element declaration, parsing and processing all
     * attributes. Returns true if element was handled successfully.
     * 
     * @param namespaceURI
     *                  The namespace of the element
     * @param localName
     *                  The local name of the element
     * @param qName
     *                  The qualified name of the element
     * @param atts
     *                  Attribute processor providing resolved attribute values
     * @return true if the start element event was handled
     *                successfully
     * @throws Exception
     */
    public boolean handleElement(String namespaceURI, String localName,
                        String qName, AttributeProcessorType atts) throws Exception;
 
    
    /**
     * Perform any end-of-element processing
     * 
     * @return true if element was handled successfully
     * @throws Exception
     */
    public boolean endElement() throws Exception;
 
    
    /**
     * Process character data for the current element
     * 
     * @param ch
     * @param start
     * @param length
     * @return true if characters were handled successfully
     * @throws Exception
     */
    public boolean characters(char[] ch, int start, int length) throws Exception;
 }