public final class XMLSerializer extends Object
Plugin document. This functionality is especially
handy when implementing serialization
for a plugin document.
Any XMLSerializable class can be serialized and deserialized using classToXML and classFromXML (or one of their variants).
However, for final classes (e.g. SequenceAnnotation) it is more efficient to serialize/deserialize the class by
directly calling XMLSerializable.toXML() and using their deserialization constructor if available.| Modifier and Type | Method and Description |
|---|---|
static XMLSerializable |
classFromXML(org.jdom.Element element)
A convenience method.
|
static <T extends XMLSerializable> |
classFromXML(org.jdom.Element element,
Class<? extends T> cl)
recreates an object from an XML element created from a classToXML() call.
|
static <T extends XMLSerializable> |
classFromXML(org.jdom.Element element,
Class<? extends T> cl,
ProgressListener progressListener)
recreates an object from an XML element created from a classToXML() call.
|
static XMLSerializable |
classFromXML(org.jdom.Element element,
ProgressListener progressListener)
A convenience method.
|
static org.jdom.Element |
classToXML(Geneious.MajorVersion version,
String elementName,
XMLSerializable object,
ProgressListener progressListener)
converts the given object to an XML element of the given name so that is is readable in the specified version of Geneious.
|
static org.jdom.Element |
classToXML(String elementName,
XMLSerializable object)
converts the given object to an XML element of the given name.
|
static org.jdom.Element |
classToXML(String elementName,
XMLSerializable object,
ProgressListener progressListener)
converts the given object to an XML element of the given name.
|
static <T extends XMLSerializable> |
clone(T object)
Create a copy of an XMLSerializable object by serializing and then
de-serializing it.
|
static void |
ensureMemoryAvailable(long memoryInBytes)
Ensures that at least this much memory is available plus a little extra (100 MB in the current implementation) to be safe, and if not throws an XMLSerializationException
|
static void |
fieldsFromElement(org.jdom.Element element,
Map<String,Object> fieldValues)
Restore values stored in element by
fieldValuesToElement(java.lang.String, java.util.Map<java.lang.String, java.lang.Object>). |
static org.jdom.Element |
fieldValuesToElement(Geneious.MajorVersion version,
String name,
Map<String,Object> fieldValues,
boolean silentlyExcludeXmlSerializableFieldsThatDontSupportThisVersion)
Create one jdom element containing several fields.
|
static org.jdom.Element |
fieldValuesToElement(String name,
Map<String,Object> fieldValues)
Create one jdom element containing several fields.
|
static org.jdom.Element |
fieldValueToElement(Geneious.MajorVersion version,
String elementName,
Object value)
Create one jdom element containing one field value.
|
static org.jdom.Element |
fieldValueToElement(String elementName,
Object value)
Create one jdom element containing one field value.
|
static Class |
forName(String oldOrNewName)
Deprecated.
use
PluginUtilities.getClass(String) instead. |
static Object |
getFieldValue(org.jdom.Element element)
Restore value stored in element by
fieldValueToElement(String, Object). |
static Geneious.MajorVersion |
getVersionSupport(XMLSerializable.VersionSupportType versionSupportType,
Object... values)
Helper method for implementing
XMLSerializable.OldVersionCompatible.getVersionSupport(com.biomatters.geneious.publicapi.documents.XMLSerializable.VersionSupportType)
Out of all values, returns the highest version of Geneious that any individual value supports serialization to via
fieldValuesToElement(String, java.util.Map), fieldValueToElement(String, Object), classToXML(String, XMLSerializable) or classToXML(String, XMLSerializable, jebl.util.ProgressListener). |
static <T extends XMLSerializable> |
listFromXML(org.jdom.Element element,
Class<? extends T> cl)
Deserializes a list of XMLSerializable elements which were serialized using
listToXML(String, java.util.List). |
static org.jdom.Element |
listToXML(String name,
List<? extends XMLSerializable> list)
Serializes a list of XMLSerializable elements which can be deserialized using
listFromXML(org.jdom.Element, Class). |
static org.jdom.Element |
pluginDocumentToXml(Geneious.MajorVersion version,
PluginDocument pluginDocument,
ProgressListener progressListener)
Converts a PluginDocument to XML, handling the case where the PluginDocument may or may not implement
XMLSerializableWithProgress. |
static org.jdom.Element |
pluginDocumentToXml(PluginDocument pluginDocument,
ProgressListener progressListener)
Converts a PluginDocument to XML, handling the case where the PluginDocument may or may not implement
XMLSerializableWithProgress. |
static List<String> |
stringListFromXml(org.jdom.Element element)
Deserializes a list of String elements which were serialized using
stringListToXml(String, java.util.List). |
static org.jdom.Element |
stringListToXml(String name,
List<String> list)
Serializes a list of Strings which can be deserialized using
stringListFromXml(org.jdom.Element) in any version of Geneious from 5.6 onwards. |
static void |
translateUrns(org.jdom.Element element,
Map<URN,URN> urnChanges)
Translates all URNs (i.e.
|
public static org.jdom.Element classToXML(String elementName, XMLSerializable object)
SequenceAnnotation) it is more efficient to serialize/deserialize it directly rather than using XMLSerializer.elementName - the name of the elementobject - the object to convertRuntimeException - whose cause is a XMLSerializationException if
either the serializable class is a PluginDocument and it is unable to serialize to a temporary file using PluginDocument.FILE_DATA_ATTRIBUTE_NAME
or the serializable class is an AnnotatedPluginDocument which can't load its internal PluginDocument because for example there is insufficient memory or it is in a shared database that encounters an IOExceptionpublic static org.jdom.Element classToXML(String elementName, XMLSerializable object, ProgressListener progressListener)
SequenceAnnotation) it is more efficient to serialize/deserialize it directly rather than using XMLSerializer.elementName - the name of the elementobject - the object to convertprogressListener - handles reporting progress and optionally cancelling the serialization to XML. Must not be null, but may be ProgressListener.EMPTY.public static org.jdom.Element classToXML(Geneious.MajorVersion version, String elementName, XMLSerializable object, ProgressListener progressListener)
SequenceAnnotation) it is more efficient to serialize/deserialize it directly rather than using XMLSerializer.version - the version of Geneious to make it readable in. If this is not equal to Geneious.getMajorVersion()
then the object must implement XMLSerializable.OldVersionCompatible and have indicated it supports serializing to that version
via XMLSerializable.OldVersionCompatible.getVersionSupport
(XMLSerializable.VersionSupportType.OldestVersionSerializableTo)elementName - the name of the elementobject - the object to convertprogressListener - handles reporting progress and optionally cancelling the serialization to XML. Must not be null, but may be ProgressListener.EMPTY.public static org.jdom.Element pluginDocumentToXml(PluginDocument pluginDocument, ProgressListener progressListener) throws XMLSerializationException
XMLSerializableWithProgress. Also, unwraps
any XMLSerializationException enclosed in a RuntimeException that the PluginDocument's toXML method may throw.pluginDocument - the document to call toXML onprogressListener - handles reporting progress and optionally cancelling the serialization to XML. Must not be null, but may be ProgressListener.EMPTY.XMLSerializationException - if the PluginDocument's toXml method threw an XMLSerializationException enclosed in a RuntimeExceptionpublic static org.jdom.Element pluginDocumentToXml(Geneious.MajorVersion version, PluginDocument pluginDocument, ProgressListener progressListener) throws XMLSerializationException
XMLSerializableWithProgress. Also, unwraps
any XMLSerializationException enclosed in a RuntimeException that the PluginDocument's toXML method may throw.version - the version of Geneious that must be able to deserialize this XMLpluginDocument - the document to call toXML onprogressListener - handles reporting progress and optionally cancelling the serialization to XML. Must not be null, but may be ProgressListener.EMPTY.XMLSerializationException - if the PluginDocument's toXml method threw an XMLSerializationException enclosed in a RuntimeExceptionpublic static <T extends XMLSerializable> T classFromXML(org.jdom.Element element, Class<? extends T> cl) throws XMLSerializationException
element - the JDOM Element to convertcl - The expected class of the returned object. If it does not match, an XMLSerializationException will be thrown.
This parameter is really just a convenience parameter to avoid casting the return result
to a particular class and possibly receiving a class cast exception
For example, you might use:
PluginDocument result =(PluginDocument) classFromXML(element)
PluginDocument result =classFromXML(element,PluginDocument.class)
XMLSerializationException - if the Element can't be converted to an object for any reasonpublic static <T extends XMLSerializable> T classFromXML(org.jdom.Element element, Class<? extends T> cl, ProgressListener progressListener) throws XMLSerializationException
element - the JDOM Element to convertcl - The expected class of the returned object. If it does not match, an XMLSerializationException will be thrown.
This parameter is really just a convenience parameter to avoid casting the return result
to a particular class and possibly receiving a class cast exception
For example, you might use:
PluginDocument result =(PluginDocument) classFromXML(element)
PluginDocument result =classFromXML(element,PluginDocument.class)
progressListener - handles reporting progress and optionally cancelling the deserialization from XML. Must not be null, but may be ProgressListener.EMPTY.XMLSerializationException - if the Element can't be converted to an object for any reason or if the progress listener requests the deserialization be cancelled.public static XMLSerializable classFromXML(org.jdom.Element element) throws XMLSerializationException
classFromXML(element,XMLSerializable.class, ProgressListener.EMPTY) element - the JDOM Element to convertXMLSerializationException - if the Element can't be converted to an object for any reasonpublic static XMLSerializable classFromXML(org.jdom.Element element, ProgressListener progressListener) throws XMLSerializationException
classFromXML(element,XMLSerializable.class, progress) element - the JDOM Element to convertprogressListener - handles reporting progress and optionally cancelling the deserialization from XML. Must not be null, but may be ProgressListener.EMPTY.XMLSerializationException - if the Element can't be converted to an object for any reason or if the progress listener requests the deserialization be cancelled.public static org.jdom.Element listToXML(String name, List<? extends XMLSerializable> list)
listFromXML(org.jdom.Element, Class).name - the name to use for the returned elementlist - the list to serialisepublic static <T extends XMLSerializable> List<T> listFromXML(org.jdom.Element element, Class<? extends T> cl) throws XMLSerializationException
listToXML(String, java.util.List).element - then element to deserializecl - a class that all elements in the list extend.XMLSerializationException - if the list cannot be deserialized for any reason.public static org.jdom.Element stringListToXml(String name, List<String> list)
stringListFromXml(org.jdom.Element) in any version of Geneious from 5.6 onwards. It manages nulls.name - the name to use for the returned elementlist - the list to serialisepublic static List<String> stringListFromXml(org.jdom.Element element)
stringListToXml(String, java.util.List).element - the element to deserializepublic static org.jdom.Element fieldValuesToElement(String name, Map<String,Object> fieldValues)
Document data item.name - name of root elementfieldValues - values to storepublic static org.jdom.Element fieldValuesToElement(Geneious.MajorVersion version, String name, Map<String,Object> fieldValues, boolean silentlyExcludeXmlSerializableFieldsThatDontSupportThisVersion)
Document data item.version - the version of Geneious that must be able to deserialize this XMLname - name of root elementfieldValues - values to storesilentlyExcludeXmlSerializableFieldsThatDontSupportThisVersion - if an XMLSerializable field doesn't support serializing to this version, silently exclude it rather than crash.public static org.jdom.Element fieldValueToElement(String elementName, Object value)
XMLSerializable or
be one of the following concrete types: String, Integer, Double, Map<X,X>, List<X>, X[] where X
is any other type supported by this method.
Value an value associated with some
Document data item.elementName - jdom element namevalue - to store in elementIllegalArgumentException - if the Object cannot be XML serialized (see supported list of object types above)public static org.jdom.Element fieldValueToElement(Geneious.MajorVersion version, String elementName, Object value)
XMLSerializable or
be one of the following concrete types: String, Integer, Double, Map<X,X>, List<X>, X[] where X
is any other type supported by this method.
Value an value associated with some
Document data item.version - the version of Geneious that must be able to deserialize this XMLelementName - jdom element namevalue - to store in elementIllegalArgumentException - if the Object cannot be XML serialized (see supported list of object types above)public static Geneious.MajorVersion getVersionSupport(XMLSerializable.VersionSupportType versionSupportType, Object... values)
XMLSerializable.OldVersionCompatible.getVersionSupport(com.biomatters.geneious.publicapi.documents.XMLSerializable.VersionSupportType)
Out of all values, returns the highest version of Geneious that any individual value supports serialization to via
fieldValuesToElement(String, java.util.Map), fieldValueToElement(String, Object), classToXML(String, XMLSerializable) or classToXML(String, XMLSerializable, jebl.util.ProgressListener).
Null values are ignored, and if the number of values specified (excluding nulls) is zero, then Geneious.MajorVersion#Version6_0 will be returned.versionSupportType - the version support typevalues - 1 or more values to query what support they have for version serializationpublic static void fieldsFromElement(org.jdom.Element element,
Map<String,Object> fieldValues)
fieldValuesToElement(java.lang.String, java.util.Map<java.lang.String, java.lang.Object>).element - jdom element containing the valuesfieldValues - the map to store all values in, indexed by name (field code). Any existing values are cleared from the map prior to populating it from the XML.public static Object getFieldValue(org.jdom.Element element)
fieldValueToElement(String, Object).element - jdom element containing valuepublic static void translateUrns(org.jdom.Element element,
Map<URN,URN> urnChanges)
element - Element to search and replace recursively for URNsurnChanges - a map of old URN to new URNMalformedURNException - if malformed URN encountered@Deprecated public static Class forName(String oldOrNewName) throws ClassNotFoundException
PluginUtilities.getClass(String) instead.PluginUtilities.getClass(String) instead.oldOrNewName - the class name to find.ClassNotFoundException - if name does not match a classpublic static <T extends XMLSerializable> T clone(T object) throws XMLSerializationException
object - the XMLSerializable object to cloneXMLSerializationException - if the original object cannot be serialized to a JDOM Elementpublic static void ensureMemoryAvailable(long memoryInBytes)
throws XMLSerializationException
memoryInBytes - memory that the calling code requires in bytesXMLSerializationException - if insufficient free memory is available.