You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jena.apache.org by ij...@apache.org on 2011/12/12 00:51:03 UTC
svn commit: r1213114 - in /incubator/jena/site/trunk:
content/jena/documentation/notes/iri.mdtext templates/sidenav.mdtext
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)