Class StaxDataStore
- All Implemented Interfaces:
AutoCloseable
,ResourceOnFileSystem
,StoreResource
,Resource
,Localized
- Direct Known Subclasses:
Store
- Since:
- 0.8
- Version:
- 1.3
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate final class
Holds information that can be used for (un)marshallers configuration, and opportunistically implement various listeners used by JAXB (actually the SIS wrappers) or StAX.Nested classes/interfaces inherited from class org.apache.sis.internal.storage.URIDataStore
URIDataStore.Provider
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final ChannelFactory
Object to use for creating new input streams if we need to read the same data more than once.(package private) final StaxDataStore.Config
Configuration information for JAXB (un)marshaller (actually the SIS wrappers) or for the StAX factories.protected final Charset
The character encoding of the file content, ornull
if unspecified.private static final byte
Possible states for thestate
field.private final byte
The number of spaces to use in indentations, or -1 if the XML output should not be formatted.private XMLInputFactory
The StAX readers factory, created when first needed.protected final Locale
The locale to use for locale-sensitive data (not for logging or warning messages), ornull
if unspecified.private XMLOutputFactory
The StAX writers factory, created when first needed.private static final byte
Possible states for thestate
field.private static final byte
Possible states for thestate
field.private byte
Whether the stream is currently in use by aStaxStreamIO
.private Object
The storage object given by the user.private final InputType
private final OutputType
private AutoCloseable
The underlying stream to close when thisStaxDataStore
is closed, ornull
if none.private long
Position of the first byte to read in the stream, or a negative value if unknown.protected final TimeZone
The timezone to use when parsing or formatting dates and times without explicit timezone, ornull
if unspecified.private static final byte
Possible states for thestate
field.Fields inherited from class org.apache.sis.internal.storage.URIDataStore
location
-
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
StaxDataStore
(StaxDataStoreProvider provider, StorageConnector connector) Creates a new data store. -
Method Summary
Modifier and TypeMethodDescription(package private) final boolean
canClose
(AutoCloseable finished) Invoked whenStaxStreamReader
finished to read XML document from the given stream.void
close()
Closes the input or output stream and releases any resources used by this XML data store.(package private) final XMLStreamReader
createReader
(StaxStreamReader target) Creates a new XML stream reader for reading the document from its position atStaxDataStore
creation time.(package private) final XMLStreamWriter
createWriter
(StaxStreamWriter target, OutputStream temporary) Creates a new XML stream writer for writing the XML document.final String
Returns the short name (abbreviation) of the format being read or written.final StaxDataStoreProvider
Returns the factory that created thisDataStore
instance, ornull
if unspecified.(package private) final XMLInputFactory
Returns the factory for StAX readers.private void
mark()
Marks the current stream position.(package private) final XMLOutputFactory
Returns the factory for StAX writers.private boolean
reset()
Resets the stream position to the mark created at construction time, then marks again the stream for allowing future resets.Methods inherited from class org.apache.sis.internal.storage.URIDataStore
addTitleOrIdentifier, getComponentFiles, getIdentifier, getOpenParameters, getOriginator, getSpecifiedPath, location, parameters
Methods inherited from class org.apache.sis.storage.DataStore
addListener, findResource, getDisplayName, getLocale, getMetadata, getNativeMetadata, removeListener, setLocale, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.apache.sis.storage.Resource
addListener, getMetadata, removeListener
-
Field Details
-
locale
The locale to use for locale-sensitive data (not for logging or warning messages), ornull
if unspecified.- See Also:
-
timezone
The timezone to use when parsing or formatting dates and times without explicit timezone, ornull
if unspecified.- See Also:
-
encoding
The character encoding of the file content, ornull
if unspecified. This is often (but not always) ignored at reading time, but taken in account at writing time. -
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.
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
The storage object given by the user. May bePath
,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
The underlying stream to close when thisStaxDataStore
is closed, ornull
if none. This is often the same reference thanstorage
if the latter is closeable, but not always. For example ifstorage
is aPath
, thenstream
will be some stream or channel opened for that path.We keep this reference as long as possible in order to use
mark()
andreset()
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 byChannelFactory.inputStream(String, StoreListeners)
are not of the same kind than the streams created byStorageConnector
.- See Also:
-
streamPosition
private long streamPosition -
storageToReader
The function in charge of producing aXMLStreamReader
from thestorage
orstream
. This field isnull
if the XML file is write-only or ifstorage
is aPath
. -
storageToWriter
The function in charge of producing aXMLStreamWriter
for thestorage
orstream
. This field isnull
if the XML file is read-only or ifstorage
is aPath
. -
inputFactory
The StAX readers factory, created when first needed.- See Also:
-
outputFactory
The StAX writers factory, created when first needed.- See Also:
-
channelFactory
Object to use for creating new input streams if we need to read the same data more than once. This field isnull
if we cannot re-open new input streams. -
indentation
private final byte indentationThe 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 -
START
private static final byte STARTPossible states for thestate
field.- See Also:
-
READING
private static final byte READINGPossible states for thestate
field.- See Also:
-
WRITING
private static final byte WRITINGPossible states for thestate
field.- See Also:
-
FINISHED
private static final byte FINISHEDPossible states for thestate
field.- See Also:
-
-
Constructor Details
-
StaxDataStore
protected StaxDataStore(StaxDataStoreProvider provider, StorageConnector connector) throws DataStoreException Creates a new data store. Theprovider
is mandatory if the data store will use JAXB, otherwise it is optional.- Parameters:
provider
- the provider of this data store, ornull
if unspecified.connector
- information about the storage (URL, stream, etc).- Throws:
DataStoreException
- if the input or output type is not recognized.
-
-
Method Details
-
mark
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
Resets the stream position to the mark created at construction time, then marks again the stream for allowing future resets.- Returns:
true
of success, orfalse
if the stream cannot be reset.- Throws:
IOException
- if an error occurred while resetting the stream.
-
getProvider
Returns the factory that created thisDataStore
instance, ornull
if unspecified.- Overrides:
getProvider
in classDataStore
- Returns:
- the factory that created this
DataStore
instance, ornull
if unspecified. - See Also:
-
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
Returns the factory for StAX readers. The same instance is returned for allStaxDataStore
lifetime. Warnings emitted by readers created by this factory will be forwarded to theDataStore.listeners
.This method is indirectly invoked by
createReader(StaxStreamReader)
, through a call toInputType.create(StaxDataStore, Object)
. -
outputFactory
Returns the factory for StAX writers. The same instance is returned for allStaxDataStore
lifetime.This method is indirectly invoked by
#createWriter(StaxStreamWriter, Object)
, through a call toOutputType.create(StaxDataStore, Object)
. -
createReader
Creates a new XML stream reader for reading the document from its position atStaxDataStore
creation time. If anotherXMLStreamReader
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 theXMLStreamReader
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 anotherXMLStreamWriter
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 theXMLStreamWriter
reference.temporary
- the temporary stream where to write, ornull
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
Invoked whenStaxStreamReader
finished to read XML document from the given stream. This method returnstrue
if the caller should invokeAutoCloseable.close()
, orfalse
if thisStaxDataStore
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
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 invokelisteners.close()
on their first line before to clear their resources and to invokesuper.close()
.- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in classDataStore
- Throws:
DataStoreException
- if an error occurred while closing the input or output stream.- See Also:
-