Package org.apache.sis.internal.storage.xml.stream

Class StaxDataStore

java.lang.Object
org.apache.sis.storage.DataStore
org.apache.sis.internal.storage.URIDataStore
org.apache.sis.internal.storage.xml.stream.StaxDataStore
All Implemented Interfaces:
AutoCloseable, ResourceOnFileSystem, StoreResource, Resource, Localized
Direct Known Subclasses:
Store
public abstract class StaxDataStore extends URIDataStore
Base class of XML data stores based on the StAX framework.
Since:
0.8
Version:
1.3

  • Field Details

    • locale

      protected final Locale locale
      The locale to use for locale-sensitive data (not for logging or warning messages), or null if unspecified.
      See Also:

    • timezone

      protected final TimeZone timezone
      The timezone to use when parsing or formatting dates and times without explicit timezone, or null if unspecified.
      See Also:

    • encoding

      protected final Charset encoding
      The character encoding of the file content, or null if unspecified. This is often (but not always) ignored at reading time, but taken in account at writing time.

    • configuration

      final StaxDataStore.Config configuration
      Configuration information for JAXB (un)marshaller (actually the SIS wrappers) or for the StAX factories. This object is a read-only map which may contain the following entries:
      • XML.LOCALE — the locale to use for locale-sensitive data (not for logging or warning messages).
      • XML.TIMEZONE — the timezone to use when parsing or formatting dates and times without explicit timezone.
      In addition, the StaxDataStore.Config class also implements various listener interfaces to be given to JAXB (un)marshallers (actually the SIS wrappers) and StAX factories configuration.
      See Also:

    • storage

      private Object storage
      The storage object given by the user. May be Path, URL, InputStream, OutputStream, Reader, Writer, XMLStreamReader, XMLStreamWriter, Node or some other types that the StAX framework can handle.

      A null value means that this datastore has been closed.

      See Also:

    • stream

      private AutoCloseable stream
      The underlying stream to close when this StaxDataStore is closed, or null if none. This is often the same reference than storage if the latter is closeable, but not always. For example if storage is a Path, then stream will be some stream or channel opened for that path.

      We keep this reference as long as possible in order to use mark() and reset() instead of creating new streams for re-reading the data. If we cannot reset the stream but can create a new one, then this field will become a reference to the new stream. This change should be done only in last resort, when there is no way to reuse the existing stream. This is because the streams created by ChannelFactory.inputStream(String, StoreListeners) are not of the same kind than the streams created by StorageConnector.

      See Also:

    • streamPosition

      private long streamPosition
      Position of the first byte to read in the stream, or a negative value if unknown. If the position is positive, then the stream should have been marked at that position by the constructor.
      See Also:

    • storageToReader

      private final InputType storageToReader
      The function in charge of producing a XMLStreamReader from the storage or stream. This field is null if the XML file is write-only or if storage is a Path.

    • storageToWriter

      private final OutputType storageToWriter
      The function in charge of producing a XMLStreamWriter for the storage or stream. This field is null if the XML file is read-only or if storage is a Path.

    • inputFactory

      private XMLInputFactory inputFactory
      The StAX readers factory, created when first needed.
      See Also:

    • outputFactory

      private XMLOutputFactory outputFactory
      The StAX writers factory, created when first needed.
      See Also:

    • channelFactory

      private final ChannelFactory channelFactory
      Object to use for creating new input streams if we need to read the same data more than once. This field is null if we cannot re-open new input streams.

    • indentation

      private final byte indentation
      The number of spaces to use in indentations, or -1 if the XML output should not be formatted. This is ignored at reading time.

    • state

      private byte state
      Whether the stream is currently in use by a StaxStreamIO. Value can be one of START, READING, WRITING or FINISHED constants.

    • START

      private static final byte START
      Possible states for the state field.
      See Also:

    • READING

      private static final byte READING
      Possible states for the state field.
      See Also:

    • WRITING

      private static final byte WRITING
      Possible states for the state field.
      See Also:

    • FINISHED

      private static final byte FINISHED
      Possible states for the state field.
      See Also:

  • Constructor Details

    • StaxDataStore

      protected StaxDataStore(StaxDataStoreProvider provider, StorageConnector connector) throws DataStoreException
      Creates a new data store. The provider is mandatory if the data store will use JAXB, otherwise it is optional.
      Parameters:
      provider - the provider of this data store, or null if unspecified.
      connector - information about the storage (URL, stream, etc).
      Throws:
      DataStoreException - if the input or output type is not recognized.

  • Method Details

    • mark

      private void mark() throws IOException
      Marks the current stream position. This method shall be invoked either at construction time, or after a new stream has been created.
      Throws:
      IOException

    • reset

      private boolean reset() throws IOException
      Resets the stream position to the mark created at construction time, then marks again the stream for allowing future resets.
      Returns:
      true of success, or false if the stream cannot be reset.
      Throws:
      IOException - if an error occurred while resetting the stream.

    • getProvider

      public final StaxDataStoreProvider getProvider()
      Returns the factory that created this DataStore instance, or null if unspecified.
      Overrides:
      getProvider in class DataStore
      Returns:
      the factory that created this DataStore instance, or null if unspecified.
      See Also:

    • getFormatName

      public final String getFormatName()
      Returns the short name (abbreviation) of the format being read or written. This is used for error messages.
      Returns:
      short name of format being read or written.
      See Also:

    • inputFactory

      final XMLInputFactory inputFactory()
      Returns the factory for StAX readers. The same instance is returned for all StaxDataStore lifetime. Warnings emitted by readers created by this factory will be forwarded to the DataStore.listeners.

      This method is indirectly invoked by createReader(StaxStreamReader), through a call to InputType.create(StaxDataStore, Object).

    • outputFactory

      final XMLOutputFactory outputFactory()
      Returns the factory for StAX writers. The same instance is returned for all StaxDataStore lifetime.

      This method is indirectly invoked by #createWriter(StaxStreamWriter, Object), through a call to OutputType.create(StaxDataStore, Object).

    • createReader

      final XMLStreamReader createReader(StaxStreamReader target) throws Exception
      Creates a new XML stream reader for reading the document from its position at StaxDataStore creation time. If another XMLStreamReader has already been created before this method call, whether this method will succeed in creating a new reader depends on the storage type (e.g. file or input stream) or on whether the previous reader has been closed.
      Parameters:
      target - the reader which will store the XMLStreamReader reference.
      Returns:
      a new reader for reading the XML data.
      Throws:
      DataStoreException - if the input type is not recognized or the data store is closed.
      XMLStreamException - if an error occurred while opening the XML file.
      IOException - if an error occurred while preparing the input stream.
      Exception - if another kind of error occurred while closing a previous stream.

    • createWriter

      final XMLStreamWriter createWriter(StaxStreamWriter target, OutputStream temporary) throws DataStoreException, XMLStreamException, IOException
      Creates a new XML stream writer for writing the XML document. If another XMLStreamWriter has already been created before this method call, whether this method will succeed in creating a new writer depends on the storage type (e.g. file or output stream).
      Parameters:
      target - the writer which will store the XMLStreamWriter reference.
      temporary - the temporary stream where to write, or null for the main storage.
      Returns:
      a new writer for writing the XML data.
      Throws:
      DataStoreException - if the output type is not recognized or the data store is closed.
      XMLStreamException - if an error occurred while opening the XML file.
      IOException - if an error occurred while preparing the output stream.

    • canClose

      final boolean canClose(AutoCloseable finished)
      Invoked when StaxStreamReader finished to read XML document from the given stream. This method returns true if the caller should invoke AutoCloseable.close(), or false if this StaxDataStore may reuse that stream.
      Parameters:
      finished - the stream that has been used for reading XML document.
      Returns:
      whether the caller should invoke finished.close().

    • close

      public void close() throws DataStoreException
      Closes the input or output stream and releases any resources used by this XML data store. This data store cannot be used anymore after this method has been invoked.

      Note for implementers

      Implementations should invoke listeners.close() on their first line before to clear their resources and to invoke super.close().
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in class DataStore
      Throws:
      DataStoreException - if an error occurred while closing the input or output stream.
      See Also: