Class URN
- java.lang.Object
-
- com.biomatters.geneious.publicapi.documents.URN
-
public final class URN extends java.lang.Object
An unmodifiable uniform resource name (URN), intended to serve as persistent, location-independent, resource identifiers. Every Geneious document ({@link AnnotatedPluginDocument)}) has a unique URN which serves as a primary database key. Given a URN, a document can be obtained even if it is stored in a remote location, which might be either an external service such as NCBI or another Geneious installation. (however this last capability has not been implemented). URN's are also used to keep a permanent reference of document(s) inside another document. For example, an alignment generated from a set of Geneious sequence documents may store the URN's of the original,unaligned sequences. Note: When XMLSerializing aPluginDocument
that stores references to other documents, it is essential to serialize the URN of the referenced document usingtoXML(String)
.
-
-
Field Summary
Fields Modifier and Type Field Description java.lang.String
assigner
Name of organization assigning names for this URN.java.lang.String
element
The specified media element.java.lang.String
namespace
The name of the organization which defines the rules on name allocation for this URN.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description boolean
equals(java.lang.Object object)
Returns true if this URN and the object argument represent the same URN.static URN
fromXML(org.jdom.Element urnElement)
Convert back to URN from element generated bytoXML(String)
.static URN
generateUniqueLocalURN()
Generates a local unique URN with anassigner
of ".".static URN
generateUniqueLocalURN(java.lang.String assigner)
Generates a unique URNint
hashCode()
Returns the hash code of the string representation of this object.boolean
isCloud()
Deprecated.all cloud document URNs (as of Geneious 2022.2) return true fromisLocal()
and false from isCloud()boolean
isExcludedDuringImportUrn()
boolean
isLocal()
java.lang.String
toString()
Returns the full URN as a string.org.jdom.Element
toXML(java.lang.String elementName)
Convert a URN into a XML element.org.jdom.Element
toXMLAsWeakReference(java.lang.String elementName)
Convert a URN into a XML element.
-
-
-
Field Detail
-
namespace
public final java.lang.String namespace
The name of the organization which defines the rules on name allocation for this URN. Example: "vrml"
-
assigner
public final java.lang.String assigner
Name of organization assigning names for this URN. Example: "umel"
-
element
public final java.lang.String element
The specified media element. Example: "texture/wood/oak.gif"
-
-
Constructor Detail
-
URN
public URN(java.lang.String namespace, java.lang.String assigner, java.lang.String element)
Construct a URN.
-
URN
public URN(URN urnToCopy)
Constructs a copy of this URN. Normally the only reason to do this is so that an in memoryAnnotatedPluginDocument
associated with this URN can become eligible for garbage collection. As long as the URN returned fromAnnotatedPluginDocument.getURN()
is still referenced, the AnnotatedPluginDocument will never be garbage collected. If a copy of a URN is made, the referenced document can still be retrieved from either the original URN or the URN copy usingDocumentUtilities.getDocumentByURN(URN)
.- Parameters:
urnToCopy
- the URN to copy.
-
URN
public URN(java.lang.String urnString) throws MalformedURNException
URN factory method. Creates aURN
object from theString
representation. URNs must take the form:
identifier:namespace:assigner:element
Example:
urn:sequence:ncbi:genbank/AF00001
- Parameters:
urnString
- theString
to parse as a URN.- Throws:
MalformedURNException
- If the spec String specifies an incomplete or invalid URN.
-
-
Method Detail
-
generateUniqueLocalURN
public static URN generateUniqueLocalURN()
Generates a local unique URN with anassigner
of ".".- Returns:
- a unique URN
- Since:
- API 4.60 (Geneious 5.6.0)
-
generateUniqueLocalURN
public static URN generateUniqueLocalURN(java.lang.String assigner)
Generates a unique URN- Parameters:
assigner
- name of organization assigning names for this URN. This could be a user name in a shared database or just "." for a local URN. A local URN is a URN that will not be used outside of this Geneious local database.- Returns:
- a unique URN
- Since:
- API 4.60 (Geneious 5.6.0)
-
isLocal
public boolean isLocal()
- Returns:
- true if this URN is a local URN (i.e. one generated using
generateUniqueLocalURN()
orgenerateUniqueLocalURN(String)
). AllAnnotatedPluginDocuments
have a local URN, including those in a shared or cloud database. Examples of non-local URNs are those returned fromPluginDocument.getURN()
for non-Geneious format databases such as NCBI - Since:
- API 4.60 (Geneious 5.6.0)
-
isCloud
@Deprecated(since="API 4.202220 (Geneious 2022.2.0)") public boolean isCloud()
Deprecated.all cloud document URNs (as of Geneious 2022.2) return true fromisLocal()
and false from isCloud()- Returns:
- true if this URN is a Geneious Cloud document.
- Since:
- API 4.201900 (Geneious 2019.0.0)
-
toString
public final java.lang.String toString()
Returns the full URN as a string.- Overrides:
toString
in classjava.lang.Object
- Returns:
- the full URN as a string
-
equals
public boolean equals(java.lang.Object object)
Returns true if this URN and the object argument represent the same URN.- Overrides:
equals
in classjava.lang.Object
- Parameters:
object
- the other object- Returns:
- true if both objects represent the same URN
-
hashCode
public int hashCode()
Returns the hash code of the string representation of this object.- Overrides:
hashCode
in classjava.lang.Object
- Returns:
- the hash code of the string representation of this object
-
toXML
public org.jdom.Element toXML(java.lang.String elementName)
Convert a URN into a XML element. This method must be used by any document storing URN's of other documents inside its XML representation (i.e insidePluginDocument#toElement
). Failure to use this method for serializing URNs means that Geneious won't recognize the document references another document and the referenced document could potentially be deleted by the user meaning the referencing document will no longer be able to find its referenced document.
When a PluginDocument stores a reference to a document that is deleted, Geneious will automatically keep the document around in a hidden location until nothing else references it. Similarly when a document is exported, all referenced documents are also exported with it. If you don't want this behaviour, usetoXMLAsWeakReference(String)
instead. URNs can be assumed to never change their XML format for the purposes ofXMLSerializable.OldVersionCompatible
.- Parameters:
elementName
- name to use for element.- Returns:
- the XML element.
- See Also:
fromXML(org.jdom.Element)
-
toXMLAsWeakReference
public org.jdom.Element toXMLAsWeakReference(java.lang.String elementName)
Convert a URN into a XML element. This is identical totoXML(String)
except that core Geneious will treat the references slightly differently. Weakly referenced documents are not included when exporting the referencing document. Any weakly referenced documents are not reference counted in the database and kept around as long as something references them. URNs can be assumed to never change their XML format for the purposes ofXMLSerializable.OldVersionCompatible
.- Parameters:
elementName
- name to use for element.- Returns:
- the XML element.
- Since:
- API 4.60 (Geneious 5.6.0)
- See Also:
fromXML(org.jdom.Element)
-
fromXML
public static URN fromXML(org.jdom.Element urnElement) throws MalformedURNException
Convert back to URN from element generated bytoXML(String)
.- Parameters:
urnElement
- URN element- Returns:
- the URN
- Throws:
MalformedURNException
- when element has the wrong form or is null- See Also:
toXML(String)
-
isExcludedDuringImportUrn
public boolean isExcludedDuringImportUrn()
- Returns:
- true if this URN was the URN of an input document excluded when downloading the results of an operation run on Geneious Server to a machine where the input document doesn't exist OR if this is a URN of a document which was missing during a geneious format export or during folder copying. This is mostly used as an indicator not to crash or throw assertion errors when data is missing. Data shouldn't be missing in recent versions of Geneious (apart from the unusual Geneious Server case mentioned), but bugs in old versions could cause references to be missing.
- Since:
- API 4.1011 (Geneious 10.1.1)
-
-