← Back to branch summary

~ubuntu-branches/ubuntu/precise/libjcommon-java/precise

« back to all changes in this revision

Viewing changes to source/org/jfree/xml/Parser.java

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2006-10-01 14:12:07 UTC
  • mfrom: (1.1.2 upstream) (4 edgy)
  • mto: This revision was merged to the branch mainline in revision 6.
  • Revision ID: james.westby@ubuntu.com-20061001141207-2aipqlhpmn45t3ng
New upstream release.

Show diffs side-by-side

added added

removed removed

Lines of Context:
source/org/jfree/xml/Parser.java
 
1
/* ========================================================================
 
2
 * JCommon : a free general purpose class library for the Java(tm) platform
 
3
 * ========================================================================
 
4
 *
 
5
 * (C) Copyright 2000-2005, by Object Refinery Limited and Contributors.
 
6
 * 
 
7
 * Project Info:  http://www.jfree.org/jcommon/index.html
 
8
 *
 
9
 * This library is free software; you can redistribute it and/or modify it 
 
10
 * under the terms of the GNU Lesser General Public License as published by 
 
11
 * the Free Software Foundation; either version 2.1 of the License, or 
 
12
 * (at your option) any later version.
 
13
 *
 
14
 * This library is distributed in the hope that it will be useful, but 
 
15
 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 
 
16
 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public 
 
17
 * License for more details.
 
18
 *
 
19
 * You should have received a copy of the GNU Lesser General Public
 
20
 * License along with this library; if not, write to the Free Software
 
21
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, 
 
22
 * USA.  
 
23
 *
 
24
 * [Java is a trademark or registered trademark of Sun Microsystems, Inc. 
 
25
 * in the United States and other countries.]
 
26
 * 
 
27
 * -----------
 
28
 * Parser.java
 
29
 * -----------
 
30
 * (C)opyright 2003-2005, by Thomas Morgner and Contributors.
 
31
 *
 
32
 * Original Author:  Thomas Morgner (taquera@sherito.org);
 
33
 * Contributor(s):   David Gilbert (for Object Refinery Limited);
 
34
 *
 
35
 * $Id: Parser.java,v 1.8 2005/11/14 10:58:02 mungady Exp $
 
36
 *
 
37
 * Changes
 
38
 * -------
 
39
 * 09-Jan-2003 : Initial version.
 
40
 * 29-Apr-2003 : Distilled from the JFreeReport project and moved into JCommon
 
41
 * 14-Jul-2003 : More help with the error location given by catching all exceptions.
 
42
 * 
 
43
 */
 
44
 
 
45
package org.jfree.xml;
 
46
 
 
47
import java.util.HashMap;
 
48
import java.util.Stack;
 
49
 
 
50
import org.xml.sax.Attributes;
 
51
import org.xml.sax.SAXException;
 
52
 
 
53
/**
 
54
 * The Parser handles the SAXEvents and forwards the event call to the currently
 
55
 * active ElementDefinitionHandler. Contains methods to manage and
 
56
 * configure the parsing process.
 
57
 * <p>
 
58
 * An initial report definition handler must be set before the parser can be used.
 
59
 *
 
60
 * @author Thomas Morgner
 
61
 */
 
62
public abstract class Parser extends FrontendDefaultHandler {
 
63
 
 
64
    /** A key for the content base. */
 
65
    public static final String CONTENTBASE_KEY = "content-base";
 
66
 
 
67
    /** A stack for the active factories. */
 
68
    private Stack activeFactories;
 
69
 
 
70
    /** The initial factory. */
 
71
    private ElementDefinitionHandler initialFactory;
 
72
 
 
73
    /** Storage for temporary objects and factories used during the parsing process. */
 
74
    private HashMap parserHelperObjects;
 
75
 
 
76
    /**
 
77
     * Creates a new parser.
 
78
     */
 
79
    public Parser() {
 
80
        this.activeFactories = new Stack();
 
81
        this.parserHelperObjects = new HashMap();
 
82
    }
 
83
 
 
84
    /**
 
85
     * Returns the currently collected comments.
 
86
     * @return the comments.
 
87
     */
 
88
    public String[] getComments() {
 
89
        return getCommentHandler().getComments();
 
90
    }
 
91
 
 
92
    /**
 
93
     * Pushes a handler onto the stack.
 
94
     *
 
95
     * @param factory  the handler.
 
96
     */
 
97
    public void pushFactory(final ElementDefinitionHandler factory) {
 
98
        this.activeFactories.push(factory);
 
99
    }
 
100
 
 
101
    /**
 
102
     * Reads a handler off the stack without removing it.
 
103
     *
 
104
     * @return The handler.
 
105
     */
 
106
    public ElementDefinitionHandler peekFactory() {
 
107
        return (ElementDefinitionHandler) this.activeFactories.peek();
 
108
    }
 
109
 
 
110
    /**
 
111
     * Pops a handler from the stack.
 
112
     *
 
113
     * @return The handler.
 
114
     */
 
115
    public ElementDefinitionHandler popFactory() {
 
116
        this.activeFactories.pop();
 
117
        return peekFactory();
 
118
    }
 
119
 
 
120
    /**
 
121
     * Receive notification of the end of the document.
 
122
     *
 
123
     * <p>By default, do nothing.  Application writers may override this
 
124
     * method in a subclass to take specific actions at the end
 
125
     * of a document (such as finalising a tree or closing an output
 
126
     * file).</p>
 
127
     *
 
128
     * @exception SAXException Any SAX exception, possibly wrapping another exception.
 
129
     *
 
130
     * @see org.xml.sax.ContentHandler#endDocument
 
131
     */
 
132
    public void endDocument() throws SAXException {
 
133
        // ignored
 
134
    }
 
135
 
 
136
    /**
 
137
     * Receive notification of the beginning of the document.
 
138
     *
 
139
     * <p>By default, do nothing.  Application writers may override this
 
140
     * method in a subclass to take specific actions at the beginning
 
141
     * of a document (such as allocating the root node of a tree or
 
142
     * creating an output file).</p>
 
143
     *
 
144
     * @exception SAXException Any SAX exception, possibly wrapping another exception.
 
145
     * @see org.xml.sax.ContentHandler#startDocument
 
146
     */
 
147
    public void startDocument() throws SAXException {
 
148
        this.activeFactories.clear();
 
149
        pushFactory(getInitialFactory());
 
150
    }
 
151
 
 
152
    /**
 
153
     * Receive notification of character data inside an element.
 
154
     *
 
155
     * <p>By default, do nothing.  Application writers may override this
 
156
     * method to take specific actions for each chunk of character data
 
157
     * (such as adding the data to a node or buffer, or printing it to
 
158
     * a file).</p>
 
159
     *
 
160
     * @param ch  the characters.
 
161
     * @param start  the start position in the character array.
 
162
     * @param length  the number of characters to use from the character array.
 
163
     *
 
164
     * @exception SAXException Any SAX exception, possibly wrapping another exception.
 
165
     * @see org.xml.sax.ContentHandler#characters
 
166
     */
 
167
    public void characters(final char[] ch, final int start, final int length)
 
168
        throws SAXException {
 
169
        try {
 
170
            peekFactory().characters(ch, start, length);
 
171
        }
 
172
        catch (ParseException pe) {
 
173
            throw pe;
 
174
        }
 
175
        catch (Exception e) {
 
176
            throw new ParseException(e, getLocator());
 
177
        }
 
178
    }
 
179
 
 
180
    /**
 
181
     * Receive notification of the end of an element.
 
182
     *
 
183
     * <p>By default, do nothing.  Application writers may override this
 
184
     * method in a subclass to take specific actions at the end of
 
185
     * each element (such as finalising a tree node or writing
 
186
     * output to a file).</p>
 
187
     *
 
188
     * @param uri  the URI.
 
189
     * @param localName  the element type name.
 
190
     * @param qName  the name.
 
191
     *
 
192
     * @exception SAXException Any SAX exception, possibly
 
193
     *            wrapping another exception.
 
194
     * @see org.xml.sax.ContentHandler#endElement
 
195
     */
 
196
    public void endElement(final String uri, final String localName, final String qName)
 
197
        throws SAXException {
 
198
        try {
 
199
            peekFactory().endElement(qName);
 
200
        }
 
201
        catch (ParseException pe) {
 
202
            throw pe;
 
203
        }
 
204
        catch (Exception e) {
 
205
            throw new ParseException(e, getLocator());
 
206
        }
 
207
        finally {
 
208
            getCommentHandler().clearComments();
 
209
        }
 
210
    }
 
211
 
 
212
 
 
213
    /**
 
214
     * Receive notification of the start of an element.
 
215
     *
 
216
     * <p>By default, do nothing.  Application writers may override this
 
217
     * method in a subclass to take specific actions at the start of
 
218
     * each element (such as allocating a new tree node or writing
 
219
     * output to a file).</p>
 
220
     *
 
221
     * @param uri  the URI.
 
222
     * @param localName  the element type name.
 
223
     * @param qName  the name.
 
224
     * @param attributes  the specified or defaulted attributes.
 
225
     *
 
226
     * @exception SAXException Any SAX exception, possibly
 
227
     *            wrapping another exception.
 
228
     * @see org.xml.sax.ContentHandler#startElement
 
229
     */
 
230
    public void startElement(final String uri, final String localName,
 
231
                             final String qName, final Attributes attributes)
 
232
        throws SAXException {
 
233
        try {
 
234
            peekFactory().startElement(qName, attributes);
 
235
        }
 
236
        catch (ParseException pe) {
 
237
            throw pe;
 
238
        }
 
239
        catch (Exception e) {
 
240
            throw new ParseException(e, getLocator());
 
241
        }
 
242
        finally {
 
243
            getCommentHandler().clearComments();
 
244
        }
 
245
    }
 
246
 
 
247
    /**
 
248
     * Sets the initial handler.
 
249
     *
 
250
     * @param factory  the initial handler.
 
251
     */
 
252
    public void setInitialFactory(final ElementDefinitionHandler factory) {
 
253
        this.initialFactory = factory;
 
254
    }
 
255
 
 
256
    /**
 
257
     * Returns the initial handler.
 
258
     *
 
259
     * @return The initial handler.
 
260
     */
 
261
    public ElementDefinitionHandler getInitialFactory() {
 
262
        return this.initialFactory;
 
263
    }
 
264
 
 
265
    /**
 
266
     * Sets a helper object.
 
267
     * 
 
268
     * @param key  the key.
 
269
     * @param value  the value.
 
270
     */
 
271
    public void setHelperObject(final String key, final Object value) {
 
272
        if (value == null) {
 
273
            this.parserHelperObjects.remove(key);
 
274
        }
 
275
        else {
 
276
            this.parserHelperObjects.put(key, value);
 
277
        }
 
278
    }
 
279
 
 
280
    /**
 
281
     * Returns a helper object.
 
282
     * 
 
283
     * @param key  the key.
 
284
     * 
 
285
     * @return The object.
 
286
     */
 
287
    public Object getHelperObject(final String key) {
 
288
        return this.parserHelperObjects.get(key);
 
289
    }
 
290
 
 
291
    /**
 
292
     * Returns a new instance of the parser.
 
293
     *
 
294
     * @return a new instance of the parser.
 
295
     */
 
296
    public abstract Parser getInstance();
 
297
 
 
298
 
 
299
    public final FrontendDefaultHandler newInstance() {
 
300
        return getInstance();
 
301
    }
 
302
 
 
303
    /**
 
304
     * Returns the parsed result object after the parsing is complete. Calling
 
305
     * this function during the parsing is undefined and may result in an
 
306
     * IllegalStateException.
 
307
     *
 
308
     * @return the parsed result.
 
309
     */
 
310
    public abstract Object getResult();
 
311
}