Package org.apache.jena.iri

Class IRIFactory

    • Method Detail

      • 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​(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 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 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 - 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:
        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 - 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:
        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 - 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:
        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 - 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:
        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 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