com.hp.hpl.jena.iri
Class IRIFactory

java.lang.Object
  extended by com.hp.hpl.jena.iri.impl.AbsIRIFactoryImpl
      extended by com.hp.hpl.jena.iri.impl.IRIFactoryImpl
          extended by com.hp.hpl.jena.iri.IRIFactory
All Implemented Interfaces:
com.hp.hpl.jena.iri.impl.Force, IRIComponents, IRIFactoryI, ViolationCodes

public class IRIFactory
extends com.hp.hpl.jena.iri.impl.IRIFactoryImpl
implements IRIFactoryI

An IRIFactory is the entry point to this module. It allows:

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.

Author:
Jeremy J. Carroll

Nested Class Summary
 
Nested classes/interfaces inherited from interface com.hp.hpl.jena.iri.ViolationCodes
ViolationCodes.Initialize
 
Field Summary
 
Fields inherited from class com.hp.hpl.jena.iri.impl.IRIFactoryImpl
errors, specs, UNKNOWN_SYNTAX, warnings
 
Fields inherited from interface com.hp.hpl.jena.iri.ViolationCodes
ACE_PREFIX, BAD_BIDI_SUBCOMPONENT, BAD_DOT_IN_IDN, BAD_IDN, BAD_IDN_UNASSIGNED_CHARS, BIDI_FORMATTING_CHARACTER, COMPATIBILITY_CHARACTER, CONTROL_CHARACTER, DEFAULT_PORT_SHOULD_BE_OMITTED, DEPRECATED_UNICODE_CHARACTER, DISCOURAGED_IRI_CHARACTER, DISCOURAGED_XML_CHARACTER, DNS_LABEL_DASH_START_OR_END, DNS_LABEL_LENGTH_LIMIT, DNS_LENGTH_LIMIT, DOUBLE_DASH_IN_REG_NAME, DOUBLE_WHITESPACE, EMPTY_SCHEME, HAS_PASSWORD, ILLEGAL_CHARACTER, ILLEGAL_PERCENT_ENCODING, IP_V4_OCTET_RANGE, IP_V6_OR_FUTURE_ADDRESS_SYNTAX, IPv6ADDRESS_SHOULD_BE_LOWERCASE, LONE_SURROGATE, LOWERCASE_PREFERRED, MAYBE_NOT_NFC, MAYBE_NOT_NFKC, NON_INITIAL_DOT_SEGMENT, NON_URI_CHARACTER, NON_XML_CHARACTER, NOT_DNS_NAME, NOT_NFC, NOT_NFKC, NOT_UTF8_ESCAPE, NOT_UTF8_ESCAPE_IN_HOST, NOT_XML_SCHEMA_WHITESPACE, PERCENT, PERCENT_20, PERCENT_ENCODING_SHOULD_BE_UPPERCASE, PORT_SHOULD_NOT_BE_EMPTY, PORT_SHOULD_NOT_BE_WELL_KNOWN, PORT_SHOULD_NOT_START_IN_ZERO, PRIVATE_USE_CHARACTER, PROHIBITED_COMPONENT_PRESENT, QUERY_IN_LEGACY_SCHEME, REQUIRED_COMPONENT_MISSING, SCHEME_INCLUDES_DASH, SCHEME_MUST_START_WITH_LETTER, SCHEME_PATTERN_MATCH_FAILED, SCHEME_PREFERS_LOWERCASE, SCHEME_REQUIRES_LOWERCASE, SUPERFLUOUS_ASCII_PERCENT_ENCODING, SUPERFLUOUS_NON_ASCII_PERCENT_ENCODING, UNASSIGNED_UNICODE_CHARACTER, UNDEFINED_UNICODE_CHARACTER, UNICODE_CONTROL_CHARACTER, UNICODE_WHITESPACE, UNREGISTERED_IANA_SCHEME, UNREGISTERED_NONIETF_SCHEME_TREE, UNWISE_CHARACTER, USE_PUNYCODE_NOT_PERCENTS, WHITESPACE
 
Fields inherited from interface com.hp.hpl.jena.iri.impl.Force
dns, DNS, minting, MINTING, must, MUST, security, SECURITY, should, SHOULD, SIZE
 
Fields inherited from interface com.hp.hpl.jena.iri.IRIComponents
AUTHORITY, FRAGMENT, HOST, PATH, PATHQUERY, PORT, QUERY, SCHEME, USER
 
Constructor Summary
IRIFactory()
          Create a new IRIFactory without any conformance settings.
IRIFactory(IRIFactory template)
          Create a new IRIFactory with the same conformance settings as the template factory.
 
Method Summary
 void allowUnwiseCharacters()
          Allows the unwise characters as optionally permitted by RFC 3987 (IRI).
 IRI construct(java.lang.String scheme, java.lang.String userInfo, java.lang.String host, int port, java.lang.String path, java.lang.String query, java.lang.String fragment)
          Create an IRI from the given components.
 IRI construct(java.lang.String scheme, java.lang.String authority, java.lang.String path, java.lang.String query, java.lang.String fragment)
          Create an IRI from the given components.
 IRI create(java.lang.String scheme, java.lang.String userInfo, java.lang.String host, int port, java.lang.String path, java.lang.String query, java.lang.String fragment)
          Create an IRI from the given components.
 IRI create(java.lang.String scheme, java.lang.String authority, java.lang.String path, java.lang.String query, java.lang.String fragment)
          Create an IRI from the given components.
 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.
 boolean ignoring(int code)
          Is condition #code being ignored.
static IRIFactory iriImplementation()
          This factory implements RFC 3987 Internationalized Resource Identifiers (IRIs) .
 boolean isError(int code)
          Is condition #code being treated as an error.
 boolean isWarning(int code)
          Is condition #code being treated as a warning.
static IRIFactory jenaImplementation()
          For use by Jena team only.
 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.
 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.
static IRIFactory semanticWebImplementation()
          This factory is a conservative implementation appropriate for Semantic Web applications.
 void setEncoding(java.lang.String enc)
          Sets the character encoding to use for decoding and encoding to percent escape sequences.
static void setIriImplementation(IRIFactory iriF)
          This globally sets the iriImplementation(); use with care.
 void setIsError(int code, boolean set)
          Set condition #code to be treated as an error; or clear it as an error condition.
 void setIsWarning(int code, boolean set)
          Set condition #code to be treated as a warning; or clear it as a warning condition.
static void setJenaImplementation(IRIFactory jf)
          This globally sets the jenaImplementation(); use with care.
 void setQueryCharacterRestrictions(boolean restrict)
          The character constraints on the query component of an IRI are weaker than on other components.
 void setSameSchemeRelativeReferences(java.lang.String scheme)
          Allows scheme:relative-path as a relative reference against a base URI from the same scheme.
static void setSemanticWebImplementation(IRIFactory sw)
          This globally sets the semanticWebImplementation(); use with care.
static void setUriImplementation(IRIFactory uriF)
          This globally sets the uriImplementation(); use with care.
 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.
static IRIFactory uriImplementation()
          This factory implements RFC 3986 Uniform Resource Identifier (URI): Generic Syntax .
 void useSchemeSpecificRules(java.lang.String scheme, boolean asErrors)
          Use the rules for a given scheme, or use all known scheme specific rules.
 void useSpecificationIRI(boolean asErrors)
          The factory will check for violations of RFC 3987, IRI.
 void useSpecificationRDF(boolean asErrors)
          The factory will check for violations of RDF URI Reference.
 void useSpecificationURI(boolean asErrors)
          The factory will check for violations of RFC 3986, URI.
 void useSpecificationXLink(boolean asErrors)
          The factory will check for violations of XLink locator: href value.
 void useSpecificationXMLSchema(boolean asErrors)
          The factory will check for violations of XML Schema anyURI.
 void useSpecificationXMLSystemID(boolean asErrors)
          The factory will check for violations of XML constraints on system ID.
 
Methods inherited from class com.hp.hpl.jena.iri.impl.IRIFactoryImpl
create, create, getAsErrors, getAsWarnings, getFactory, getProhibited, getRequired, getScheme, initializing, noScheme, setViolation, useSpec
 
Methods inherited from class com.hp.hpl.jena.iri.impl.AbsIRIFactoryImpl
construct, construct, throwAnyErrors
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.hp.hpl.jena.iri.IRIFactoryI
construct, construct, create, create
 

Constructor Detail

IRIFactory

public IRIFactory()
Create a new IRIFactory without any conformance settings. To check for errors, you must call one or more of useSpecificationIRI(boolean), useSpecificationRDF(boolean), useSpecificationURI(boolean), useSpecificationXMLSchema(boolean), useSpecificationXLink(boolean) or useSpecificationXMLSystemID(boolean).


IRIFactory

public IRIFactory(IRIFactory template)
Create a new IRIFactory with the same conformance settings as the template factory. These can then be modified before using the new factory.

Method Detail

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

public static IRIFactory semanticWebImplementation()
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.

Returns:
A factory suitable for Semantic Web applications.

jenaImplementation

public static IRIFactory jenaImplementation()
For use by Jena team only. This method reflects the current IRI support in Jena, which is a moving target at present.

Returns:
A factory suitable for Jena.

setSameSchemeRelativeReferences

public void setSameSchemeRelativeReferences(java.lang.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 com.hp.hpl.jena.iri.impl.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(java.lang.String enc)
                 throws java.io.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 com.hp.hpl.jena.iri.impl.IRIFactoryImpl
Throws:
java.lang.IllegalStateException - If this factory has already been used to create an IRI.
java.io.UnsupportedEncodingException - If the encoding is not supported.

create

public IRI create(java.lang.String scheme,
                  java.lang.String userInfo,
                  java.lang.String host,
                  int port,
                  java.lang.String path,
                  java.lang.String query,
                  java.lang.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 -
userInfo -
host - Will be encoded using punycode, if necessary.
port - May be 0 for no port.
path - May not be null
query -
fragment -
Returns:
An IRI with the given components.
See Also:
setEncoding(String)

create

public IRI create(java.lang.String scheme,
                  java.lang.String authority,
                  java.lang.String path,
                  java.lang.String query,
                  java.lang.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 -
authority - Will be percent escaped if necessary
path - May not be null
query -
fragment -
Returns:
An IRI with the given components.
See Also:
setEncoding(String)

construct

public IRI construct(java.lang.String scheme,
                     java.lang.String userInfo,
                     java.lang.String host,
                     int port,
                     java.lang.String path,
                     java.lang.String query,
                     java.lang.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 -
userInfo -
host - Will be encoded using punycode, if necessary.
port - May be 0 for no port.
path - May not be null
query -
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:
setEncoding(String)

construct

public IRI construct(java.lang.String scheme,
                     java.lang.String authority,
                     java.lang.String path,
                     java.lang.String query,
                     java.lang.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 -
authority - Will be percent escaped if necessary
path - May not be null
query -
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:
setEncoding(String)

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:
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.IllegalArgumentException - if isError && isWarning.
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.IllegalArgumentException - if isError && isWarning.
java.lang.IllegalStateException - If this factory has already been used to create an IRI.

useSchemeSpecificRules

public void useSchemeSpecificRules(java.lang.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 com.hp.hpl.jena.iri.impl.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:
java.lang.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