org.decisiondeck.jmcda.persist.xmcda2.utils
Class XMCDAReadUtils

java.lang.Object
  org.decisiondeck.jmcda.persist.xmcda2.utils.XMCDAErrorsManagerForwarder
      org.decisiondeck.jmcda.persist.xmcda2.utils.XMCDAReadUtils

public class XMCDAReadUtils
extends XMCDAErrorsManagerForwarder

Helper class containing methods useful for parsing various XMCDA fragments.

Field Summary

static String

DEFAULT_XMCDA_VERSION

Constructor Summary

XMCDAReadUtils()
Creates a new object which will use the default error management strategy XMCDAErrorsManager.ErrorManagement.THROW.

XMCDAReadUtils(XMCDAErrorsManager errorsManager)
Creates a new object delegating error management to the given error manager in case of unexpected data read.

Method Summary

static InputSupplier<? extends Reader>	getAsVersion_Reader(InputSupplier<? extends Reader> source, String version) Blindly transforms an XMCDA document corresponding to any version to a new XMCDA document corresponding to a different version.
static InputSupplier<? extends InputStream>	getAsVersion(InputSupplier<? extends InputStream> source, String version) Blindly transforms an XMCDA document corresponding to any version to a new XMCDA document corresponding to a different version.
String	getLastVersionRead() Retrieves the version number of the last XMCDA document read by this object, as assessed by its namespace.
static String	getNamespace_Reader(InputSupplier<? extends Reader> source) Retrieves the namespace associated to the document root of the given xml source document.
static String	getNamespace(InputSupplier<? extends InputStream> source) Retrieves the namespace associated to the document root of the given xml source document.
static String	getTagName(Class<? extends XmlObject> targetType)
<T extends XmlTokenSource> T	getUnique(Collection<T> collection, String contextMessageIfEmpty) Retrieves the only element from the given collection of elements.
<T> T	getUniqueOrZero(Collection<T> collection) Retrieves the only element from the given collection of elements, or null if the collection is empty.
XMCDADoc.XMCDA	getXMCDA_Reader(InputSupplier<? extends Reader> source) Retrieves the XMCDA document from the given source.
XMCDADoc.XMCDA	getXMCDA(InputSupplier<? extends InputStream> source) Retrieves the XMCDA document from the given source.
XMCDADoc	getXMCDADoc(InputSupplier<? extends InputStream> source) Retrieves the XMCDA document from the given source.

Methods inherited from class org.decisiondeck.jmcda.persist.xmcda2.utils.XMCDAErrorsManagerForwarder

error, getErrors, getStrategy, setStrategy

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_XMCDA_VERSION

public static String DEFAULT_XMCDA_VERSION

Constructor Detail

XMCDAReadUtils

public XMCDAReadUtils(XMCDAErrorsManager errorsManager)

Creates a new object delegating error management to the given error manager in case of unexpected data read.

Parameters:

errorsManager - not null.

XMCDAReadUtils

public XMCDAReadUtils()

Creates a new object which will use the default error management strategy XMCDAErrorsManager.ErrorManagement.THROW.

Method Detail

getUnique

public <T extends XmlTokenSource> T getUnique(Collection<T> collection,
                                              String contextMessageIfEmpty)
                                   throws InvalidInputException

Retrieves the only element from the given collection of elements. This method expects the collection of elements to contain exactly one element.

In case of unexpected contents, this method returns null or throws an exception depending on the strategy this object follows.

Type Parameters:

T - the type of content of the collection.

Parameters:

collection - not null.

contextMessageIfEmpty - if not null, is used to give a more useful error message about the context when the given collection is empty. If parsing an XmlObject, one possibility is to use the qualified name of the parsed type, see e.g. XPerformanceTable.type and SchemaType.getName().

Returns:

null iff the collection contains more or less than one element and this object follows a permissive strategy.

Throws:

InvalidInputException - iff the collection contains more or less than one element and this object follows the XMCDAErrorsManager.ErrorManagement.THROW strategy.

getUniqueOrZero

public <T> T getUniqueOrZero(Collection<T> collection)
                  throws InvalidInputException

Retrieves the only element from the given collection of elements, or null if the collection is empty. This method expects the collection of elements to contain zero or one elements, thus maximum one element.

If the given collection contains more than one element, this method returns null or throws an exception depending on the strategy this object follows.

Type Parameters:

T - the type of content of the collection.

Parameters:

collection - not null.

Returns:

null if the collection contains zero elements, or if the given collection contains more than one element and this object follows a permissive strategy.

Throws:

InvalidInputException - iff the given collection contains more than one element and this object follows the XMCDAErrorsManager.ErrorManagement.THROW strategy.

getXMCDA_Reader

public XMCDADoc.XMCDA getXMCDA_Reader(InputSupplier<? extends Reader> source)
                               throws IOException,
                                      XmlException

Retrieves the XMCDA document from the given source. Ensures that it validates.

If the document contained in the given source appears, according to its namespace, to be an XMCDA document not matching the expected version DEFAULT_XMCDA_VERSION, this method attemps to proceed as if the source version matched the expected one.

The underlying reader is closed when this method returns.

Parameters:

source - not null, with a non null reader.

Returns:

not null.

Throws:

IOException - if an exception happens while opening or closing the given reader, or while parsing the source.

XmlException - if an exception related to the contents of the source happens while parsing the source, including if the source document does not validate.

See Also:

getLastVersionRead()

getAsVersion

public static InputSupplier<? extends InputStream> getAsVersion(InputSupplier<? extends InputStream> source,
                                                                String version)
                                                         throws IOException,
                                                                XmlException

Blindly transforms an XMCDA document corresponding to any version to a new XMCDA document corresponding to a different version. This method only changes the namespace associated with the document and performs no validation whatsoever, except that the source document must have a namespace which has the appropriate prefix for an XMCDA document. The resulting document is therefore not necessarily a valid XMCDA document.

This method may typically be useful in two situations: transforming an old version of an XMCDA document into the version supported by this library (see DEFAULT_XMCDA_VERSION) in order to be able to read data using the reader classes this library proposes; or transforming a version of an XMCDA document obtained by writer classes in this library into an older version possibly expected by some user.

Parameters:

source - not null, must contain an XMCDA document.

version - not null, e.g. "2.0.0" or .

Returns:

not null.

Throws:

IOException - if an IO error occurs.

XmlException - if a parse error occurs.

getNamespace

public static String getNamespace(InputSupplier<? extends InputStream> source)
                           throws IOException,
                                  XmlException

Retrieves the namespace associated to the document root of the given xml source document.

Parameters:

source - not null, must correspond to an xml document.

Returns:

the namespace read, possibly null if none has been found.

Throws:

IOException - if an IO error occurs.

XmlException - if a parse error occurs.

getLastVersionRead

public String getLastVersionRead()

Retrieves the version number of the last XMCDA document read by this object, as assessed by its namespace. This does not necessarily correspond to an effective version number as the document could contain an exotic namespace.

Returns:

null iff no document has been read or the version number could not be retrieved.

getXMCDADoc

public XMCDADoc getXMCDADoc(InputSupplier<? extends InputStream> source)
                     throws IOException,
                            XmlException

Retrieves the XMCDA document from the given source. Ensures that it validates.

If the document contained in the given source appears, according to its namespace, to be an XMCDA document not matching the expected version DEFAULT_XMCDA_VERSION, this method attemps to proceed as if the source version matched the expected one.

The underlying reader is closed when this method returns.

Parameters:

source - not null, with a non null reader.

Returns:

not null.

Throws:

IOException - if an exception happens while opening or closing the given reader, or while parsing the source.

XmlException - if an exception related to the contents of the source happens while parsing the source, including if the source document does not validate.

See Also:

getLastVersionRead()

getXMCDA

public XMCDADoc.XMCDA getXMCDA(InputSupplier<? extends InputStream> source)
                        throws IOException,
                               XmlException

Retrieves the XMCDA document from the given source. Ensures that it validates.

If the document contained in the given source appears, according to its namespace, to be an XMCDA document not matching the expected version DEFAULT_XMCDA_VERSION, this method attemps to proceed as if the source version matched the expected one.

The underlying reader is closed when this method returns.

Parameters:

source - not null, with a non null reader.

Returns:

not null.

Throws:

IOException - if an exception happens while opening or closing the given reader, or while parsing the source.

XmlException - if an exception related to the contents of the source happens while parsing the source, including if the source document does not validate.

See Also:

getLastVersionRead()

getTagName

public static String getTagName(Class<? extends XmlObject> targetType)

getNamespace_Reader

public static String getNamespace_Reader(InputSupplier<? extends Reader> source)
                                  throws IOException,
                                         XmlException

Retrieves the namespace associated to the document root of the given xml source document.

Parameters:

source - not null, must correspond to an xml document.

Returns:

the namespace read, possibly null if none has been found.

Throws:

IOException - if an IO error occurs.

XmlException - if a parse error occurs.

getAsVersion_Reader

public static InputSupplier<? extends Reader> getAsVersion_Reader(InputSupplier<? extends Reader> source,
                                                                  String version)
                                                           throws IOException,
                                                                  XmlException

Blindly transforms an XMCDA document corresponding to any version to a new XMCDA document corresponding to a different version. This method only changes the namespace associated with the document and performs no validation whatsoever, except that the source document must have a namespace which has the appropriate prefix for an XMCDA document. The resulting document is therefore not necessarily a valid XMCDA document.

This method may typically be useful in two situations: transforming an old version of an XMCDA document into the version supported by this library (see DEFAULT_XMCDA_VERSION) in order to be able to read data using the reader classes this library proposes; or transforming a version of an XMCDA document obtained by writer classes in this library into an older version possibly expected by some user.

Parameters:

source - not null, must contain an XMCDA document.

version - not null, e.g. "2.0.0" or .

Returns:

not null.

Throws:

IOException - if an IO error occurs.

XmlException - if a parse error occurs.