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.Warning;
   6 import net.sf.openrocket.aerodynamics.WarningSet;
   7
   8 import org.xml.sax.SAXException;
   9
  10
  11 /**
  12  * A "simple XML" element handler.  An object of this class handles a single element of
  13  * an XML file.  If the input file is:
  14  *
  15  *   <foo>
  16  *     <bar>message</bar>
  17  *   </foo>
  18  *
  19  * and the initial handler is initHandler, then the following methods will be called:
  20  *
  21  * 1. initHandler.{@link #openElement(String, HashMap, WarningSet)} is called for
  22  *       the opening element <bar>, which returns fooHandler
  23  * 2. fooHandler.{@link #openElement(String, HashMap, WarningSet)} is called for
  24  *       the opening element <bar>, which returns barHandler
  25  * 3. barHandler.{@link #endHandler(String, HashMap, String, WarningSet)} is called for
  26  *       the closing element </bar>
  27  * 4. fooHandler.{@link #closeElement(String, HashMap, String, WarningSet)} is called for
  28  *       the closing element </bar>
  29  * 5. fooHandler.{@link #endHandler(String, HashMap, String, WarningSet)} is called for
  30  *       the closing element </foo>
  31  * 6. initHandler.{@link #closeElement(String, HashMap, String, WarningSet)} is called for
  32  *       the closing element </foo>
  33  *
  34  * Note that {@link #endHandler(String, HashMap, String, WarningSet)} is not called for
  35  * the initial handler.
  36  *
  37  * @author Sampo Niskanen <sampo.niskanen@iki.fi>
  38  */
  39 public abstract class ElementHandler {
  40
  41         /**
  42          * Called when an opening element is encountered.  Returns the handler that will handle
  43          * the elements within that element, or <code>null</code> if the element and all of
  44          * its contents is to be ignored.
  45          * <p>
  46          * Note that this method may also return <code>this</code>, in which case this
  47          * handler will also handle the subelement.
  48          *
  49          * @param element               the element name.
  50          * @param attributes    attributes of the element.
  51          * @param warnings              the warning set to store warnings in.
  52          * @return                              the handler that handles elements encountered within this element,
  53          *                                              or <code>null</code> if the element is to be ignored.
  54          */
  55         public abstract ElementHandler openElement(String element,
  56                         HashMap<String, String> attributes, WarningSet warnings) throws SAXException;
  57
  58         /**
  59          * Called when an element is closed.  The default implementation checks whether there is
  60          * any non-space text within the element and if there exists any attributes, and adds
  61          * a warning of both.  This can be used at the and of the method to check for
  62          * spurious data.
  63          *
  64          * @param element               the element name.
  65          * @param attributes    attributes of the element.
  66          * @param content               the textual content of the element.
  67          * @param warnings              the warning set to store warnings in.
  68          */
  69         public void closeElement(String element, HashMap<String, String> attributes,
  70                         String content, WarningSet warnings) throws SAXException {
  71
  72                 if (!content.trim().equals("")) {
  73                         warnings.add(Warning.fromString("Unknown text in element '" + element
  74                                         + "', ignoring."));
  75                 }
  76                 if (!attributes.isEmpty()) {
  77                         warnings.add(Warning.fromString("Unknown attributes in element '" + element
  78                                         + "', ignoring."));
  79                 }
  80         }
  81
  82
  83         /**
  84          * Called when the element block that this handler is handling ends.
  85          * The default implementation is a no-op.
  86          *
  87          * @param warnings              the warning set to store warnings in.
  88          */
  89         public void endHandler(String element, HashMap<String, String> attributes,
  90                         String content, WarningSet warnings) throws SAXException {
  91                 // No-op
  92         }
  93
  94 }