Class 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 a PluginDocument that stores references to other documents, it is essential to serialize the URN of the referenced document using toXML(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.
    • Constructor Summary

      Constructors 
      Constructor Description
      URN​(URN urnToCopy)
      Constructs a copy of this URN.
      URN​(java.lang.String urnString)
      URN factory method.
      URN​(java.lang.String namespace, java.lang.String assigner, java.lang.String element)
      Construct a URN.
    • 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.
        Parameters:
        namespace - namespace
        assigner - assigner
        element - element
      • URN

        public URN​(URN urnToCopy)
        Constructs a copy of this URN. Normally the only reason to do this is so that an in memory AnnotatedPluginDocument associated with this URN can become eligible for garbage collection. As long as the URN returned from AnnotatedPluginDocument.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 using DocumentUtilities.getDocumentByURN(URN).
        Parameters:
        urnToCopy - the URN to copy.
      • URN

        public URN​(java.lang.String urnString)
            throws MalformedURNException
        URN factory method. Creates a URN object from the String representation. URNs must take the form:
        identifier:namespace:assigner:element

        Example:
        urn:sequence:ncbi:genbank/AF00001

        Parameters:
        urnString - the String 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 an assigner 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)
      • 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 from isLocal() 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 class java.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 class java.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 class java.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 inside PluginDocument#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, use toXMLAsWeakReference(String) instead.

        URNs can be assumed to never change their XML format for the purposes of XMLSerializable.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 to toXML(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 of XMLSerializable.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)
      • 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)