Package com.iizix.urn

Class URN

java.lang.Object
com.iizix.urn.URN
Direct Known Subclasses:
BarcodeURN, SVG_URN, URL_URN, URNResource, UserProfileImageURN, UserProfileStringURN
public abstract class URN extends 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 Details

    • urnString

      protected final String urnString
      The original URN string.

  • Constructor Details

    • URN

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

  • Method Details

    • from

      public static URN from(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.
      IllegalArgumentException - If the implementation encounters illegal characters.

    • getURL

      public abstract String getURL() throws 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:
      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 URNResource.
      Returns:
      true if the instance is a URNResource, false by default.

    • asURNResource

      public URNResource asURNResource()
      Gets this instance as URNResource type.
      Returns:
      The URNResource 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 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 Object
      Returns:
      A hash code value.

    • equals

      public abstract boolean equals(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 Object
      Parameters:
      obj - The other object to compare with.
      Returns:
      true if the URN's are equal, false otherwise.

    • getParamString

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

    • toString

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