Class StaxStreamWriter

java.lang.Object
org.apache.sis.internal.storage.xml.stream.StaxStreamIO
org.apache.sis.internal.storage.xml.stream.StaxStreamWriter
All Implemented Interfaces:
AutoCloseable, Consumer<AbstractFeature>
Direct Known Subclasses:
Writer

public abstract class StaxStreamWriter extends StaxStreamIO implements Consumer<AbstractFeature>
Base class of Apache SIS writers of XML files using STAX writer. This class is itself a consumer of 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 the DataStore that contains the StaxStreamIO instances.
Since:
0.8
Version:
1.3
  • Field Details

  • Constructor Details

  • Method Details

    • writeStartDocument

      public void writeStartDocument() throws Exception
      Writes the XML declaration with the data store encoding and default XML version (1.0). The encoding is specified as an option of the StorageConnector given at StaxDataStore 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 include XMLStreamException, but also JAXBException if JAXB is used for marshalling metadata objects, DataStoreException, ClassCastException, etc.
    • writeEndDocument

      public void writeEndDocument() throws Exception
      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

      public abstract void write(AbstractFeature feature) throws Exception
      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 include XMLStreamException, but also JAXBException if JAXB is used for marshalling metadata objects, DataStoreException, ClassCastException, etc.
    • accept

      public void accept(AbstractFeature feature) throws BackingStoreException
      Delegates to write(Feature), wrapping Exception into unchecked BackingStoreException.
      Specified by:
      accept in interface Consumer<AbstractFeature>
      Parameters:
      feature - the feature to write.
      Throws:
      BackingStoreException - if an error occurred while writing to the XML file.
    • writeSingleValue

      protected final void writeSingleValue(String localName, Object value) throws XMLStreamException
      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

      protected final void writeSingle(String localName, Date value) throws XMLStreamException
      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

      protected final void writeList(String localName, Iterable<?> values) throws XMLStreamException
      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

      The hideNS 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 by xmlns = "foo/1.0").

      Type Parameters:
      T - compile-time value of the type argument.
      Parameters:
      hideNS - the namespace to erase from the marshalling output, or null 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, or null if none.
      Throws:
      XMLStreamException - if the XML stream is closed.
      JAXBException - if an error occurred during marshalling.
      See Also:
    • close

      public void close() throws Exception
      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 interface AutoCloseable
      Overrides:
      close in class StaxStreamIO
      Throws:
      XMLStreamException - if an error occurred while releasing XML writer resources.
      IOException - if an error occurred while closing the output stream.
      Exception