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: */
19: public interface XMLEventAllocator {
20:
21: /**
22: * This method creates an instance of the XMLEventAllocator. This
23: * allows the XMLInputFactory to allocate a new instance per reader.
24: */
25: public XMLEventAllocator newInstance();
26:
27: /**
28: * This method allocates an event given the current
29: * state of the XMLStreamReader. If this XMLEventAllocator
30: * does not have a one-to-one mapping between reader states
31: * and events this method will return null. This method
32: * must not modify the state of the XMLStreamReader.
33: * @param reader The XMLStreamReader to allocate from
34: * @return the event corresponding to the current reader state
35: */
36: public XMLEvent allocate(XMLStreamReader reader)
37: throws XMLStreamException;
38:
39: /**
40: * This method allocates an event or set of events
41: * given the current
42: * state of the XMLStreamReader and adds the event
43: * or set of events to the
44: * consumer that was passed in. This method can be used
45: * to expand or contract reader states into event states.
46: * This method may modify the state of the XMLStreamReader.
47: * @param reader The XMLStreamReader to allocate from
48: * @param consumer The XMLEventConsumer to add to.
49: */
50: public void allocate(XMLStreamReader reader,
51: XMLEventConsumer consumer) throws XMLStreamException;
52:
53: }
|