This method allocates an event given the current state of the XMLStreamReader.

  This method allocates an event given the current
state of the XMLStreamReader. If this XMLEventAllocator
does not have a one-to-one mapping between reader states
and events this method will return null. This method
must not modify the state of the XMLStreamReader.
Returns: the event corresponding to the current reader state
Parameters:
- reader - The XMLStreamReader to allocate from

  This method allocates an event or set of events given the current state of the XMLStreamReader and adds the event or set of events to the consumer that was passed in.

  This method allocates an event or set of events
given the current
state of the XMLStreamReader and adds the event
or set of events to the
consumer that was passed in. This method can be used
to expand or contract reader states into event states.
This method may modify the state of the XMLStreamReader.
Parameters:
- reader - The XMLStreamReader to allocate from
- consumer - The XMLEventConsumer to add to.

  This method creates an instance of the XMLEventAllocator.

  This method creates an instance of the XMLEventAllocator. This
allows the XMLInputFactory to allocate a new instance per reader.