DTRules/src/main/java/com/dtrules/xmlparser/IGenericXMLParser.java

   1 /*
   2  * $Id$
   3  *
   4  * Copyright 2004-2007 MTBJ, Inc.
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  *      http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  */
  18
  19 package com.dtrules.xmlparser;
  20
  21 import java.io.IOException;
  22 import java.util.HashMap;
  23
  24 /**
  25  * This is a simple interface for handling parsing events
  26  * from the generic parser.  At this time, only two events
  27  * are generated, the beginTag and the endTag events.  The
  28  * endTag() provides the body, if present.
  29  * Creation date: (9/15/2003 8:35:17 AM)
  30  * @author: Paul Snow, MTBJ, Inc.
  31  */
  32 public interface IGenericXMLParser {
  33
  34         /**
  35          * The beginTag method is called when the parser detects the
  36          * each begin tag in the XML file being parsed.  When one uses
  37          * a SAX parser, the class implementing the interface is responsible
  38          * for keeping up with the context of the tags as they are
  39          * encountered and closed.  The GenericXMLParser provides a
  40          * stack of all the tags currently open when the begin tag
  41          * is encountered.  This is the actual stack maintained by the
  42          * GenericXMLParser, which is maintained as an array of tags.
  43          * The tagstkptr provides an index into this array. <br><br>
  44          * The attributes associated with the tag are provided as a
  45          * hashmap of key/Value pairs. <br><br>
  46          *
  47          * @param tagstk A stack of tags active at the time the tag was encountered.
  48          * @param tagstkptr A pointer into the tag stack to the top of stack.
  49          * @param tag The tag encountered.
  50          * @param attribs A hash map of attributes as a set of key/Value pairs.
  51          * @throws IOException If an error occurs while parsing the XML, this exception will be thrown.
  52          * @throws Exception If the tags are not matched, or an unexpected character is encountered, an
  53          *                   exception will be thrown.
  54          */
  55         public void beginTag(
  56                 String tagstk[],
  57                 int tagstkptr,
  58                 String tag,
  59                 HashMap<String, String> attribs)
  60                 throws IOException, Exception;
  61
  62     /**
  63          * The endTag method is called when the parser detects the
  64          * each end tag in the XML file being parsed.  When one uses
  65          * a SAX parser, the class implementing the interface is responsible
  66          * for keeping up with the context of the tags as they are
  67          * encountered and closed.  The GenericXMLParser provides a
  68          * stack of all the tags currently open when the end tag
  69          * is encountered.  The GenericXMLParser also provides the
  70          * attributes of the begin tag to the end tag as well.
  71          *  <br><br>
  72          *
  73          * @param tagstk A stack of tags active at the time the tag was encountered.
  74          * @param tagstkptr A pointer into the tag stack to the top of stack.
  75          * @param tag The tag encountered.
  76          * @param body the body (if any) of the data between the begin and end tags.
  77          * @param attribs A hash map of attributes as a set of key/Value pairs.
  78          * @throws IOException If an error occurs while parsing the XML, this exception will be thrown.
  79          * @throws Exception If the tags are not matched, or an unexpected character is encountered, an
  80          *                   exception will be thrown.
  81         **/
  82         public void endTag(
  83                 java.lang.String[] tagstk,
  84                 int tagstkptr,
  85                 String tag,
  86                 String body,
  87                 HashMap<String,String> attribs)
  88                 throws Exception, IOException;
  89
  90         /**
  91          * When an error is encountered by the parser, the error method
  92          * is called on the class implementing the IGenericXMLParser
  93          * interface.  This method returns true if parsing should continue.
  94          * @param v This is the error string from the GenericXMLParser
  95          */
  96         public boolean error(String v)
  97                 throws Exception; // Returns true if parsing should continue.
  98 }