AbstractHandler


1   /* ====================================================================
2    * 
3    * The ObjectStyle Group Software License, version 1.1
4    * ObjectStyle Group - http://objectstyle.org/
5    * 
6    * Copyright (c) 2002-2005, Andrei (Andrus) Adamchik and individual authors
7    * of the software. All rights reserved.
8    * 
9    * Redistribution and use in source and binary forms, with or without
10   * modification, are permitted provided that the following conditions
11   * are met:
12   * 
13   * 1. Redistributions of source code must retain the above copyright
14   *    notice, this list of conditions and the following disclaimer.
15   * 
16   * 2. Redistributions in binary form must reproduce the above copyright
17   *    notice, this list of conditions and the following disclaimer in
18   *    the documentation and/or other materials provided with the
19   *    distribution.
20   * 
21   * 3. The end-user documentation included with the redistribution, if any,
22   *    must include the following acknowlegement:
23   *    "This product includes software developed by independent contributors
24   *    and hosted on ObjectStyle Group web site (http://objectstyle.org/)."
25   *    Alternately, this acknowlegement may appear in the software itself,
26   *    if and wherever such third-party acknowlegements normally appear.
27   * 
28   * 4. The names "ObjectStyle Group" and "Cayenne" must not be used to endorse
29   *    or promote products derived from this software without prior written
30   *    permission. For written permission, email
31   *    "andrus at objectstyle dot org".
32   * 
33   * 5. Products derived from this software may not be called "ObjectStyle"
34   *    or "Cayenne", nor may "ObjectStyle" or "Cayenne" appear in their
35   *    names without prior written permission.
36   * 
37   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
38   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
39   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
40   * DISCLAIMED.  IN NO EVENT SHALL THE OBJECTSTYLE GROUP OR
41   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
42   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
43   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
44   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
45   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
46   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
47   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
48   * SUCH DAMAGE.
49   * ====================================================================
50   * 
51   * This software consists of voluntary contributions made by many
52   * individuals and hosted on ObjectStyle Group web site.  For more
53   * information on the ObjectStyle Group, please see
54   * <http://objectstyle.org/>.
55   */
56  package org.objectstyle.cayenne.util;
57  
58  import org.xml.sax.Attributes  ;
59  import org.xml.sax.ContentHandler  ;
60  import org.xml.sax.SAXException  ;
61  import org.xml.sax.XMLReader  ;
62  import org.xml.sax.helpers.DefaultHandler  ;
63  
64  
65  /**
66   * The common superclass for all SAX event handlers used to parse
67   * the configuration file. Each method just throws an exception, 
68   * so subclasses should override what they can handle.
69   *
70   * Each type of XML element (map, node, etc.) has
71   * a specific subclass.
72   *
73   * In the constructor, this class takes over the handling of SAX
74   * events from the parent handler and returns
75   * control back to the parent in the endElement method.
76   * <p>
77   * The idea to use nested handlers for XML document parsing
78   * (and code to implement it) were taken from org.apache.tools.ant.ProjectHelper 
79   * from Jakarta-Ant project (Copyright: Apache Software Foundation).
80   * This may not be the best way to build objects from XML, but it is rather 
81   * consistent. For each nested element in the XML tree a dedicated handler
82   * is created (subclass of this AbstractHandler). Once the element is parsed, 
83   * control is handled back to the parent handler.
84   * </p>
85   *
86   * @author Andrei Adamchik 
87   */
88  public class AbstractHandler extends DefaultHandler   {
89      /** Current parser. */
90      protected XMLReader   parser;
91  
92      /** Previous handler for the document.
93       * When the next element is finished, control returns
94       * to this handler. */
95      protected ContentHandler   parentHandler;
96  
97      /**
98       * Creates a handler and sets the parser to use it
99       * for the current element.
100      * 
101      * @param parser  Currently used XML parser. 
102      *                Must not be <code>null</code>.
103      * @param parentHandler The handler which should be restored to the 
104      *                      parser at the end of the element. 
105      *                      Must not be <code>null</code>.
106      */
107     public AbstractHandler(XMLReader   parser, ContentHandler   parentHandler) {
108         this.parentHandler = parentHandler;
109         this.parser = parser;
110 
111         // Start handling SAX events
112         parser.setContentHandler(this);
113     }
114 
115     /** Returns currently used XMLReader. */
116     public XMLReader   getParser() {
117         return parser;
118     }
119 
120 
121     /**
122      * Handles the start of an element. This base implementation just
123      * throws an exception.
124      * 
125      * @exception SAXException if this method is not overridden, or in
126      *                              case of error in an overridden version
127      */
128     public void startElement(String   namespaceURI, String   localName, String   qName, Attributes   atts)
129     throws SAXException   {
130         throw new SAXException  (this.getClass().getName() + ": unexpected element \"" + localName + "\"");
131     }
132 
133     /**
134      * Handles text within an element. This base implementation just
135      * throws an exception.
136      * 
137      * @param buf A character array of the text within the element.
138      *            Will not be <code>null</code>.
139      * @param start The start element in the array.
140      * @param count The number of characters to read from the array.
141      * 
142      * @exception SAXException if this method is not overridden, or in
143      *                              case of error in an overridden version
144      */
145     public void characters(char[] buf, int start, int count) throws SAXException   {
146         String   s = new String  (buf, start, count).trim();
147 
148         if (s.length() > 0) {
149             throw new SAXException  (this.getClass().getName() + ": unexpected text \"" + s + "\"");
150         }
151     }
152 
153     /**
154      * Called when this element and all elements nested into it have been
155      * handled.
156      */
157     protected void finished() {}
158 
159 
160     /**
161      * Handles the end of an element. Any required clean-up is performed
162      * by the finished() method and then the original handler is restored to
163      * the parser.
164      * 
165      * @see #finished()
166      */
167     public void endElement(String   namespaceURI, String   localName, String   qName)
168     throws SAXException   {
169         finished();
170         // Let parent resume handling SAX events
171         parser.setContentHandler(parentHandler);
172     }
173 }
174 
175
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags