01 package javax.xml.stream.util;
02
03 import javax.xml.stream.events.XMLEvent;
04 import javax.xml.stream.XMLStreamReader;
05 import javax.xml.stream.XMLStreamException;
06
07 /**
08 * This interface defines a class that allows a user to register
09 * a way to allocate events given an XMLStreamReader. An implementation
10 * is not required to use the XMLEventFactory implementation but this
11 * is recommended. The XMLEventAllocator can be set on an XMLInputFactory
12 * using the property "javax.xml.stream.allocator"
13 *
14 * @version 1.0
15 * @author Copyright (c) 2003 by BEA Systems. All Rights Reserved.
16 * @see javax.xml.stream.XMLInputFactory
17 * @see javax.xml.stream.XMLEventFactory
18 * @since 1.6
19 */
20 public interface XMLEventAllocator {
21
22 /**
23 * This method creates an instance of the XMLEventAllocator. This
24 * allows the XMLInputFactory to allocate a new instance per reader.
25 */
26 public XMLEventAllocator newInstance();
27
28 /**
29 * This method allocates an event given the current
30 * state of the XMLStreamReader. If this XMLEventAllocator
31 * does not have a one-to-one mapping between reader states
32 * and events this method will return null. This method
33 * must not modify the state of the XMLStreamReader.
34 * @param reader The XMLStreamReader to allocate from
35 * @return the event corresponding to the current reader state
36 */
37 public XMLEvent allocate(XMLStreamReader reader)
38 throws XMLStreamException;
39
40 /**
41 * This method allocates an event or set of events
42 * given the current
43 * state of the XMLStreamReader and adds the event
44 * or set of events to the
45 * consumer that was passed in. This method can be used
46 * to expand or contract reader states into event states.
47 * This method may modify the state of the XMLStreamReader.
48 * @param reader The XMLStreamReader to allocate from
49 * @param consumer The XMLEventConsumer to add to.
50 */
51 public void allocate(XMLStreamReader reader,
52 XMLEventConsumer consumer) throws XMLStreamException;
53
54 }
|