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 Summary

    Fields
    Modifier and Type
    Field
    Description
    protected final String
    The original URN string.
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    URN(String urnString)
    Constructor.
  • Method Summary

    Modifier and Type
    Method
    Description
    Gets this instance as URNResource type.
    abstract boolean
    Checks if another URN is equal to this one.
    static URN
    from(String urnString)
    Helper method that creates a URNResource from a String.
    protected String
    Gets the URN string as toString() prints it: the original URN string, unless a subclass holds a secret in it and prints a redacted form instead (CC-FIX-URN-LOCKDOWN, U515-35: a barcode URN carries its text, for the 2FA QR code the otpauth secret).
    Gets the image target interface for this URN instance, if supported.
    abstract String
    Gets the parameter string for the toString() method.
    abstract String
    Gets the URL of this resource relative the current web server.
    final String
    Gets the original URN unparsed string.
    abstract int
    Gets the hash code of the instance.
    boolean
    Checks if this instance supports returning the image target interface {@link IImageTarget}.
    boolean
    Checks if this URN instance is a URNResource.
    final String
    Formats this instance to a String that can be used for debugging.

    Methods inherited from class Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait
  • 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.
    • getDisplayURNString

      protected String getDisplayURNString()
      Gets the URN string as toString() prints it: the original URN string, unless a subclass holds a secret in it and prints a redacted form instead (CC-FIX-URN-LOCKDOWN, U515-35: a barcode URN carries its text, for the 2FA QR code the otpauth secret). getURNString() is never redacted.
      Returns:
      The URN string for display, 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]", where the URN string is getDisplayURNString().