git.gag.com Git - debian/openrocket/blob - core/src/net/sf/openrocket/file/simplesax/ElementHandler.java

   1 package net.sf.openrocket.file.simplesax;
   2
   3 import java.util.HashMap;
   4
   5 import net.sf.openrocket.aerodynamics.WarningSet;
   6
   7 import org.xml.sax.SAXException;
   8
   9
  10 /**
  11  * A "simple XML" element handler.  An object of this class handles a single element of
  12  * an XML file.  If the input file is:
  13  *
  14  *   <foo>
  15  *     <bar>message</bar>
  16  *   </foo>
  17  *
  18  * and the initial handler is initHandler, then the following methods will be called:
  19  *
  20  * 1. initHandler.openElement(String, HashMap, WarningSet) is called for the opening element <foo>, which returns fooHandler
  21  * 2. fooHandler.openElement(String, HashMap, WarningSet) is called for the opening element <bar>, which returns barHandler
  22  * 3. barHandler.endHandler(String, HashMap, String, WarningSet) is called for the closing element </bar>
  23  * 4. fooHandler.closeElement(String, HashMap, String, WarningSet) is called for the closing element </bar>
  24  * 5. fooHandler.endHandler(String, HashMap, String, WarningSet) is called for the closing element </foo>
  25  * 6. initHandler.closeElement(String, HashMap, String, WarningSet) is called for the closing element </foo>
  26  *
  27  * Note that endHandler(String, HashMap, String, WarningSet) is not called for the initial handler.
  28  *
  29  * @author Sampo Niskanen <sampo.niskanen@iki.fi>
  30  */
  31 public interface ElementHandler {
  32
  33         /**
  34          * Called when an opening tag of a contained element is encountered.  Returns the handler
  35          * that will handle the elements within that element, or <code>null</code> if the element
  36          * and all of its contents is to be ignored.
  37          * <p>
  38          * Note that this method may also return <code>this</code>, in which case this
  39          * handler will also handle the subelement.
  40          *
  41          * @param element               the element name.
  42          * @param attributes    attributes of the element.
  43          * @param warnings              the warning set to store warnings in.
  44          * @return                              the handler that handles elements encountered within this element,
  45          *                                              or <code>null</code> if the element is to be ignored.
  46          */
  47         public ElementHandler openElement(String element, HashMap<String, String> attributes,
  48                         WarningSet warnings) throws SAXException;
  49
  50         /**
  51          * Called when a closing tag of a contained element is encountered.
  52          * <p>
  53          * This method can be used to handle the textual content of the element for simple text
  54          * elements, which is passed in as the "content" parameter.
  55          *
  56          * @param element               the element name.
  57          * @param attributes    attributes of the element.
  58          * @param content               the textual content of the element.
  59          * @param warnings              the warning set to store warnings in.
  60          */
  61         public abstract void closeElement(String element, HashMap<String, String> attributes,
  62                         String content, WarningSet warnings) throws SAXException;
  63
  64         /**
  65          * Called when the current element that this handler is handling is closed.
  66          *
  67          * @param warnings              the warning set to store warnings in.
  68          */
  69         public abstract void endHandler(String element, HashMap<String, String> attributes,
  70                         String content, WarningSet warnings) throws SAXException;
  71
  72 }