Package com.iizix.urn

Class URN

  • Direct Known Subclasses:
    BarcodeURN, SVG_URN, URL_URN, URNResource, UserProfileImageURN, UserProfileStringURN
    public abstract class URN
extends java.lang.Object
    This URN class handles a iizi Universal Resource Name generated from various {@link NID} with its required parameters, varying depending on the {@link NID}. The NID string is case sensitive. the "urn:" prefix is not case sensitive.

    iizi Uniform Resource Names (URN) are using the common standard.

    A URN normally looks like below, but you can read more at Uniform Resource Name.

    The iizi implementation for URN's to reference various parts in iizi is:

       "urn:NID:NSS:[?+r-component]][?=q-component][#fragment]".

    or, in the form of a syntax diagram, as:

    URN syntax diagram - namestring

    In the iizi case, the use of the some NID's also requires specifying an environment location ({@link NIDLocation}) where the data is stored, e.g. in a database, a server cluster, a server instance (for security), a user (chosen to be identified or not), a user identifier, an application, a specific user session or a specific user client session. In the case a location is used, the resource URL produced from the URN will be private to that particular location, e.g. a server, a user or its application/client session.

    Luckily, the abstraction of the final naming depends on so many things, but you don't have to worry about it. Just place it in the correct NID (Name space IDentifier) and leave the complexity to the framework.

    The iizi NID's are not registered with IANA, so they are all prefixed with "iz-" in this enum class.

    Author:
    Christopher Mindus

    • Field Summary

      Fields 
      Modifier and TypeFieldDescription
      protected java.lang.StringurnString
      The original URN string.

    • Constructor Summary

      Constructors 
      ModifierConstructorDescription
      protectedURN​(java.lang.String urnString)
      Constructor.

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and TypeMethodDescription
      URNResourceasURNResource()
      Gets this instance as type.
      abstract booleanequals​(java.lang.Object obj)
      Checks if another URN is equal to this one.
      static URNfrom​(java.lang.String urnString)
      Helper method that creates a URNResource from a String.
      IImageTargetgetImageTarget()
      Gets the image target interface for this URN instance, if supported.
      abstract java.lang.StringgetParamString()
      Gets the parameter string for the toString() method.
      abstract java.lang.StringgetURL()
      Gets the URL of this resource relative the current web server.
      java.lang.StringgetURNString()
      Gets the original URN unparsed string.
      abstract inthashCode()
      Gets the hash code of the instance.
      booleanisImageTargetSupported()
      Checks if this instance supports returning the image target interface {@link IImageTarget}.
      booleanisURNResource()
      Checks if this URN instance is a .
      java.lang.StringtoString()
      Formats this instance to a String that can be used for debugging.

      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait

    • Field Detail

      • urnString

        protected final java.lang.String urnString
        The original URN string.

    • Constructor Detail

      • URN

        protected URN​(java.lang.String urnString)
        Constructor.
        Parameters:
        urnString - The original URN string.
        Throws:
        java.lang.NullPointerException - If the urnString is null.

    • Method Detail

      • from

        public static URN from​(java.lang.String urnString)
                throws URNException
        Helper method that creates a URNResource from a String.

        This method calls:

         URNFactory.getInstance().from(urnString);

        Parameters:
        urnString - The String to resolve to an URN resource.
        Returns:
        The URN instance.
        Throws:
        URNException - For illegal URN's.
        NIDException - For exceptions with Naming ID's.
        UnknownNIDException - For unknown Naming ID's.
        java.lang.IllegalArgumentException - If the implementation encounters illegal characters.

      • getURL

        public abstract java.lang.String getURL()
                                 throws java.io.IOException
        Gets the URL of this resource relative the current web server.
        Returns:
        The URL relative the current server, if based on the current server, otherwise the full URL to the resource, or the data URL as data:<i>mediatype</i>[;base64],<i>data</i>.
        Throws:
        java.io.IOException - If there was a problem retrieving the file, an SQL error or other I/O error that caused the URL not to be possible to get (e.g. barcode failure).

      • isURNResource

        public boolean isURNResource()
        Checks if this URN instance is a .
        Returns:
        true if the instance is a , false by default.

      • asURNResource

        public URNResource asURNResource()
        Gets this instance as type.
        Returns:
        The instance, or null if this instance is not a URNResource (default).

      • isImageTargetSupported

        public boolean isImageTargetSupported()
        Checks if this instance supports returning the image target interface {@link IImageTarget}.
        Returns:
        true if the URN supports the image target interface, false (default) otherwise.

      • getImageTarget

        public IImageTarget getImageTarget()
        Gets the image target interface for this URN instance, if supported.
        Returns:
        The image target interface, or null (default) if not supported.

      • getURNString

        public final java.lang.String getURNString()
        Gets the original URN unparsed string.
        Returns:
        The string used to parse and build this URN instance.

      • hashCode

        public abstract int hashCode()
        Gets the hash code of the instance. The original URN string is not used for this hash code, rather the URN 'NID' and the parameters.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        A hash code value.

      • equals

        public abstract boolean equals​(java.lang.Object obj)
        Checks if another URN is equal to this one. The original URN string is not used for this comparison, rather the URN 'NID' and the parameters.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        obj - The other object to compare with.
        Returns:
        true if the URN's are equal, false otherwise.

      • getParamString

        public abstract java.lang.String getParamString()
        Gets the parameter string for the toString() method.
        Returns:
        The parameter string, always non-null.

      • toString

        public final java.lang.String toString()
        Formats this instance to a String that can be used for debugging.
        Overrides:
        toString in class java.lang.Object
        Returns:
        The String formatted as "className[param1=value1,param2=value2,originalURNString]".