Class AliasDocument
- java.lang.Object
-
- com.biomatters.geneious.publicapi.documents.AliasDocument
-
- All Implemented Interfaces:
PluginDocument
,XMLSerializable
,XMLSerializable.OldVersionCompatible
public class AliasDocument extends java.lang.Object implements PluginDocument, XMLSerializable.OldVersionCompatible
An alias document created using 'Edit->Paste Alias' or programmatically usingcreateAlias(AnnotatedPluginDocument)
. This is a lightweight document that references the original document. When viewed in Geneious, the document table follows the alias to decide what to display to the user and the original document is always passed to DocumentViewers and DocumentOperations.- Since:
- API 4.1000 (Geneious 10.0.0)
- See Also:
DocumentType.ALIAS_DOCUMENT_TYPE
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from interface com.biomatters.geneious.publicapi.documents.PluginDocument
PluginDocument.ReferencedDocumentsAlwaysLoaded, PluginDocument.ReferencedDocumentsNotLoaded, PluginDocument.SizeRequiredToLoadIntoMemoryProvider
-
Nested classes/interfaces inherited from interface com.biomatters.geneious.publicapi.documents.XMLSerializable
XMLSerializable.OldVersionCompatible, XMLSerializable.VersionSupportType
-
-
Field Summary
-
Fields inherited from interface com.biomatters.geneious.publicapi.documents.PluginDocument
FILE_DATA_ATTRIBUTE_NAME, MAXIMUM_HTML_LENGTH, MODIFIED_DATE_FIELD
-
Fields inherited from interface com.biomatters.geneious.publicapi.documents.XMLSerializable
ROOT_ELEMENT_NAME
-
-
Constructor Summary
Constructors Constructor Description AliasDocument()
Construct a new AliasDocument.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static void
changeAliasesToReferenceNewDocument(AnnotatedPluginDocument originalDocument, AnnotatedPluginDocument newDocument, jebl.util.ProgressListener progressListener)
Changes all aliases in the same database that originalDocument is in that refer to originalDocument to instead refer to newDocument.static AnnotatedPluginDocument
createAlias(AnnotatedPluginDocument document)
static java.util.List<AnnotatedPluginDocument>
createAliases(java.util.List<AnnotatedPluginDocument> documents)
CallscreateAlias(AnnotatedPluginDocument)
on each documentstatic AnnotatedPluginDocument
followAlias(AnnotatedPluginDocument document)
If the provided document is an alias, follows this alias to the original documentstatic java.util.List<AnnotatedPluginDocument>
followAliases(java.util.List<AnnotatedPluginDocument> documents, boolean removeDuplicates)
CallsfollowAlias(AnnotatedPluginDocument)
on each document.void
fromXML(org.jdom.Element element)
Restore the object from the JDOM Element returned byXMLSerializable.toXML()
.static URN
getAliasedUrn(AnnotatedPluginDocument document)
Retrieves theURN
of a document aliased by this document without retrieving it from persistent storagejava.util.Date
getCreationDate()
Get the date this document was created.java.lang.String
getDescription()
A human readable single line of text describing this document, to appear in the description field in the document table.java.util.List<DocumentField>
getDisplayableFields()
A list of columns for display in the main document panel.java.lang.Object
getFieldValue(java.lang.String fieldCodeName)
Get the value of a particular field.java.lang.String
getName()
A short name (preferably one or two words) for the document.URN
getURN()
A Universal Resource Name.Geneious.MajorVersion
getVersionSupport(XMLSerializable.VersionSupportType versionType)
Gets either the latest version this class can serialize to viaXMLSerializable.OldVersionCompatible.toXML(Geneious.MajorVersion, ProgressListener)
or the most recent version in which the XML returned fromXMLSerializable.OldVersionCompatible.toXML(Geneious.MajorVersion, ProgressListener)
last changed.static boolean
isAlias(AnnotatedPluginDocument document)
java.lang.String
toHTML()
Provide a textual view of document.org.jdom.Element
toXML()
Convert object to a JDOM element.org.jdom.Element
toXML(Geneious.MajorVersion majorVersion, jebl.util.ProgressListener progressListener)
Serializes this class to XML format, potentially to a format readable by an earlier version of Geneious.
-
-
-
Constructor Detail
-
AliasDocument
public AliasDocument()
Construct a new AliasDocument. Should not be called directly (this is only here for document deserialization). UsecreateAlias(AnnotatedPluginDocument)
to create an Alias Document
-
-
Method Detail
-
getVersionSupport
public Geneious.MajorVersion getVersionSupport(XMLSerializable.VersionSupportType versionType)
Description copied from interface:XMLSerializable.OldVersionCompatible
Gets either the latest version this class can serialize to viaXMLSerializable.OldVersionCompatible.toXML(Geneious.MajorVersion, ProgressListener)
or the most recent version in which the XML returned fromXMLSerializable.OldVersionCompatible.toXML(Geneious.MajorVersion, ProgressListener)
last changed. Example implementation:switch (versionType) { case FormatLastExtended: //added a new tag to xml in 10.0 that can be safely ignored by older versions return Geneious.MajorVersion.Version10_0; case FormatLastChanged: //renamed a tag in 9.1 meaning that older versions can no longer read the xml from 9.1 return Geneious.MajorVersion.Version9_1; case OldestVersionSerializableTo: //this document class can export xml that is compatible with 9.0 return Geneious.MajorVersion.Version9_0; default: throw new IllegalArgumentException("Unrecognized VersionSupportType"); }
- Specified by:
getVersionSupport
in interfaceXMLSerializable.OldVersionCompatible
- Parameters:
versionType
- specifies which version property to return- Returns:
- the major version of Geneious corresponding to the versionType for this classes toXML method.
-
toXML
public org.jdom.Element toXML()
Description copied from interface:XMLSerializable
Convert object to a JDOM element. The representation should be complete so thatXMLSerializable.fromXML(org.jdom.Element)
can completely restore the object's representation. It is recommended that the returned element useXMLSerializable.ROOT_ELEMENT_NAME
as its name, in which case it must not define an attribute called "type". In this case, fromXML, will be called with an element whose name may differ from the element return from this function. This recommendation allows a more compact representation of the XML can be stored. This method generally should not be called directly. Instead, you should usually callXMLSerializer.classToXML(String, XMLSerializable)
which calls this method internally. PluginDocument implementations of this method may choose to throw anXMLSerializationException
, enclosed in aRuntimeException
.- Specified by:
toXML
in interfaceXMLSerializable
- Returns:
- object encoded as a JDOM element
-
toXML
public org.jdom.Element toXML(Geneious.MajorVersion majorVersion, jebl.util.ProgressListener progressListener)
Description copied from interface:XMLSerializable.OldVersionCompatible
Serializes this class to XML format, potentially to a format readable by an earlier version of Geneious. It is acceptable for the XML to include unnecessary tags that will be ignored by the earlier version. For example if the implementation has only extended the XML since the earlier version, then the XML returned may be identical to the XML returned for the current version. SeeXMLSerializable.toXML()
for a more detailed description of what it means to serialize to XML. All classes that implement this method must also implement XMLSerializable.toXML() and should delegate back to this method using Geneious.getMajorVersion() and ProgressListener.EMPTY as parameters.- Specified by:
toXML
in interfaceXMLSerializable.OldVersionCompatible
- Parameters:
majorVersion
- the major version of Geneious to serialize to XML for. For example "6.0" but not "6.0.0". This must be a version returned greater or equal to a version returned fromgetVersionSupport
(VersionSupportType.OldestVersionSerializableTo
) and must never be greater than the current version (Geneious.getMajorVersion())progressListener
- for reporting progress and cancelling- Returns:
- object encoded as a JDOM element
-
fromXML
public void fromXML(org.jdom.Element element) throws XMLSerializationException
Description copied from interface:XMLSerializable
Restore the object from the JDOM Element returned byXMLSerializable.toXML()
. This method generally should not be called directly. Instead, you should usually callXMLSerializer.classFromXML(org.jdom.Element)
orXMLSerializer.classFromXML(org.jdom.Element, Class)
which calls this method internally. It is optional to implement this method. Instead of implementing an empty constructor and implementing this method properly, the implementation may instead throw an UnsupportedOperationException and implement a constructor that takes a singleElement
as a parameter. This allows for cleaner code such as support for final fields in the XMLSerializable class. The element parameter should not be modified since it may be reused. If you need a modified version of it, take a copy withElement.clone()
.- Specified by:
fromXML
in interfaceXMLSerializable
- Parameters:
element
- representation from a previous call toXMLSerializable.toXML()
- Throws:
XMLSerializationException
- if the Element can't be converted into this type of object
-
getDisplayableFields
public java.util.List<DocumentField> getDisplayableFields()
Description copied from interface:PluginDocument
A list of columns for display in the main document panel. This function only defines the columns available to display, not the particular values of these columns, which are returned byPluginDocument.getFieldValue(String)
. Each column is specified by a Field. The fields should be obtained from a call to the appropriate Field.createXXXXField, where XXXX is the appropriate type. While it is not required, it is recommended that a PluginDocument handle returning a complete list of its displayable fields before the document has been properly constructed via a call toXMLSerializable.fromXML(org.jdom.Element)
The returned list need not and should not be modifiable.- Specified by:
getDisplayableFields
in interfacePluginDocument
- Returns:
- a list of document fields (or null to indicate no displayable fields)
-
getFieldValue
public java.lang.Object getFieldValue(java.lang.String fieldCodeName)
Description copied from interface:PluginDocument
Get the value of a particular field.- Specified by:
getFieldValue
in interfacePluginDocument
- Parameters:
fieldCodeName
- field code. This should be thecode
of one of the fields returned fromPluginDocument.getDisplayableFields()
.- Returns:
- value for a field or null if this document does not have a field with the given field code.
The class of the returned value must be the
DocumentField.getValueType()
(or a subclass) of the corresponding DocumentField returned fromPluginDocument.getDisplayableFields()
.
-
getName
public java.lang.String getName()
Description copied from interface:PluginDocument
A short name (preferably one or two words) for the document. If this PluginDocument is wrapped inside anAnnotatedPluginDocument
then this method will be overridden and delegate back toAnnotatedPluginDocument.getName()
. One way to look at it is that when you call PluginDocument.getName() you will get the current name of the document. If you are implementing PluginDocument.getName() then you are returning the default name for the document.- Specified by:
getName
in interfacePluginDocument
- Returns:
- document name. Cannot be null but may be an empty string.
-
getURN
public URN getURN()
Description copied from interface:PluginDocument
A Universal Resource Name. Documents from external sources should set this to a unique name inside that service. Documents generated locally (such as from operations) and documents that don't have a unique identifier should return null since Geneious handles URNs for these.- Specified by:
getURN
in interfacePluginDocument
- Returns:
- the urn, or null if this document doesn't have a unique identifier
-
getCreationDate
public java.util.Date getCreationDate()
Description copied from interface:PluginDocument
Get the date this document was created. This method may return null. Generally clients should useAnnotatedPluginDocument.getCreationDate()
instead as that will return either the date returned fromPluginDocument.getCreationDate()
or if that returned null,AnnotatedPluginDocument.getCreationDate()
will return the date the document was first instantiated.- Specified by:
getCreationDate
in interfacePluginDocument
- Returns:
- the date this document was created or null to use the date the document was first instantiated.
- See Also:
PluginDocument.MODIFIED_DATE_FIELD
-
getDescription
public java.lang.String getDescription()
Description copied from interface:PluginDocument
A human readable single line of text describing this document, to appear in the description field in the document table.- Specified by:
getDescription
in interfacePluginDocument
- Returns:
- a one line simple text description of the document, or null if no description is available.
-
toHTML
public java.lang.String toHTML()
Description copied from interface:PluginDocument
Provide a textual view of document. The contents should be at most 30K-60K characters. One reason is that this text is rendered using JTextPane, which is horrendously slow when handling large text. The more fundamental reason is that large amounts of text are generally not useful for a user. The whole idea of using a tool such as Geneious is to provide specialized viewers which make the large amount of bioinformatics data perceivable and comprehensible to a human user. Return an HTML body fragment (i.e. a fragment which sits inside a <body></body> tag). (Header,stylesheet and annotations are automatically added by GENEious code). Can optionally return an entire html tag set, as long as the first six characters are<html>
- Specified by:
toHTML
in interfacePluginDocument
- Returns:
- an HTML fragment of tag set, or null to have no text view.
-
followAliases
@MayReturnSlowly public static java.util.List<AnnotatedPluginDocument> followAliases(java.util.List<AnnotatedPluginDocument> documents, boolean removeDuplicates)
CallsfollowAlias(AnnotatedPluginDocument)
on each document.- Parameters:
documents
- the documents to follow aliases onremoveDuplicates
- if after following aliases, there are duplicate documents in the list removes all duplicates leaving a single copy of each document- Returns:
- the documents after following aliases. If removeDuplicates is false, then the returned list will have
documents in the same order as the given list, as if this method was implemented as
return documents.stream() .map(AliasDocument::followAlias) .collect(Collectors.toList());
- See Also:
isAlias(AnnotatedPluginDocument)
,followAlias(AnnotatedPluginDocument)
-
followAlias
@MayReturnSlowly public static AnnotatedPluginDocument followAlias(AnnotatedPluginDocument document)
If the provided document is an alias, follows this alias to the original document- Parameters:
document
- the document which may be an alias document- Returns:
- the given document if is not an alias, or the document referred to if this is an alias. If this alias can't be followed (for example this is an alias in a disconnected shared database), then the alias document will be returned.
- See Also:
isAlias(AnnotatedPluginDocument)
,followAliases(List, boolean)
,createAlias(AnnotatedPluginDocument)
-
getAliasedUrn
@MustReturnPromptly public static URN getAliasedUrn(AnnotatedPluginDocument document)
Retrieves theURN
of a document aliased by this document without retrieving it from persistent storage- Parameters:
document
- theAnnotatedPluginDocument
to check- Returns:
- The URN this document aliases iff it is an
AliasDocument
or null if it is not - See Also:
isAlias(AnnotatedPluginDocument)
,followAlias(AnnotatedPluginDocument)
-
createAliases
@MustReturnPromptly public static java.util.List<AnnotatedPluginDocument> createAliases(java.util.List<AnnotatedPluginDocument> documents)
CallscreateAlias(AnnotatedPluginDocument)
on each document- Parameters:
documents
- documents to create aliases to- Returns:
- a list of alias documents
- See Also:
createAlias(AnnotatedPluginDocument)
-
createAlias
@MustReturnPromptly public static AnnotatedPluginDocument createAlias(AnnotatedPluginDocument document)
- Parameters:
document
- the document to create an alias to- Returns:
- a new document that is an alias to the provided document. If the provided document is itself an alias, the returned alias refers to the same original document as the other alias did. i.e. the returned document will never refer to another alias.
- See Also:
isAlias(AnnotatedPluginDocument)
,followAlias(AnnotatedPluginDocument)
-
isAlias
@MustReturnPromptly public static boolean isAlias(AnnotatedPluginDocument document)
- Returns:
- true iff document
document.getDocument()
is anAliasDocument
- See Also:
followAlias(AnnotatedPluginDocument)
,createAlias(AnnotatedPluginDocument)
-
changeAliasesToReferenceNewDocument
@MayReturnSlowly public static void changeAliasesToReferenceNewDocument(AnnotatedPluginDocument originalDocument, AnnotatedPluginDocument newDocument, jebl.util.ProgressListener progressListener) throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
Changes all aliases in the same database that originalDocument is in that refer to originalDocument to instead refer to newDocument.
Note: The implementation relies on a database search. This will work even if the local database is in the process of indexing documents, but if the local database search index is corrupt or has lost of unindexed documents, this won't change aliases. It may be desirable to callWritableDatabaseService.waitForSearchIndexingToComplete(true)
first to ensure all aliases are updated. However, that could take a long time to return so in situations where updating aliases is probably unlikely to be necessary and isn't critical if it isn't done, it may be better not to call this.- Parameters:
originalDocument
- the document to which all aliases to be modified refer tonewDocument
- the new document the aliases should refer to- Throws:
com.biomatters.geneious.publicapi.plugin.DocumentOperationException
- if there is a problem updating the aliases- See Also:
isAlias(AnnotatedPluginDocument)
,followAlias(AnnotatedPluginDocument)
,createAlias(AnnotatedPluginDocument)
-
-