Class StaxStreamWriter
- All Implemented Interfaces:
AutoCloseable
,Consumer<AbstractFeature>
- Direct Known Subclasses:
Writer
Feature
instances to write in the XML file.
This is a helper class for DataStore
implementations.
Writers for a given specification should extend this class and implement methods as in
the following example:
Example:
Writers can be used like below:Multi-threading
This class and subclasses are not tread-safe. Synchronization shall be done by theDataStore
that contains the StaxStreamIO
instances.- Since:
- 0.8
- Version:
- 1.3
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate Marshaller
The marshaller reserved to this writer usage, created only when first needed and kept until this writer is closed.protected final XMLStreamWriter
The XML stream writer.Fields inherited from class org.apache.sis.internal.storage.xml.stream.StaxStreamIO
owner, stream
-
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
StaxStreamWriter
(StaxDataStore owner, OutputStream temporary) Creates a new XML writer for the given data store. -
Method Summary
Modifier and TypeMethodDescriptionvoid
accept
(AbstractFeature feature) Delegates towrite(Feature)
, wrappingException
into uncheckedBackingStoreException
.void
close()
Closes the output stream and releases any resources used by this XML writer.protected final <T> void
Delegates to JAXB the marshalling of a part of XML document.abstract void
write
(AbstractFeature feature) Writes the given features to the XML document.void
Closes any start tags and writes corresponding end tags.protected final void
Writes the given list of values, ignoring null values.protected final void
writeSingle
(String localName, Date value) Writes a new element with the given date and no attribute.protected final void
writeSingleValue
(String localName, Object value) Writes a new element with the given value and no attribute.void
Writes the XML declaration with the data store encoding and default XML version (1.0).Methods inherited from class org.apache.sis.internal.storage.xml.stream.StaxStreamIO
errors, getMarshallerPool
-
Field Details
-
writer
The XML stream writer. -
marshaller
The marshaller reserved to this writer usage, created only when first needed and kept until this writer is closed.- See Also:
-
-
Constructor Details
-
StaxStreamWriter
protected StaxStreamWriter(StaxDataStore owner, OutputStream temporary) throws DataStoreException, XMLStreamException, IOException Creates a new XML writer for the given data store.- Parameters:
owner
- the data store for which this writer is created.temporary
- the temporary stream where to write, ornull
for the main storage.- 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.
-
-
Method Details
-
writeStartDocument
Writes the XML declaration with the data store encoding and default XML version (1.0). The encoding is specified as an option of theStorageConnector
given atStaxDataStore
construction time.Subclasses should overwrite this method if they need to write metadata in the XML document before the features. The overwritten method shall begin by a call to
super.writeStartDocument()
. Example:- Throws:
Exception
- if an error occurred while writing to the XML file. Possible subtypes includeXMLStreamException
, but alsoJAXBException
if JAXB is used for marshalling metadata objects,DataStoreException
,ClassCastException
, etc.
-
writeEndDocument
Closes any start tags and writes corresponding end tags. Subclasses should overwrite this method if they need to write some elements before the end tags.- Throws:
Exception
- if an error occurred while writing to the XML file.
-
write
Writes the given features to the XML document.- Parameters:
feature
- the feature to write.- Throws:
Exception
- if an error occurred while writing to the XML file. Possible subtypes includeXMLStreamException
, but alsoJAXBException
if JAXB is used for marshalling metadata objects,DataStoreException
,ClassCastException
, etc.
-
accept
Delegates towrite(Feature)
, wrappingException
into uncheckedBackingStoreException
.- Specified by:
accept
in interfaceConsumer<AbstractFeature>
- Parameters:
feature
- the feature to write.- Throws:
BackingStoreException
- if an error occurred while writing to the XML file.
-
writeSingleValue
Writes a new element with the given value and no attribute. If the given value is null, then this method does nothing.- Parameters:
localName
- local name of the tag to write.value
- text to write inside the element.- Throws:
XMLStreamException
- if the underlying STAX writer raised an error.
-
writeSingle
Writes a new element with the given date and no attribute. If the given date is null, then this method does nothing.- Parameters:
localName
- local name of the tag to write.value
- date to write inside the element.- Throws:
XMLStreamException
- if the underlying STAX writer raised an error.
-
writeList
Writes the given list of values, ignoring null values. If the given list is null, then this method does nothing.- Parameters:
localName
- local name of the tag to write.values
- values to write inside the element.- Throws:
XMLStreamException
- if the underlying STAX writer raised an error.
-
marshal
protected final <T> void marshal(String hideNS, String name, Class<T> type, T object) throws XMLStreamException, JAXBException Delegates to JAXB the marshalling of a part of XML document. The XML content will be written in an element of the given name with no namespace (see below).Hiding namespace
ThehideNS
argument, if non-null, gives a namespace to remove in the marshalling result. There is two reasons why we may want to hide a namespace. The most straightforward reason is to simplify the XML document when the namespace of elements to marshal is the default namespace. Since some JAXB implementation systematically inserts a prefix no matter if the namespace is the default one or not, we have to manually erase the namespace when it is the default one.But a more convolved reason is to reuse an element defined for another version of the file format. For example, some elements may be identical in 1.0 and 1.1 versions of a file format, so we may want to define only one JAXB annotated class for both versions. In that case the
hideNS
argument is not necessarily the default namespace. It is rather the namespace of the JAXB element that we want to erase (for example"foo/1.1"
), in order to pretend that it is the element of a different version specified by the default namespace (for example defined byxmlns = "foo/1.0"
).- Type Parameters:
T
- compile-time value of thetype
argument.- Parameters:
hideNS
- the namespace to erase from the marshalling output, ornull
if none.name
- the XML tag to write.type
- the Java class that define the XML schema of the object to marshal.object
- the object to marshal, ornull
if none.- Throws:
XMLStreamException
- if the XML stream is closed.JAXBException
- if an error occurred during marshalling.- See Also:
-
close
Closes the output stream and releases any resources used by this XML writer. This writer cannot be used anymore after this method has been invoked.- Specified by:
close
in interfaceAutoCloseable
- Overrides:
close
in classStaxStreamIO
- Throws:
XMLStreamException
- if an error occurred while releasing XML writer resources.IOException
- if an error occurred while closing the output stream.Exception
-