Module org.apache.jena.iri
Package org.apache.jena.iri

Class IRI

java.lang.Object
org.apache.jena.iri.impl.AbsIRIFactoryImpl
org.apache.jena.iri.IRI
All Implemented Interfaces:
IRIFactoryI, IRIRelativize
Direct Known Subclasses:
AbsIRIImpl
public abstract class IRI extends AbsIRIFactoryImpl implements IRIFactoryI, IRIRelativize
An IRI. The IRI may or may not conform to a variety of standards, IRIFactory. Methods allow:
  • accessing the components of the IRI, (both in raw and decoded form).
  • converting an IRI to a URI.
  • accessing Violations of the standards being enforced.
  • creating new IRI objects by resolving against this IRI as a base.
  • creating relative IRIs that when resolved against this IRI, would give a given absolute IRI.

The standards, and other setttings, which are used in the methods are determined by the configuration of the IRIFactory used to create this IRI. To check for conformance with a different standard, the IRI must be passed to IRIFactoryI.create(IRI) of a different appropriately configured IRIFactory.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    ILLFORMED_PORT
    Return code from getPort(), indicating that a port component was found, but it is not a non-negative integer.
    static final int
    NO_PORT
    Return code from getPort(), indicating no port component found.

    Fields inherited from interface org.apache.jena.iri.IRIRelativize

    ABSOLUTE, CHILD, GRANDPARENT, NETWORK, PARENT, SAMEDOCUMENT

  • Constructor Summary

    Constructors
    Constructor
    Description
    IRI()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    abstract String
    getASCIIHost()
    The host part of the authority, encoded as an International Domain Name.
    abstract String
    getAuthority()
    The authority component, found between the first "//" and the next "/".
    abstract String
    getFragment()
    The fragment, found after a "#" at the end of the main URI (note a fragment may itself contain a "#").
    abstract String
    getHost()
    The host part of the authority.
    abstract String
    getPath()
    The path component of the IRI; always present, possibly the empty string.
    abstract int
    getPort()
    The port number from the authority component.
    abstract String
    getQuery()
    The query component of the IRI.
    abstract String
    getRawAuthority()
    The authority component, found between the first "//" and the next "/".
    abstract String
    getRawFragment()
    The fragment, found after a "#" at the end of the main URI (note a fragment may itself contain a "#").
    abstract String
    getRawHost()
    The host part of the authority.
    abstract String
    getRawPath()
    The path component of the IRI; always present, possibly the empty string.
    abstract String
    getRawQuery()
    The query component of the IRI.
    abstract String
    getRawUserinfo()
    The user information part of the authority component of the IRI.
    abstract String
    getScheme()
    The scheme component of the IRI.
    abstract String
    getUserinfo()
    The user information part of the authority component of the IRI.
    abstract boolean
    hasViolation(boolean includeWarnings)
    Are there any violations of the factory's specification settings.
    abstract boolean
    isAbsolute()
    Does this IRI specify a scheme.
    abstract boolean
    isRelative()
    Is this IRI a relative reference without a scheme specified.
    abstract boolean
    isRootless()
    Is this an 'opaque' IRI.
    abstract int
    ladderEquals(IRI iri)
    To be defined: use the comparison ladder.
    abstract boolean
    ladderEquals(IRI iri, int other)
    To be defined: use the comparison ladder.
    static void
    main(String[] args)
    Check one or more IRIs against a specification.
    abstract IRI
    normalize(boolean useDns)
    To be defined - return result does not violate any minting conditions.
    abstract IRI
    relativize(String abs)
    Returns an IRI that when resolved against this IRI would return abs.
    abstract IRI
    relativize(String abs, int flags)
    Returns an IRI that when resolved against this IRI would return abs.
    abstract IRI
    relativize(IRI abs)
    Returns an IRI that when resolved against this IRI would return abs.
    abstract IRI
    relativize(IRI abs, int flags)
    Returns an IRI that when resolved against this IRI would return abs.
    final IRI
    resolve(String relative)
    Resolves an IRI against this one.
    final IRI
    resolve(IRI relative)
    Resolves an IRI against this one.
    abstract String
    toASCIIString()
    Converts the IRI into ASCII.
    abstract String
    toDisplayString()
    The IRI string with any recommended bi-directional control characters (if necessary) to ensure correct display.
    abstract String
    toString()
    The logical IRI string as originally specified.
    abstract URI
    toURI()
    Converts the IRI to an ASCII string, and then to a java.net.URI.
    abstract URL
    toURL()
    Converts the IRI to an ASCII string, and then to a URL.
    abstract Iterator<Violation>
    violations(boolean includeWarnings)
    The error and warning conditions associated with this IRI violating the standards associated with its factory.

    Methods inherited from class org.apache.jena.iri.impl.AbsIRIFactoryImpl

    construct, construct, construct, create, create, create

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

    Methods inherited from interface org.apache.jena.iri.IRIFactoryI

    construct, construct, construct, create, create, create

  • Field Details

    • NO_PORT

      public static final int NO_PORT
      Return code from getPort(), indicating no port component found.
      See Also:

    • ILLFORMED_PORT

      public static final int ILLFORMED_PORT
      Return code from getPort(), indicating that a port component was found, but it is not a non-negative integer.
      See Also:

  • Constructor Details

    • IRI

      public IRI()

  • Method Details

    • violations

      public abstract Iterator<Violation> violations(boolean includeWarnings)
      The error and warning conditions associated with this IRI violating the standards associated with its factory.
      Parameters:
      includeWarnings - If true then warnings are returned as well as errors.
      Returns:
      The Violations found which violate the factory's standards.

    • getRawAuthority

      public abstract String getRawAuthority()
      The authority component, found between the first "//" and the next "/". No decoding is done; this method is cheap.
      Returns:
      The authority component, or null if none.

    • getAuthority

      public abstract String getAuthority()
      The authority component, found between the first "//" and the next "/". Any legal percent escape sequences are decoded. If the host name is an Internationalized Domain Name, then that is decoded too. This method may be more expensive than getRawAuthority().
      Returns:
      The authority component, or null if none.

    • getRawFragment

      public abstract String getRawFragment()
      The fragment, found after a "#" at the end of the main URI (note a fragment may itself contain a "#"). No decoding is done; this method is cheap.
      Returns:
      The fragment, or null if none,

    • getFragment

      public abstract String getFragment()
      The fragment, found after a "#" at the end of the main URI (note a fragment may itself contain a "#"). Any legal percent escape sequences are decoded. This method may be more expensive than getRawFragment().
      Returns:
      The fragment, or null if none,

    • getRawHost

      public abstract String getRawHost()
      The host part of the authority. Found between an optional "@" and an optional ":" in the authority. No decoding is done; this method is cheap.
      Returns:
      The host, or null if none.

    • getHost

      public abstract String getHost()
      The host part of the authority. Found between an optional "@" and an optional ":" in the authority. Any legal percent escape sequences are decoded. Any legal punycode is decoded. This method may be more expensive than getRawHost().
      Returns:
      The host, or null if none.

    • getASCIIHost

      public abstract String getASCIIHost() throws MalformedURLException
      The host part of the authority, encoded as an International Domain Name. Any legal percent escape sequences are decoded. Any non-ASCII characters are encoded as punycode, if possible. This may be impossible (even in the ASCII case), in which case an exception is thrown. This method may be more expensive than getRawHost().
      Returns:
      The host as an IDN, or null if none.
      Throws:
      MalformedURLException - An Internationalized Domain Name algorithm failed, there is no equivalent ascii string.

    • getRawPath

      public abstract String getRawPath()
      The path component of the IRI; always present, possibly the empty string. This includes any leading "/". Found after the authority, and before any "?" or "#". No decoding is done; this method is cheap.
      Returns:
      The path.

    • getPath

      public abstract String getPath()
      The path component of the IRI; always present, possibly the empty string. This includes any leading "/". Found after the authority, and before any "?" or "#". Any legal percent escape sequences are decoded. This method may be more expensive than getRawPath().
      Returns:
      The path.

    • getPort

      public abstract int getPort()
      The port number from the authority component. Found after the last ":" in the authority.
      Returns:
      The port number, or NO_PORT or ILLFORMED_PORT.

    • getRawQuery

      public abstract String getRawQuery()
      The query component of the IRI. Found after the "?" and before an optional "#". No decoding is done; this method is cheap.
      Returns:
      The query component, or null if none.

    • getQuery

      public abstract String getQuery()
      The query component of the IRI. Found after the "?" and before an optional "#". Any legal percent escape sequences are decoded. This method may be more expensive than getRawQuery().
      Returns:
      The query component, or null if none.

    • getScheme

      public abstract String getScheme()
      The scheme component of the IRI. Found before the first ":".
      Returns:
      The scheme component, or null if none.

    • getRawUserinfo

      public abstract String getRawUserinfo()
      The user information part of the authority component of the IRI. Found before the first "@" in the authority. May include a ":" separating the user name from a password, ViolationCodes.HAS_PASSWORD. No decoding is done; this method is cheap.
      Returns:
      The user information, or null if none.

    • getUserinfo

      public abstract String getUserinfo()
      The user information part of the authority component of the IRI. Found before the first "@" in the authority. May include a ":" separating the user name from a password, ViolationCodes.HAS_PASSWORD. Any legal percent escape sequences are decoded. This method may be more expensive than getRawUserinfo().
      Returns:
      The user information, or null if none.

    • hasViolation

      public abstract boolean hasViolation(boolean includeWarnings)
      Are there any violations of the factory's specification settings. Quick check, equivalent to violations(includeWarnings).hasNext(), but faster.
      Parameters:
      includeWarnings - If true then warnings are reported as well as errors.
      Returns:
      true if the factory's specifications have been violated.

    • isAbsolute

      public abstract boolean isAbsolute()
      Does this IRI specify a scheme.
      Returns:
      True if this IRI has a scheme specified.

    • isRootless

      public abstract boolean isRootless()
      Is this an 'opaque' IRI. Is this IRI an absolute IRI with a path matching the path-rootless production: i.e. it has a scheme but no authority, and a path not starting in "/". Note: in the earlier RFC 2396 this concept was called being opaque.
      Returns:
      True if the non-empty path of this non-relative IRI is rootless

    • isRelative

      public abstract boolean isRelative()
      Is this IRI a relative reference without a scheme specified.
      Returns:
      True if the IRI is a relative reference

    • relativize

      public abstract IRI relativize(IRI abs, int flags)
      Returns an IRI that when resolved against this IRI would return abs. If possible, a relative IRI is formed, using any of the methods specified in flags, which is a bitwise or of values from IRIRelativize.

      If abs contains a dot segment (either "/./" or "/../") then the contract cannot be satisfied and an incorrect answer is returned. This incorrect return value has an ViolationCodes.NON_INITIAL_DOT_SEGMENT violation associated with it.

      Parameters:
      abs - An absolute IRI to make relative.
      flags - Which type of relative IRIs to permit.
      Returns:
      A relative or absolute IRI equivalent to abs.

    • relativize

      public abstract IRI relativize(IRI abs)
      Returns an IRI that when resolved against this IRI would return abs. If possible, a relative IRI is formed, using default methods.

      If abs contains a dot segment (either "/./" or "/../") then the contract cannot be satisfied and an incorrect answer is returned. This incorrect return value has an ViolationCodes.NON_INITIAL_DOT_SEGMENT violation associated with it.

      Parameters:
      abs - An absolute IRI to make relative.
      Returns:
      A relative or absolute IRI equivalent to abs.

    • relativize

      public abstract IRI relativize(String abs)
      Returns an IRI that when resolved against this IRI would return abs. If possible, a relative IRI is formed, using default methods.

      If abs contains a dot segment (either "/./" or "/../") then the contract cannot be satisfied and an incorrect answer is returned. This incorrect return value has an ViolationCodes.NON_INITIAL_DOT_SEGMENT violation associated with it.

      Parameters:
      abs - An absolute IRI to make relative.
      Returns:
      A relative or absolute IRI equivalent to abs.

    • relativize

      public abstract IRI relativize(String abs, int flags)
      Returns an IRI that when resolved against this IRI would return abs. If possible, a relative IRI is formed, using any of the methods specified in flags, which is a bitwise or of values from IRIRelativize.

      If abs contains a dot segment (either "/./" or "/../") then the contract cannot be satisfied and an incorrect answer is returned. This incorrect return value has an ViolationCodes.NON_INITIAL_DOT_SEGMENT violation associated with it.

      Parameters:
      abs - An absolute IRI to make relative.
      flags - Which type of relative IRIs to permit.
      Returns:
      A relative or absolute IRI equivalent to abs.

    • toASCIIString

      public abstract String toASCIIString() throws MalformedURLException
      Converts the IRI into ASCII. The hostname is converted into punycode; other components are converted using percent encoding. Even if the IRI is already ASCII, the hostname may be modified, if, for example, it (inappropriately) uses percent encoding. This may be impossible (even in the ASCII case), in which case an exception is thrown.
      Returns:
      An ASCII string corresponding to this IRI.
      Throws:
      MalformedURLException - An Internationalized Domain Name algorithm failed, there is no equivalent ascii string.

    • toString

      public abstract String toString()
      The logical IRI string as originally specified. Use toDisplayString() for display purposes such as error messages.
      Overrides:
      toString in class Object
      Returns:
      The IRI string

    • toDisplayString

      public abstract String toDisplayString()
      The IRI string with any recommended bi-directional control characters (if necessary) to ensure correct display.
      Returns:
      The IRI string formatted with unicode bidi control characters

    • toURL

      public abstract URL toURL() throws MalformedURLException
      Converts the IRI to an ASCII string, and then to a URL.
      Returns:
      a URL corresponding to this IRI.
      Throws:
      MalformedURLException - If IDNA conversion failed, or from java.net.URL

    • toURI

      public abstract URI toURI() throws URISyntaxException
      Converts the IRI to an ASCII string, and then to a java.net.URI.
      Returns:
      a URL corresponding to this IRI.
      Throws:
      URISyntaxException - If IDNA conversion failed.

    • resolve

      public final IRI resolve(IRI relative)
      Resolves an IRI against this one. This method is an alias for IRIFactoryImpl.create(IRI).
      Parameters:
      relative - IRI to resolve
      Returns:
      The resolution of relative against this.
      See Also:

    • resolve

      public final IRI resolve(String relative)
      Resolves an IRI against this one. This method is an alias for IRIFactoryImpl.create(String).
      Parameters:
      relative - IRI to resolve
      Returns:
      The resolution of relative against this.
      See Also:

    • normalize

      public abstract IRI normalize(boolean useDns)
      To be defined - return result does not violate any minting conditions.
      Parameters:
      useDns - If true, do DNS look ups to normalize hostname.
      Returns:
      An equivalent, normalized IRI

    • ladderEquals

      public abstract boolean ladderEquals(IRI iri, int other)
      To be defined: use the comparison ladder.
      Parameters:
      iri - IRI
      other - Specifies where on the ladder to make the comparison.
      Returns:
      True if this IRI is equal to the given one, when normalized with rules specified by other.

    • ladderEquals

      public abstract int ladderEquals(IRI iri)
      To be defined: use the comparison ladder.
      Parameters:
      iri - IRI
      Returns:
      A value for other to make ladderEquals(IRI, int) true, or -1 if none.

    • main

      public static void main(String[] args)
      Check one or more IRIs against a specification. Usage: 
       java <classpath> [ -help ] [ -iri | -uri | -xml | -schema | -xlink ] [ -f file ] [ iri ... ]
      If no file or iris are specified on the command line, then standard input is used. In fact more than one spec can be used, in which case violations of any of them are reported.
      Parameters:
      args - See above.