1 /*
   2  * Copyright (c) 2009, 2020, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.xml.stream.util;
  27 
  28 import javax.xml.stream.events.XMLEvent;
  29 import javax.xml.stream.XMLStreamReader;
  30 import javax.xml.stream.XMLStreamException;
  31 
  32 /**
  33  * This interface defines a class that allows a user to register
  34  * a way to allocate events given an XMLStreamReader.  An implementation
  35  * is not required to use the XMLEventFactory implementation but this
  36  * is recommended.  The XMLEventAllocator can be set on an XMLInputFactory
  37  * using the property "javax.xml.stream.allocator"
  38  *
  39  * @version 1.0
  40  * @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved.
  41  * @see javax.xml.stream.XMLInputFactory
  42  * @see javax.xml.stream.XMLEventFactory
  43  * @since 1.6
  44  */
  45 public interface XMLEventAllocator {
  46 
  47   /**
  48    * This method creates an instance of the XMLEventAllocator. This
  49    * allows the XMLInputFactory to allocate a new instance per reader.
  50    * @return an instance of the {@code XMLEventAllocator}
  51    */
  52   public XMLEventAllocator newInstance();
  53 
  54   /**
  55    * This method allocates an event given the current
  56    * state of the XMLStreamReader.  If this XMLEventAllocator
  57    * does not have a one-to-one mapping between reader states
  58    * and events this method will return null.  This method
  59    * must not modify the state of the XMLStreamReader.
  60    * @param reader The XMLStreamReader to allocate from
  61    * @return the event corresponding to the current reader state
  62    * @throws XMLStreamException if an error occurs
  63    */
  64   public XMLEvent allocate(XMLStreamReader reader)
  65     throws XMLStreamException;
  66 
  67   /**
  68    * This method allocates an event or set of events
  69    * given the current
  70    * state of the XMLStreamReader and adds the event
  71    * or set of events to the
  72    * consumer that was passed in.  This method can be used
  73    * to expand or contract reader states into event states.
  74    * This method may modify the state of the XMLStreamReader.
  75    * @param reader The XMLStreamReader to allocate from
  76    * @param consumer The XMLEventConsumer to add to.
  77    * @throws XMLStreamException if an error occurs
  78    */
  79   public void allocate(XMLStreamReader reader, XMLEventConsumer consumer)
  80     throws XMLStreamException;
  81 
  82 }