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

Class IRIFactory

java.lang.Object
org.apache.jena.iri.impl.AbsIRIFactoryImpl
org.apache.jena.iri.impl.IRIFactoryImpl
org.apache.jena.iri.IRIFactory
All Implemented Interfaces:
Force, IRIComponents, IRIFactoryI, ViolationCodes
public class IRIFactory extends IRIFactoryImpl implements IRIFactoryI
An IRIFactory is the entry point to this module. It allows:
  • The setting of conformance levels, particularly identifying which standard(s) to enforce
  • The creation of IRI objects, checking them against the selected standard(s)
  • The setting of optional behaviours, as specified in the various standard(s)

Any configuration of the factory to implement particular standards, or to treat particular violations as warnings or errors, must be completed before using the construct or create methods.

The easiest way to use this class is to use one of the preconfigured factories: semanticWebImplementation() iriImplementation(), or uriImplementation(). If none of these meets your application needs then you have to configure your own factory.

When initializing a factory, the initialization methods should be used in the following order:

  1. Any of:
  2. One or more of (note the effect is cumulative, all the used specifications will be enforced):
  3. Any of the methods that invoke optional behaviour
  4. Any scheme specific initialization
  5. Finally calls to

It is possible to make these calls in different orders, but the resultant behaviour is likely to be more confusing, and may change in future releases.

The other initialization methods (probably) do not have order dependencies.

  • Constructor Details

  • Method Details

    • iriImplementation

      public static IRIFactory iriImplementation()
      This factory implements RFC 3987 Internationalized Resource Identifiers (IRIs) .
      Returns:
      An implementation of RFC 3987

    • uriImplementation

      public static IRIFactory uriImplementation()
      This factory implements RFC 3986 Uniform Resource Identifier (URI): Generic Syntax .
      Returns:
      An implementation of RFC 3986

    • semanticWebImplementation

      @Deprecated public static IRIFactory semanticWebImplementation()
      Deprecated.
      Use iriImplementation()
      This factory is a conservative implementation appropriate for Semantic Web applications. It implements: RDF URI Reference (essential), IRI (needed for SPARQL) and XLink locator (ensures that only legal XML characters are included, allowing RDF/XML usage). In addition, ViolationCodes.NON_INITIAL_DOT_SEGMENT is treated as an error (since any IRI with this condition cannot be serialized in RDF/XML, which resolves all IRIs against the inscope base, and hence uses the remove_dot_segments algorithm). This should ensure that any IRI that is not in error, can be used interoperably in RDF/XML, SPARQL, N3 and N-Triple.

      This is the support for RDF 1.0 / RDF 2004 which includes "RDF URI References" (they are very broad and allow spaces, for example; the IRI RFC was not finalized when the RDF 1.1 specs were published). Nowadays, IRIs are strongly preferred by the semantic web standards.

      Returns:
      A factory suitable for Semantic Web applications.

    • jenaImplementation

      @Deprecated public static IRIFactory jenaImplementation()
      Deprecated.
      Use iriImplementation()
      For use by Jena intenal use only.

      This is the support for RDF 1.0 / RDF 2004 which includes "RDF URI References" (they are very broad and allow spaces, for example; the IRI RFC was not finalized when the RDF 1.1 specs were published). Nowadays, IRIs are strongly preferred by the semantic web standards.

      Returns:
      A factory suitable for Jena.

    • setSameSchemeRelativeReferences

      public void setSameSchemeRelativeReferences(String scheme)
      Allows scheme:relative-path as a relative reference against a base URI from the same scheme.

      Sets the behaviour of the relative reference resolution algorithm to be the backward compatible mode described in the URI specification: 

      -- A non-strict parser may ignore a scheme in the reference
-- if it is identical to the base URI's scheme.
--
   if ((not strict) and (R.scheme == Base.scheme)) then
         undefine(R.scheme);
   endif;
      Overrides:
      setSameSchemeRelativeReferences in class IRIFactoryImpl
      Parameters:
      scheme - The scheme to enable this behaviour for, or "*" for all schemes

    • allowUnwiseCharacters

      public void allowUnwiseCharacters()
      Allows the unwise characters as optionally permitted by RFC 3987 (IRI).
      Systems accepting IRIs MAY also deal with the printable characters in US-ASCII that are not allowed in URIs, namely "<", ">", '"', space, "{", "}", "|", "\", "^", and "`", in step 2 above. If these characters are found but are not converted, then the conversion SHOULD fail. Please note that the number sign ("#"), the percent sign ("%"), and the square bracket characters ("[", "]") are not part of the above list

      This method is intended to be used with factories that are using the IRI specification. The unwise characters are treated as minting warnings after this method is called. This method does not override any setting from useSpecificationXMLSchema(boolean) concerning ViolationCodes.DOUBLE_WHITESPACE.

    • setQueryCharacterRestrictions

      public void setQueryCharacterRestrictions(boolean restrict)
      The character constraints on the query component of an IRI are weaker than on other components. It is not clear how much weaker. Calling this method with restrict=false removes (all?) restrictions, calling this method with restrict=true adds restrictions, specifically disallowing private use codepoints.
      Parameters:
      restrict - True to make the query component checking stricter, false to make the query component checking more lenient

    • setEncoding

      public void setEncoding(String enc) throws UnsupportedEncodingException
      Sets the character encoding to use for decoding and encoding to percent escape sequences. UTF-8 is always used for the hostname.

      Using this method does not conform with the IRI specification, or XLink, XML system identifiers, RDF URI references, or XML Schema anyURI. This method is conformant with the URI specification.

      Overrides:
      setEncoding in class IRIFactoryImpl
      Throws:
      IllegalStateException - If this factory has already been used to create an IRI.
      UnsupportedEncodingException - If the encoding is not supported.

    • create

      public IRI create(String scheme, String userInfo, String host, int port, String path, String query, String fragment)
      Create an IRI from the given components. Performs whatever percent escaping or punycode encoding is necessary to make this IRI legal for this factory (if possible). Omitted components are passed as null.
      Parameters:
      scheme - Schema
      userInfo - User Info
      host - Will be encoded using punycode, if necessary.
      port - May be 0 for no port.
      path - May not be null
      query - Query string
      fragment - Fragment
      Returns:
      An IRI with the given components.
      See Also:

    • create

      public IRI create(String scheme, String authority, String path, String query, String fragment)
      Create an IRI from the given components. Performs whatever percent escaping is necessary to make this IRI legal for this factory (if possible). Omitted components are passed as null. Use create(String, String, String, int, String, String, String) when the authority is a DNS hostname, even if both the user information and the port are unspecified; this version uses percent escaping as opposed to punycode for the authority. DNS hostnames should be escaped in punycode (if necessary).
      Parameters:
      scheme - Scheme
      authority - Will be percent escaped if necessary
      path - May not be null
      query - Query
      fragment - Fragment
      Returns:
      An IRI with the given components.
      See Also:

    • construct

      public IRI construct(String scheme, String userInfo, String host, int port, String path, String query, String fragment) throws IRIException
      Create an IRI from the given components. Performs whatever percent escaping or punycode encoding is necessary to make this IRI legal for this factory (if possible). Omitted components are passed as null.
      Parameters:
      scheme - Scheme
      userInfo - user info
      host - Will be encoded using punycode, if necessary.
      port - May be 0 for no port.
      path - May not be null
      query - Query string
      fragment - Fragment
      Returns:
      An IRI with the given components. * @throws IRIException If the resulting IRI has unfixable errors, e.g. non-ascii chars in the scheme name
      Throws:
      IRIException
      See Also:

    • construct

      public IRI construct(String scheme, String authority, String path, String query, String fragment) throws IRIException
      Create an IRI from the given components. Performs whatever percent escaping is necessary to make this IRI legal for this factory (if possible). Omitted components are passed as null. Use construct(String, String, String, int, String, String, String) when the authority is a DNS hostname, even if both the user information and the port are unspecified; this version uses percent escaping as opposed to punycode for the authority. DNS hostnames should be escaped in punycode (if necessary).
      Parameters:
      scheme - Scheme
      authority - Will be percent escaped if necessary
      path - May not be null
      query - Query string
      fragment - Fragment
      Returns:
      An IRI with the given components.
      Throws:
      IRIException - If the resulting IRI has unfixable errors, e.g. non-ascii chars in the scheme name
      See Also:

    • isError

      public boolean isError(int code)
      Is condition #code being treated as an error.
      Parameters:
      code - A condition code from ViolationCodes.

    • isWarning

      public boolean isWarning(int code)
      Is condition #code being treated as a warning.
      Parameters:
      code - A condition code from ViolationCodes.

    • setIsError

      public void setIsError(int code, boolean set)
      Set condition #code to be treated as an error; or clear it as an error condition.

      Care must be taken when using this to clear the error behaviour on a code documented in ViolationCodes as having SHOULD force: see the documentation at shouldViolation(boolean, boolean), concerning the necessary steps. Using this method with code being one that is documented as having MUST force will result in non-conformant behaviour.

      Parameters:
      code - A condition code from ViolationCodes.
      set - True to set this as an error, false to clear.
      Throws:
      IllegalStateException - If this factory has already been used to create an IRI.

    • setIsWarning

      public void setIsWarning(int code, boolean set)
      Set condition #code to be treated as a warning; or clear it as a warning condition. Setting a code to be a warning, clears it from being an error. Care must be taken if the code is one that is documented in ViolationCodes has having SHOULD or MUST force, since ignoring any resulting warning may result in a nonconformant application.
      Parameters:
      code - A condition code from ViolationCodes.
      set - True to set this as a warning, false to clear.
      Throws:
      IllegalStateException - If this factory has already been used to create an IRI.

    • ignoring

      public boolean ignoring(int code)
      Is condition #code being ignored.
      Parameters:
      code - A condition code from ViolationCodes.

    • useSpecificationURI

      public void useSpecificationURI(boolean asErrors)
      The factory will check for violations of RFC 3986, URI. Non-ascii input will result in warnings or errors.
      Parameters:
      asErrors - If true, then violations are treated as errors; if false violations are treated as warnings.
      Throws:
      IllegalStateException - If this factory has already been used to create an IRI.

    • useSpecificationIRI

      public void useSpecificationIRI(boolean asErrors)
      The factory will check for violations of RFC 3987, IRI.
      Parameters:
      asErrors - If true, then violations are treated as errors; if false violations are treated as warnings.
      Throws:
      IllegalStateException - If this factory has already been used to create an IRI.

    • useSpecificationRDF

      public void useSpecificationRDF(boolean asErrors)
      The factory will check for violations of RDF URI Reference. Note: relative IRIs are prohibited.
      Parameters:
      asErrors - If true, then violations are treated as errors; if false violations are treated as warnings.
      Throws:
      IllegalStateException - If this factory has already been used to create an IRI.

    • useSpecificationXMLSchema

      public void useSpecificationXMLSchema(boolean asErrors)
      The factory will check for violations of XML Schema anyURI.
      Parameters:
      asErrors - If true, then violations are treated as errors; if false violations are treated as warnings.
      Throws:
      IllegalStateException - If this factory has already been used to create an IRI.

    • useSpecificationXMLSystemID

      public void useSpecificationXMLSystemID(boolean asErrors)
      The factory will check for violations of XML constraints on system ID. Note: fragments are prohibited.
      Parameters:
      asErrors - If true, then violations are treated as errors; if false violations are treated as warnings.
      Throws:
      IllegalStateException - If this factory has already been used to create an IRI.

    • useSpecificationXLink

      public void useSpecificationXLink(boolean asErrors)
      The factory will check for violations of XLink locator: href value.
      Parameters:
      asErrors - If true, then violations are treated as errors; if false violations are treated as warnings.
      Throws:
      IllegalStateException - If this factory has already been used to create an IRI.

    • shouldViolation

      public void shouldViolation(boolean isError, boolean isWarning)
      The factory will treat violations of "SHOULD" force statements from the specifications it is enforcing as errors, or warnings, or not at all. (Default is error)

      From RFC 2119 the full implications must be understood and carefully weighed before calling this method with isError=false. Thus, you MUST have read and understood the specifications that you are configuring the factory to use, before switching SHOULDs to warnings or to be ignored. An easier path, is to understand a specific error code, with SHOULD force, and then use setIsError(int, boolean), and setIsWarning(int, boolean) to modify the behaviour of that error code only. The prerequisite for modifiying a single error code to be ignored, or to be treated as a warning is to have understood the full implications of that condition, rather than of all the SHOULD force statements within all the specifications being used.

      Parameters:
      isError - If true, treat violations of SHOULDs as errors.
      isWarning - If true, treat violations of SHOULDs as warnings.
      Throws:
      IllegalArgumentException - if isError && isWarning.
      IllegalStateException - If this factory has already been used to create an IRI.

    • securityViolation

      public void securityViolation(boolean isError, boolean isWarning)
      The factory will treat violations of statements from the specifications flagged as security issues, including weak heuristical suggestions, it is enforcing as errors, or warnings, or not at all. (Default is error)
      Parameters:
      isError - If true, treat security violations as errors.
      isWarning - If true, treat security violations as warnings.
      Throws:
      IllegalArgumentException - if isError && isWarning.

    • dnsViolation

      public void dnsViolation(boolean isError, boolean isWarning)
      The factory will treat violations of statements from the specifications flagged as DNS issues, including Internationalized Domain Name issues, it is enforcing as errors, or warnings, or not at all. (Default is error)
      Parameters:
      isError - If true, treat DNS violations as errors.
      isWarning - If true, treat DNS violations as warnings.
      Throws:
      IllegalArgumentException - if isError && isWarning.

    • mintingViolation

      public void mintingViolation(boolean isError, boolean isWarning)
      The factory will treat violations of statements from the specifications concerning creating new IRIs it is enforcing as errors, or warnings, or not at all. (Default is warning). A sample phrase indicating the intent is this one from RFC 3986:
      An implementation should accept uppercase letters as equivalent to lowercase in scheme names (e.g., allow "HTTP" as well as "http") for the sake of robustness but should only produce lowercase scheme names for consistency.
      Parameters:
      isError - If true, treat violations of minting force statements as errors.
      isWarning - If true, treat violations of minting force statements as warnings.
      Throws:
      IllegalArgumentException - if isError && isWarning.
      IllegalStateException - If this factory has already been used to create an IRI.

    • useSchemeSpecificRules

      public void useSchemeSpecificRules(String scheme, boolean asErrors)
      Use the rules for a given scheme, or use all known scheme specific rules. Only a few sets of scheme specific rules are implemented. In the table below:
      Partial
      indicates that some but not all of the scheme specific restrictions on the IRI are implemented.
      component
      means that the scheme prohibits or requires one or more components of the IRI; and only these checks are performed.

      The currently implemented schemes are:

      SchemeLevel of implementation
      none
      Overrides:
      useSchemeSpecificRules in class IRIFactoryImpl
      Parameters:
      scheme - The scheme name or "*" to use all implemented scheme specific rules.
      asErrors - If true, then violations are treated as errors; if false violations are treated as warnings.
      Throws:
      IllegalStateException - If this factory has already been used to create an IRI.

    • setJenaImplementation

      public static void setJenaImplementation(IRIFactory jf)
      This globally sets the jenaImplementation(); use with care. This should be used before any calls to jenaImplementation(); it does not modify the factory returned by any previous calls, but subsequent calls to jenaImplementation() will return the new value.
      Parameters:
      jf - The new Jena Factory

    • setIriImplementation

      public static void setIriImplementation(IRIFactory iriF)
      This globally sets the iriImplementation(); use with care. This should be used before any calls to iriImplementation(); it does not modify the factory returned by any previous calls, but subsequent calls to iriImplementation() will return the new value.
      Parameters:
      iriF - The new IRI Factory

    • setUriImplementation

      public static void setUriImplementation(IRIFactory uriF)
      This globally sets the uriImplementation(); use with care. This should be used before any calls to uriImplementation(); it does not modify the factory returned by any previous calls, but subsequent calls to uriImplementation() will return the new value.
      Parameters:
      uriF - The new URI Factory

    • setSemanticWebImplementation

      public static void setSemanticWebImplementation(IRIFactory sw)
      This globally sets the semanticWebImplementation(); use with care. This should be used before any calls to semanticWebImplementation(); it does not modify the factory returned by any previous calls, but subsequent calls to semanticWebImplementation() will return the new value.
      Parameters:
      sw - The new IRI Factory