jena-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From i..@apache.org
Subject svn commit: r1213114 - in /incubator/jena/site/trunk: content/jena/documentation/notes/iri.mdtext templates/sidenav.mdtext
Date Sun, 11 Dec 2011 23:51:03 GMT
Author: ijd
Date: Sun Dec 11 23:51:03 2011
New Revision: 1213114

URL: http://svn.apache.org/viewvc?rev=1213114&view=rev
Log:
Migrated (minimal) IRI documenation from old Jena site

Added:
    incubator/jena/site/trunk/content/jena/documentation/notes/iri.mdtext
Modified:
    incubator/jena/site/trunk/templates/sidenav.mdtext

Added: incubator/jena/site/trunk/content/jena/documentation/notes/iri.mdtext
URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/documentation/notes/iri.mdtext?rev=1213114&view=auto
==============================================================================
--- incubator/jena/site/trunk/content/jena/documentation/notes/iri.mdtext (added)
+++ incubator/jena/site/trunk/content/jena/documentation/notes/iri.mdtext Sun Dec 11 23:51:03
2011
@@ -0,0 +1,155 @@
+Title: Support for Internationalised Resource Identifiers in Jena
+
+The Jena IRI Library is an implementation of [RFC 3987](http://www.ietf.org/rfc/rfc3987.txt)
(IRI)
+and [RFC 3986](http://www.ietf.org/rfc/rfc3986.txt) (URI),
+and a partial implementation of other related standards. It is incomplete.
+
+## Javadoc
+
+[The IRI Library Javadoc (Public APIs)](TODO)
+
+The most important parts of the Javadoc are:
+
+[ViolationCodes](TODO)
+Gives the relationships between the error codes and the
+specifications.
+
+[IRI](TODO)
+Gives the main interface for IRIs.
+
+[IRIFactory](TODO)
+Gives the main class for creating IRIs, including specifying
+which specifications you wish to be using, and with what degree of
+force.
+
+## Minimal Documentation
+
+Unfortunately this version of the IRI Library has badly incomplete
+documentation, any help in producing good documentation would be
+appreciated.
+
+The current version is incomplete with little indication as to
+where. It is primarily intended to support the functionality of
+checking strings against any of the various IRI or URI
+specifications. Some support for different levels of checking is
+provided.
+
+These instructions are from a mail message on the `jena-dev` mailing
+list.
+
+    Summary:
+    =======
+    use something like:
+
+    import com.hp.hpl.jena.iri.*;
+
+     static IRIFactory iriFactory = IRIFactory
+                                    .semanticWebImplementation();
+
+    ...
+
+       boolean includeWarnings = false;
+       IRI iri;
+       iri = iriFactory.create{iriString); // always works
+       if (iri.hasViolation(includeWarnings)) {
+         // bad iri code
+       }
+
+    ...
+
+    Since you are taking IRI rules seriously, you may want to have
+    includeWarnings = true in the above.
+
+    Full version
+    ============
+    The code is found in the iri.jar, which is not particularly
+    well documented, and the source and documentation is in the
+    separate iri download, from the Jena download area.
+
+    As shown, you start by building an IRIFactory
+
+    com.hp.hpl.jena.iri.IRIFactory
+
+    this embodies some set of rules, against which you will check
+    an IRI.
+
+    The one we use is:
+      IRIFactory.jenaImplementation()
+        For use by Jena team only.
+        This method reflects the current IRI support
+        in Jena, which is a moving target at present.
+
+    (actually it hasn't ever moved - the main issue is to do with
+    file: IRIs - we definitely want to be more liberal than a
+    conservative reading of the specs allow, because, e.g.
+    filenames with spaces in happen, and because file uris like
+    file:localFile which aren't particularly conformant, also
+    happen).
+
+    others, that allow you to control which specs you are checking
+    against are:
+
+      IRIFactory.iriImplementation()   RFC 3987
+      IRIFactory.uriImplementation()   RFC 3986 (US-ASCII only)
+
+      IRIFactory.semanticWebImplementation()
+           This factory is a conservative implementation
+           appropriate for Semantic Web applications.
+
+    Having got your factory then you convert a string into an IRI
+    in one of two ways, depending on how you want to handle errors:
+
+    e.g.
+       IRI iri;
+       try {
+         iri = iriFactory.construct{iriString);
+       }
+       catch (IRIException e) {
+         // bad iri code
+
+       }
+
+
+    or
+
+       boolean includeWarnings = false;
+       IRI iri;
+       iri = iriFactory.create{iriString); // always works
+       if (iri.hasViolation(includeWarnings)) {
+         // bad iri code
+    // e.g.
+
+            Iterator it = iri.violations(includeWarnings);
+            while (it.hasNext()) {
+                Violation v = (Violation) it.next();
+       // do something:    printErrorMessages(v);
+
+            }
+       }
+
+    various warning and error conditions are listed in the java doc
+    for ViolationCodes (in the iri download).
+    An error is a MUST force statement from the spec,
+    a warning corresponds to a SHOULD force statement from the
+    spec. There is also some support for 'minting' violations,
+    which provide a stricter level of checking for
+    IRIs that you are generating, as opposed to IRIs
+    that have been passed to your application from elsewhere.
+
+    So that, if I remember correctly:
+
+    http://example.org:80/foo
+
+    raises a warning with code DEFAULT_PORT_SHOULD_BE_OMITTED
+
+    Like this one, many of the SHOULD force statements help avoid having
+    two different IRIs that have the same operational semantics.
+
+    Each spec is implemented as some set of active error and warning
+    codes, so depending on which factory you chose in the first place,
+    you may get a different collection of spec violations, some with
+    SHOULD force and some with MUST force.
+
+    There are also potentially warnings associated with security issues
+    like IRI spoofing, which may not strictly violate any SHOULDs
+    in any spec.

Modified: incubator/jena/site/trunk/templates/sidenav.mdtext
URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/templates/sidenav.mdtext?rev=1213114&r1=1213113&r2=1213114&view=diff
==============================================================================
--- incubator/jena/site/trunk/templates/sidenav.mdtext (original)
+++ incubator/jena/site/trunk/templates/sidenav.mdtext Sun Dec 11 23:51:03 2011
@@ -68,6 +68,7 @@
     - [RDF frames](/jena/documentation/notes/rdf-frames.html)
     - [Reification how-to](/jena/documentation/notes/reification.html)
     - [Typed literals how-to](/jena/documentation/notes/typed-literals.html)
+    - [Support for IRI's](/jena/documentation/notes/iri.html)
   - [Tools](/jena/documentation/tools/index.html)
     - [schemagen](/jena/documentation/tools/schemagen.html)
     - [eyeball](/jena/documentation/tools/eyeball-getting-started.html)



Mime
View raw message