Module org.apache.jena.iri3986
Package org.apache.jena.rfc3986

Class IRI3986

java.lang.Object
org.apache.jena.rfc3986.IRI3986
All Implemented Interfaces:
IRI
public class IRI3986 extends Object implements IRI
Implementation of RFC 3986 (URI), RFC 3987 (IRI). As is common, these are referred to as "3986" regardless, just as java.net.URI covers IRIs. This provides a fast checking operation which does not copy the various parts of the IRI and which creates a single object. The cost of extracting and allocating strings happen when the getter for the component is called. java.net.URI parses and allocates and follows RFC 2396 with modifications (several of which are in RFC 3986). See RFC3986 for operations involving IRI3986. This package implements the algorithms specified in RFC 3986 operations for:
  • Checking a string matches the IRI grammar.
  • Extracting components of an IRI
  • Normalizing an IRI
  • Resolving an IRI against a base IRI.
  • Rebuilding an IRI from components.
Additions:
  • Scheme specific rules for Linked Data usage of HTTP IRIs and URNs.
HTTP IRIs forbids the "user@" part which is strongly discouraged in IRIs and requires a host name if the "//" is present.
Some additional check for RFC 8141 for URNs are included such as being of the form urn:NID:NSS. Restrictions and limitations: Usage:
Check conformance with the RFC 3986 grammar: 
 RFC3986.check(string);
Check conformance with the RFC 3986 grammar and any applicable scheme specific rules: 
 RFC3986.check(string, true);
Validate and extract the components of IRI: 
     IRI3986 iri = RFC3986.create(string);
     iri.getPath();
     ...
Resolve: 
     IRI3986 base = ...
     IRI3986 iri = RFC3986.create(string);
     IRI3986 iri2 = iri.resolve(base);
Normalize: 
     IRI3986 base = ...
     IRI3986 iri = RFC3986.create(string);
     IRI3986 iri2 = iri.normalize();

  • Method Details

    • create

      public static IRI3986 create(String iristr)
      Create an IRI3986 object or throw an exception if there is a syntax error.

      This operation also checks conformance to the rules of the IRI schemes for some IRI schemes (http/https, urn:uuid, urn, file, did). These violations are accessed with hasViolations() and forEachViolation(java.util.function.Consumer<org.apache.jena.rfc3986.Violation>).

      See Violations for the mapping from issue to a warning or an error.

      See Issue for the scheme specific issues covered.

    • createSyntax

      public static IRI3986 createSyntax(String iristr)
      Create an IRI3986 object or throw an exception if there is a syntax error.

      This operation does not check conformance to the rules of IRI schemes.

      Prefer create(String) which records scheme-violations.

      See Violations for the mapping from issue to a warning or an error.

      See Issue for the scheme specific issues covered.

    • createAny

      public static IRI3986 createAny(String iristr)
      Create an IRI3986 object; report errors and warnings. This operation always returns an object; it does not throw an exception, nor return null.

      Errors and warning may be accessed with hasViolations() and forEachViolation(java.util.function.Consumer<org.apache.jena.rfc3986.Violation>).

      This operation checks the resulting IRI conforms to URI scheme specific rules only if the syntax as an IRI is valid.

    • str

      public final String str()
      The IRI in string form. This is guaranteed to parse to a ".equals" IRI.
      Specified by:
      str in interface IRI

    • hasViolations

      public boolean hasViolations()
      Does this IRI have any scheme specific issues?

      The normal way to create IRIs, create(java.lang.String) throws an IRIParseException. Parse errors in IRI string are IRIParseExceptions (unless createAny(java.lang.String) is used). In addition to parsing, IRIs are checked for some of the scheme-specific issues in the standards. See enum Issue.

      These are recorded in the IRI object; they do not automatically cause exceptions. See Violations for mapping issues to warnings and errors.

    • hasViolations

      public boolean hasViolations(Severity levelSeverity)
      Return true if this IRI has any violations greater than (and not equal to) the severity argument.

    • forEachViolation

      public void forEachViolation(Consumer<Violation> action)
      Call a consumer function for any violations recorded for this IRI.

      The normal way to create IRIs, create(java.lang.String), throws an IRIParseException if the IRI string does not match the grammar of RFC 3986/3987 and other RFCs. In addition to parsing, IRIs are checked for scheme-specific issues in the standards. See enum Issue for the issues covered.

      Issues are recorded as Violations. These are recorded in the IRI object; they do not automatically cause exceptions. See Violations for mapping issues to warnings and errors.

      See createAny(java.lang.String) for an operation to create a IRI that records parse exceptions are does not throw exception.

    • violations

      public List<Violation> violations()
      Return an immutable list of the violations for this IRI. See forEachViolation(Consumer).

    • toString

      public String toString()
      Human-readable appearance. Use str() to a string to use in code.
      Specified by:
      toString in interface IRI
      Overrides:
      toString in class Object

    • hasScheme

      public boolean hasScheme()
      Specified by:
      hasScheme in interface IRI

    • scheme

      public String scheme()
      Specified by:
      scheme in interface IRI

    • hasAuthority

      public boolean hasAuthority()
      Specified by:
      hasAuthority in interface IRI

    • authority

      public String authority()
      Specified by:
      authority in interface IRI

    • hasUserInfo

      public boolean hasUserInfo()
      Specified by:
      hasUserInfo in interface IRI

    • userInfo

      public String userInfo()
      Specified by:
      userInfo in interface IRI

    • hasHost

      public boolean hasHost()
      Specified by:
      hasHost in interface IRI

    • host

      public String host()
      Specified by:
      host in interface IRI

    • hasPort

      public boolean hasPort()
      Specified by:
      hasPort in interface IRI

    • port

      public String port()
      Specified by:
      port in interface IRI

    • hasPath

      public boolean hasPath()
      Specified by:
      hasPath in interface IRI

    • path

      public String path()
      Specified by:
      path in interface IRI

    • pathSegments

      public String[] pathSegments()
      Specified by:
      pathSegments in interface IRI

    • hasQuery

      public boolean hasQuery()
      Specified by:
      hasQuery in interface IRI

    • query

      public String query()
      Specified by:
      query in interface IRI

    • hasFragment

      public boolean hasFragment()
      Specified by:
      hasFragment in interface IRI

    • fragment

      public String fragment()
      Specified by:
      fragment in interface IRI

    • isAbsolute

      public boolean isAbsolute()
      RFC 3986, Section 4.3
      Specified by:
      isAbsolute in interface IRI

    • isRelative

      public boolean isRelative()
      RFC 3986, Section 4.2
      Specified by:
      isRelative in interface IRI

    • isRootless

      public boolean isRootless()
      RFC 3986, Section 3. IRI has a scheme, no authority (no //) and is path-rootless (does not start with /) e.g. URN's.
      Specified by:
      isRootless in interface IRI

    • isHierarchical

      public boolean isHierarchical()
      RFC 3986, Section 1.2.3 : Hierarchical Identifiers.
      Specified by:
      isHierarchical in interface IRI

    • isRFC3986

      public boolean isRFC3986()
      Test whether the IRI is RFC 3986 compatible;that is, has only ASCII characters.

    • normalize

      public IRI3986 normalize()
      RFC 3986, Section 6.2.2 : Syntax-Based Normalization..
      Specified by:
      normalize in interface IRI

    • relativize

      public IRI3986 relativize(IRI iri)
      Return (if possible), an IRI that is relative to the base argument.

      The base must have a scheme, and must not have a query string.

      Any fragment on the base IRI is lost.

      If no relative IRI can be found, return null.

    • resolve

      public IRI3986 resolve(IRI3986 other)
      Resolve an IRI, using this as the base. RFC 3986 section 5

    • build

      public static IRI3986 build(String scheme, String authority, String path, String query, String fragment)
      Build a IRI3986 from components.

    • rebuild

      public String rebuild()
      RFC 3986 : 5.3. Component Recomposition

    • hashCode

      public int hashCode()
      Description copied from interface: IRI
      Java hashCode.
      Specified by:
      hashCode in interface IRI
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object obj)
      Description copied from interface: IRI
      Java equals. IRI implementations must provide value-based equality and hashCode. That is, two IRI objects with the same components are ".equals" and have the same ".hashCode". (Like java.lang.String where "same chars" means "equals".)

      Specifically, if two IRI objects are parsed from the same string or return the same "str()" they are .equals and also have the same .hashCode.

      Specified by:
      equals in interface IRI
      Overrides:
      equals in class Object