You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jena.apache.org by ch...@apache.org on 2012/10/16 17:20:36 UTC
svn commit: r1398843 [2/2] - in /jena/Scratch/Eyeball/trunk/doc: ./
eyeball-1-doc/
Added: jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-full.html
URL: http://svn.apache.org/viewvc/jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-full.html?rev=1398843&view=auto
==============================================================================
--- jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-full.html (added)
+++ jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-full.html Tue Oct 16 15:20:36 2012
@@ -0,0 +1,1396 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><!--
+ This is not the document you want to edit.
+
+ This document has been generated by the TOC-insertion tool.
+ You want to edit its template, not this document, which is
+ constructed by the `ant massage-manual` command from
+ `full-template.html`.
+
+--><html>
+<head>
+ <title>Eyeball 2.4</title>
+ <link href='styles/doc.css' rel='stylesheet' type='text/css'/>
+ <script>
+ function invert( id )
+ {
+ x = document.getElementById( id )
+ x.className = x.className == "hide" ? "show" : "hide"
+ }
+ </script>
+</head>
+<body>
+ <h1>summary</h1>
+
+ <p>This document describes Eyeball 2.4, an
+ "<a href='http://www.w3.org/RDF/'>RDF</a>
+ <a href='http://en.wikipedia.org/wiki/Lint_programming_tool'>lint</a>";
+ see the
+ <a href='ReleaseNotes.text'>release notes</a> for descriptions
+ of changes from previous versions.
+ Eyeball is part of the Jena family of RDF/OWL tools: see
+ <a href='http://jena.sourceforge.net'>jena.sourceforge.net</a>
+ for the Jena documentation and downloads. Support for the
+ Jena family is provided on the mailing lists
+ <i>jena-dev@yahoogroups.com</i> (for developers using Jena)
+ and <i>jena-devel@lists.sourceforge.net</i> (for developers
+ modifying or extending Jena). Note that, ny support is provided
+ on a voluntary basis, as and when the effort is available.
+ </p>
+
+ <p>
+ Throughout this document, the prefix <i>eye</i> stands for the
+ URL <i>http://jena.hpl.hp.com/Eyeball#</i>.
+ </p>
+
+ <h1 onClick='invert('TOC')'>table of contents [click to reveal]</h1>
+
+ <div class='hide' id='TOC'>
+ <div class='toc'>
+ <div class='toc-h2'><a href='#toc-0'>installation</a></div><div class='toc-h2'><a href='#toc-1'>command line operation</a></div><div class='toc-h3'><a href='#toc-2'>examples of command-line use</a></div><div class='toc-h3'><a href='#toc-3'>-check specialURL+</a></div><div class='toc-h3'><a href='#toc-4'>-config fileOrURL and -root rootURI</a></div><div class='toc-h3'><a href='#toc-5'>-set Setting*</a></div><div class='toc-h3'><a href='#toc-6'>-include/-exclude shortNames</a></div><div class='toc-h3'><a href='#toc-7'>-assume Reference</a></div><div class='toc-h3'><a href='#toc-8'>-sign and -accept (experimental)</a></div><div class='toc-h3'><a href='#toc-9'>-version</a></div><div class='toc-h3'><a href='#toc-10'>-remark</a></div><div class='toc-h3'><a href='#toc-11'>-repair and -analyse (experimental)</a></div><div class='toc-h3'><a href='#toc-12'>-render Name</a></div><div class='toc-h3'><a href='#toc-13'>setting the proxy</a></div><div class='toc-h2'><a href='#toc-14'>i
nspectors shipped with Eyeball</a></div><div class='toc-h3'><a href='#toc-15'>PropertyInspector (short name: "property")</a></div><div class='toc-h3'><a href='#toc-16'>ClassInspector (short name: "presumed-class")</a></div><div class='toc-h3'><a href='#toc-17'>URIInspector (short name: "URI")</a></div><div class='toc-h3'><a href='#toc-18'>LiteralInspector (short name: "literal")</a></div><div class='toc-h3'><a href='#toc-19'>PrefixInspector (short name: "prefix")</a></div><div class='toc-h3'><a href='#toc-20'>VocabularyInspector (short name: "vocabulary")</a></div><div class='toc-h3'><a href='#toc-21'>OwlSyntaxInspector (short name: "owl")</a></div><div class='toc-h3'><a href='#toc-22'>SparqlDrivenInspector (short name: "sparql")</a></div><div class='toc-h3'><a href='#toc-23'>AllTypedInspector (short name: "all-typed")</a></div><div class='toc-h3'><a href='#toc-24'>ConsistentTypeInspect
or (short name: "consistent-type")</a></div><div class='toc-h3'><a href='#toc-25'>CardinalityInspector (short name: "cardinality")</a></div><div class='toc-h3'><a href='#toc-26'>ListInspector (short name: "list")</a></div><div class='toc-h2'><a href='#toc-27'>Eyeball problem reports</a></div><div class='toc-h3'><a href='#toc-28'>PropertyInspector: predicate not declared</a></div><div class='toc-h3'><a href='#toc-29'>ClassInspector: class not declared</a></div><div class='toc-h3'><a href='#toc-30'>URIInspector: bad URI</a></div><div class='toc-h3'><a href='#toc-31'>LiteralInspector: illegal language code</a></div><div class='toc-h3'><a href='#toc-32'>LiteralInspector: bad datatype URI</a></div><div class='toc-h3'><a href='#toc-33'>LiteralInspector: bad lexical form</a></div><div class='toc-h3'><a href='#toc-34'>PrefixInspector: bad namespace URI</a></div><div class='toc-h3'><a href='#toc-35'>PrefixInspector: Jena prefix found</a></div><div class=
'toc-h3'><a href='#toc-36'>PrefixInspector: multiple prefixes for namespace</a></div><div class='toc-h3'><a href='#toc-37'>VocabularyInspector: not from schema</a></div><div class='toc-h3'><a href='#toc-38'>OwlSyntaxInspector: suspicious restriction</a></div><div class='toc-h3'><a href='#toc-39'>SparqlDrivenInspector: require failed</a></div><div class='toc-h3'><a href='#toc-40'>SparqlDrivenInspector: prohibit failed</a></div><div class='toc-h3'><a href='#toc-41'>AllTypedInspector: should have type</a></div><div class='toc-h3'><a href='#toc-42'>ConsistentTypeInspector: inconsistent types for resource</a></div><div class='toc-h3'><a href='#toc-43'>CardinalityInspector: cardinality failure</a></div><div class='toc-h3'><a href='#toc-44'>ListInspector: ill-formed list</a></div><div class='toc-h3'><a href='#toc-45'>ListInspector: suspect list idiom</a></div><div class='toc-h2'><a href='#toc-46'>inside the Eyeball configuration file</a></div><div class='toc-h3'><a href='#toc-47'>c
onfiguration files</a></div><div class='toc-h3'><a href='#toc-48'>configuring schema names</a></div><div class='toc-h3'><a href='#toc-49'>configuring inspectors</a></div><div class='toc-h3'><a href='#toc-50'>configuring the URI inspector</a></div><div class='toc-h3'><a href='#toc-51'>configuring the vocabulary inspector</a></div><div class='toc-h3'><a href='#toc-52'>configuring the SPARQL-driven inspector</a></div><div class='toc-h3'><a href='#toc-53'>configuring renderers</a></div><div class='toc-h2'><a href='#toc-54'>inside the Eyeball code</a></div><div class='toc-h3'><a href='#toc-55'>creating an Eyeball</a></div><div class='toc-h3'><a href='#toc-56'>to eyeball a model</a></div><div class='toc-h2'><a href='#toc-57'>rebuilding Eyeball</a></div><div class='toc-h2'><a href='#toc-58'>creating and configuring an inspector</a></div><div class='toc-h3'><a href='#toc-59'>creating an Inspector</a></div><div class='toc-h3'><a href='#toc-60'>reports and report properties</a></div><
div class='toc-h3'><a href='#toc-61'>configuring an inspector</a></div></div>
+ </div>
+
+ <h1>Eyeball - checking RDF for common problems</h1>
+
+ <p>Eyeball is a
+ library and command-line tool for checking RDF and OWL models for
+ various common problems. These problems often result in
+ technically correct but implausible RDF. Eyeball checks against
+ user-provided schema files and makes various closed-world
+ assumptions.
+ </p>
+
+ <p>Eyeball 2.4 can check for:</p>
+
+ <ul>
+ <li>unknown [with respect to the schemas] properties and classes</li>
+ <li>bad prefix namespaces</li>
+ <li>ill-formed URIs, with user-specifiable constraints</li>
+ <li>ill-formed language tags on literals</li>
+ <li>datatyped literals with illegal lexical forms</li>
+ <li>unexpected local names in schema namespaces</li>
+ <li>untyped resources and literals</li>
+ <li>individuals having consistent types, assuming complete typing</li>
+ <li>likely cardinality violations</li>
+ <li>broken RDF list structures</li>
+ <li>suspected broken use of the typed list idiom</li>
+ <li>obviously broken OWL restrictions</li>
+ <li>user-specified constraints written in SPARQL</li>
+ </ul>
+
+ <p>Eyeball's checks are performed by Inspector plug-ins and can
+ be customised by the user. Rendering its reports to output is
+ performed by Renderer plug-ins which can also be customised by
+ the user.</p>
+
+ <h2><a name='toc-0'></a>installation</h2>
+
+ <p>Fetch the Eyeball distribution zipfile and unpack it somewhere
+ convenient. Read the documention in the <i>doc</i> directory: the
+ one-minute guide <i>index.html</i>, the brief introduction
+ <i>brief.html</i>, and when necessary the manual <i>full.html</i>
+ (that's what this is).</p>
+
+ <p>Eyeball 2.4 comes with its own copy of Jena 2.5 with CVS
+ updates. Do <i>not</i> attempt to use other versions of Jena with
+ Eyeball.</p>
+
+ <p>In the Eyeball distribution directory, run the Eyeball
+ tests:
+ </p>
+
+ <blockquote>
+ ant test
+ </blockquote>
+
+ <p>
+ If these tests fail, something is wrong.
+
+ (The message <i>(Note:
+ statistician test disabled; don't worry about this.)</i> is not a
+ failure.)
+
+ Sometimes
+ it's no more than a classpath problem, which you can fix. If not,
+ use the <i>jena-dev</i> mailing list to request assistance. Note that,
+ just as with Jena itself, any support is provided on a voluntary
+ basis, as and when the effort is available.
+ </p>
+
+ <p>
+ If the tests have passed, you can use Eyeball from the installation
+ directory, or copy <i>lib</i>, <i>etc</i> and <i>mirror</i> to
+ somewhere convenient.
+ </p>
+
+ <h2><a name='toc-1'></a>command line operation</h2>
+
+ <p>
+ You must ensure that <i>all</i> the Eyeball jars from <i>lib</i>
+ are on your classpath. (Note that Eyeball comes with its own Jena
+ jar files and <i>may not work</i> with other Jena jars.) The
+ directories <i>etc</i> and <i>mirror</i> should be in the
+ current directory or also on your classpath.
+ </p>
+
+ <p>Run the Eyeball command:</p>
+
+ <pre>
+java [java options eg classpath and proxy] jena.eyeball
+ (-check | -sign | -accept) specialURL+
+ [-assume Reference*]
+ [-config fileOrURL*]
+ [-set Setting*]
+ [-root rootURI]
+ [-render Name]
+ [-include shortName*]
+ [-exclude shortName*]
+ [-analyse | -repair]
+ [-remark] [-version]
+</pre>
+
+ <p>
+ The -<i>whatever</i> sections can come in any order
+ and may be repeated, in which case the additonal arguments are appended
+ to the existing ones. Exactly one of <i>-check</i>, <i>-sign</i>,
+ <i>-accept</i>, or <i>version</i> must be provided; all the other
+ options are optional.
+ </p>
+
+ <p>
+ When Eyeball resolves ordinary filenames or URLs it uses the
+ Jena file manager to possibly map those names (<i>eg</i> to
+ redirect an <code>http:</code> URL to a local cached copy).
+ See the
+ <a href='http://jena.sourceforge.net/how-to/filemanager.html'>
+ file manager howto</a> for details on how to configure the
+ file manager.
+ </p>
+
+ <h3><a name='toc-2'></a>examples of command-line use</h3>
+
+ <pre>
+java jena.eyeball -version
+
+java jena.eyeball -check myDataFile.rdf
+
+java jena.eyeball -assume dc -check http://example.com/nosuch.n3
+
+java jena.eyeball -assume mySchema.rdf -check myData.rdf -render xml
+
+java jena.eyeball -check myData.rdf -include consistent-type
+
+java jena.eyeball -check myConfig.ttl -sign >signedConfig.ttl
+</pre>
+
+ <h3><a name='toc-3'></a>-check specialURL+</h3>
+
+ <p>The <i>-check</i> command checks the specified models for
+ problems. The <i>specialURL</i>s designate the models to be
+ checked. In the simplest case, these are plain filenames,
+ <code>file:</code> URLs, or <code>http:</code> URLs. At least one
+ <i>specialURL</i> must be specified. Each specified model is
+ checked independently of the others.</p>
+
+ <pre>
+-check myModel.ttl
+-check file:///c:/rdf/pizza.owl
+-check http://example.com/rdf/beer.rdf
+</pre>
+
+ <p>If the <i>specialURL</i> is of the form <i>ont:NAME:base</i>,
+ then the checked model is the model <i>base</i> treated as an
+ OntModel with the specification
+ <code>OntModelSpec.<i>NAME</i></code>; see <a href='http://jena.sourceforge.net/ontology/index.html#creatingModels'>the
+ Jena ontology documentation</a> for the available names.</p>
+ <pre>
+-check ont:OWL_MEM_RDFS_INF:myModel.ttl
+-check ont:OWL_DL_MEM_RULE_INF:http://example.com/rdf/beer.rdf
+</pre>
+
+ <p>If the <i>specialURL</i> is of the form <i>ja:R@AF</i>, then
+ the model is that described by the resource <i>R</i> in the Jena
+ <a href='http://jena.sourceforge.net/assembler/index.html'>assembler</a>
+ description file <i>AF</i>. <i>R</i> is prefix-expanded using the
+ prefixes in <i>AF</i>.</p>
+ <pre>
+-check ja:my:root@my-assembly.ttl
+-check ont:OWL_MEM_RDFS_INF:my:root@my-assembly.ttl
+</pre>
+
+ <p>If the URL (or the base) is of the form
+ <i>jdbc:DB:head:model</i>, then the checked model is the one
+ called <i>model</i> in the database with connection
+ <i>jdbc:DB:head</i>. (The database user and password must be
+ specified independently using the <i>jena.db.user</i> and
+ <i>jena.db.password</i> system properties.)</p>
+ <pre>
+-check jdbc:mysql://localhost/test:example
+</pre>
+
+ <h3><a name='toc-4'></a>-config fileOrURL and -root rootURI</h3>
+
+ <p>The <i>-config fileOrURL</i> options specify the Eyeball
+ <a href='http://jena.sourceforge.net/assembler/index.html'>assembler</a>
+ configuration files to load. A single configuration model is
+ constructed as the union of the contents of those files. If this
+ option is omitted, the default configuration file
+ <i>etc/eyeball-config.n3</i> is loaded. See <a href='#inside-configuration'>inside the Eyeball configuration file</a>
+ for details of the configuration file.</p>
+ <pre>
+-config my-hacked-config-file.n3
+-config etc/eyeball-config.n3 extras.ttl
+</pre>
+
+ <p>The <i>-root rootURI</i> option specifies the root resource in
+ the Eyeball configuration. If this option is omitted,
+ <i>eye:eyeball</i> is used by default. <i>rootURI</i> is
+ prefix-expanded using the prefixes in the configuration file.</p>
+ <pre>
+-root my:root
+-root my:sparse-config
+-root urn:x-hp:eyeball-roots:special
+</pre>
+
+ <h3><a name='toc-5'></a>-set Setting*</h3>
+
+ <p>
+ The <i>-set</i> option allows command-line tweaks to the
+ configuration, <i>eg</i> for enabling checking URIs for
+ empty local names. <i>You will rarely need to use this</i>;
+ it is presented here because of its association with
+ the <code>-config</code> and <code>-root</code> options.
+ </p>
+
+ <p>
+ Each <i>Setting</i> has the form <code>S.P=O</code> and adds
+ the statement <code>(S' P' O')</code> to the configuration.
+ </p>
+
+ <p>
+ The current Eyeball converts the components of the
+ <code>S.P=O</code> string into RDF nodes <code>S'</code>,
+ <code>P'</code>, <code>O'</code> using some special rules:
+ </p>
+
+ <ul>
+ <li>
+ A component starting with a digit is treated as an
+ xsd:integer literal (and hence should only appear as
+ the object of the setting).
+ </li>
+
+ <li>
+ A component starting with a quote, either <code>"</code>
+ or <code>'</code>, is treated as a literal whose lexical
+ form extends to the matching closing quote. Note:
+ (a) <i>literals with embedded spaces are not supported</i>;
+ (b) your command-line interpreter may treat quotes
+ specially, and to allow the quotes to pass through to
+ Eyeball, you'll have to use another (different) pair of
+ quotes!
+ </li>
+
+ <li>
+ A component starting with <code>_</code> is treated
+ as a blank node with that label.
+ </li>
+
+ <li>
+ Otherwise, the component is treated as a URI reference.
+ If it starts with a prefix (<i>eg</i>, <code>rdf:</code>)
+ that prefix is expanded using the prefixes of the configuration
+ file. If it has no prefix, it is as though the empty prefix
+ was specified: in the default configuration file, that is
+ set to the Eyeball namespace, so it is as though the prefix
+ <code>eye:</code> had been used.
+ </li>
+ </ul>
+
+ <p>
+ For example, to enable the URI inspectors non-default reporting
+ of URIs with empty local names, use:
+ </p>
+
+ <pre>
+-set URIInspector.reportEmptyLocalNames="'true'"
+</pre>
+
+ <p>
+ Note the nested different quotes required to pass 'true'
+ to Eyeball so that it can interpret this as a literal.
+ </p>
+
+ <h3><a name='toc-6'></a>-include/-exclude shortNames</h3>
+
+ <p>
+ The various Eyeball inspectors are given <i>short names</i> in
+ the configuration file. By default, an Eyeball check uses a
+ specific set of inspectors with short name
+ <i>defaultInspectors</i>. Additional inspectors can be enabled
+ using the <i>-include</i> option, and default inspectors can be
+ disabled using the <i>-exclude</i> option. See below for the
+ available inspectors and their short names, and see <a href='#inspectors-configuration'>inspectors configuration</a> for
+ how to configure inspectors.
+ </p>
+
+ <pre>
+-include list all-typed
+-exclude cardinality
+-include owl -exclude consistent-type
+</pre>
+
+ <h3><a name='toc-7'></a>-assume Reference</h3>
+
+ <p>The -assume <i>Reference</i>s identifies any assumed schemas
+ used to specify the predicates and classes of the data model. The
+ reference may be a file name or a URL (and may be mapped by the
+ file manager).</p>
+
+ <p>Eyeball automatically assumes the RDF and RDFS schemas, and
+ the built-in XSD datatype classes. The short name <i>owl</i> can
+ be used to refer to the OWL schema, <i>dc</i> to the Dublin Core
+ schema, <i>dcterms</i> to the Dublin Core terms schema, and
+ <i>dc-all</i> to both.</p>
+
+<pre>
+-assume owl
+-assume owl dc-all
+-assume owl my-ontology.owl
+</pre>
+
+ <h3><a name='toc-8'></a>-sign and -accept (experimental)</h3>
+
+ <p>If <i>-sign</i> is specified, Eyeball first does a
+ <i>-check</i>. If no problem reports are
+ generated, Eyeball writes a <i>signed</i> version of
+ the current model to the standard output. The signature
+ records the Eyeball configuration used and a weak hash
+ of the model. If the input model is already signed, that
+ signature is discarded before computing the new signature
+ and writing the output.
+ </p>
+
+ <p>
+ If <i>-accept</i> is specified, the model is checked for its
+ signature. If it is not signed, or if the signature does
+ not match the content of the model -- either the hash fails,
+ or the recorded configuration is not sufficient -- a problem
+ is reported; otherwise not.
+ </p>
+
+ <p>
+ The intended use of <i>-sign</i> and <i>-accept</i>
+ is that an application can require signed models
+ which have passed some minimum set of inspections.
+ The application code can then rely on the model
+ having the desired properties, without having to
+ run potentially expensive validation checks every
+ time a model is loaded.
+ </p>
+
+ <p>
+ <i>Important</i>. Model signing is intended to catch careless
+ mistakes, not for security against malicious users.
+ </p>
+
+ <h3><a name='toc-9'></a>-version</h3>
+
+ <p>
+ Eyeball will print its version on the standard error
+ stream (currently "<i>Eyeball 2.4 (Nova Embers)</i>").
+ </p>
+
+ <h3><a name='toc-10'></a>-remark</h3>
+
+ <p>Normally Eyeball issues its report or signed model to
+ the standard output and exits with code 0 (success)
+ or 1 (failure) with no additional output. Specifying
+ <i>-remark</i> causes it to report <i>success</i>
+ or <i>some problems reported</i> to standard error.
+ </p>
+
+
+ <h3><a name='toc-11'></a>-repair and -analyse (experimental)</h3>
+
+ <p>These operations are not currently documented. Try them at
+ your peril: <i>-repair</i> may attempt to update your models.
+ </p>
+
+ <h3><a name='toc-12'></a>-render Name</h3>
+
+ <p>The eyeball reports are written to the standard output; by
+ default, the reports appear as text (RDF rendered by omitting the
+ subjects - which are all blank nodes - and lightly prettifying
+ the predicate and object). To change the rendering style, supply
+ the <i>-render</i> option with the name of the renderer as its
+ value. Eyeball comes with N3, XML, and text renderers; the
+ Eyeball config file associates renderer names with their
+ classes.</p>
+ <pre>
+-render n3
+-render rdf
+</pre>
+
+ <h3><a name='toc-13'></a>setting the proxy</h3>
+
+ <p>
+ If any of the data or schema are identified by an http: URL,
+ and you are behind a firewall, you will need specify the proxy to
+ Java using system properties; one way to do this is by using the
+ Java command line options:
+ </p>
+
+ <pre>
+ -DproxySet=true
+ -DproxyHost=theProxyHostName
+ -DproxyPort=theProxyPortNumber
+</pre>
+
+ <h2><a name='toc-14'></a>inspectors shipped with Eyeball</h2>
+
+ <p>Eyeball comes with a collection of inspectors that do
+ relatively simple checks.</p>
+
+ <h3><a name='toc-15'></a>PropertyInspector (short name: "property")</h3>
+
+ <p>Checks that every predicate that appears in the model is
+ declared in some <i>-assume</i>d schema or
+ <code>owl:import</code>ed model -- that is, is given
+ <code>rdf:type</code> <code>rdf:Property</code> or some subclass
+ of it.</p>
+
+ <h3><a name='toc-16'></a>ClassInspector (short name: "presumed-class")</h3>
+
+ <p>Checks that every resource in the model that is used as a
+ class, <i>ie</i> that appears as the object of an
+ <code>rdf:type</code>, <code>rdfs:domain</code>, or
+ <code>rdfs:range</code> statement, or as the subject or object of
+ an <code>rdfs:subClassOf</code> statement, has been declared as a
+ <code>Class</code> in the <i>-assume</i>d schemas or in the model
+ under test.</p>
+
+ <h3><a name='toc-17'></a>URIInspector (short name: "URI")</h3>
+
+ <p>Checks that every URI in the model is well-formed according to
+ the rules of the Jena IRI library. May apply additional rules
+ specified in the configuration file: see <a href='#uri-configuration'>uri configuration</a> later for details.</p>
+
+ <h3><a name='toc-18'></a>LiteralInspector (short name: "literal")</h3>
+
+ <p>
+ Checks literals for syntactically correct language codes,
+ syntactically correct datatype URIs (using the same rules as the
+ URIInspector), and conformance of the lexical form of typed
+ literals to their datatype.
+ </p>
+
+ <h3><a name='toc-19'></a>PrefixInspector (short name: "prefix")</h3>
+
+ <p>The PrefixInspector checks that the prefix declarations of the
+ model have namespaces that are valid URIs and that if the prefix
+ name is "well-known" (<code>rdf</code>, <code>rdfs</code>,
+ <code>owl</code>, <code>xsd</code>, and <code>dc</code>) then the
+ associated URI is the one usually associated with the prefix.</p>
+
+ <p>The PrefixInspector also reports a problem if any prefix looks
+ like an Jena automatically-generated prefix,
+ <code>j.<i>Number</i></code>. (Jena generates these prefixes when
+ writing RDF/XML if the XML syntactically requires a prefix but
+ the model hasn't defined one.)</p>
+
+ <h3><a name='toc-20'></a>VocabularyInspector (short name: "vocabulary")</h3>
+
+ <p>Checks that every URI in the model with a namespace which is
+ mentioned in some schema is one of the URIs declared for that
+ namespace -- that is, it assumes that the schemas define a closed
+ set of URIs.</p>
+
+ <p>The inspector may be configured to suppress this check for
+ specified namespaces: see <a href='#configure-vocabulary'>vocabulary configuration</a> later.</p>
+
+ <h3><a name='toc-21'></a>OwlSyntaxInspector (short name: "owl")</h3>
+
+ <p>This inspector looks for "suspicious restrictions" which have
+ some of the OWL restriction properties but not exactly one
+ owl:onProperty and exactly one constraint (owl:allValuesFrom,
+ etc).</p>
+
+ <h3><a name='toc-22'></a>SparqlDrivenInspector (short name: "sparql")</h3>
+
+ <p>The SparqlDrivenInspector is configured according to <a href='#SPARQL-driven'>configuring the SPARQL-driven inspector</a>, and
+ applies arbitrary SPARQL queries to the model. The queries can be
+ required to match or prohibited from matching; a problem is
+ reported if the constraint fails.</p>
+
+ <h3><a name='toc-23'></a>AllTypedInspector (short name: "all-typed")</h3>
+
+ <p>
+ Checks that all URI and bnode resources in the model have an
+ rdf:type property in the model or the schema(s). If there is
+ a statement in the confiuration with property
+ <code>eye:checkLiteralTypes</code> and value <code>eye:true</code>,
+ also checks that every literal has a type or a language.
+ <i>Not</i> in the default set of inspectors.
+ </p>
+
+ <h3><a name='toc-24'></a>ConsistentTypeInspector (short name: "consistent-type")</h3>
+
+ <p>
+ Checks that every subject in the model can
+ be given a type which is the intersection of the subclasses of
+ all its "attached" types -- a "consistent type".
+ </p>
+
+ <p>
+ For example, if the model contains three types
+ <code>Top</code>, <code>Left</code>, and <code>Right</code>, with
+ <code>Left</code> and <code>Right</code> both being subtypes of
+ <code>Top</code> and with no other subclass statements, then some
+ <code>S</code> with <code>rdf:type</code>s <code>Left</code> and
+ <code>Right</code> would generate this warning.
+ </p>
+
+ <h3><a name='toc-25'></a>CardinalityInspector (short name: "cardinality")</h3>
+
+ <p>
+ Looks for classes <i>C</i> that are subclasses of cardinality
+ restrictions on some property <i>P</i> with cardinality range
+ <i>min</i> to <i>max</i>. For any <i>X</i> of <code>rdf:type</code>
+ <i>C</i>, it checks that the number of values of <i>P</i> is in
+ the range <i>min..max</i> and generates a report if it isn't.
+ </p>
+
+ <p>Literals are counted as distinct if their values (not just their
+ lexical form) are distinct. Resources are counted as distinct if
+ they have different case-sensitive URIs: the CardinalityInspector
+ takes no account of <code>owl:sameAs</code> statements.
+ </p>
+
+ <h3><a name='toc-26'></a>ListInspector (short name: "list")</h3>
+
+ <p>The ListInspector performs two separate checks:
+ </p>
+
+ <ul>
+ <li>looks for lists that are ill-formed by having multiple or
+ missing rdf:first or rdf:rest properties on their elements.
+ </li>
+
+ <li>looks for possible mis-uses of the "typed list" idiom, and
+ reports the types so defined.
+ </li>
+ </ul>
+
+ <p>The <i>typed list idiom</i> is boilerplate OWL for defining
+ a type which is List-of-T for some type T. It takes the form:
+ </p>
+
+ <pre>
+my:EList a owl:Class
+ ; rdfs:subClassOf rdf:List
+ ; rdfs:subClassOf [owl:onProperty rdf:first; owl:allValuesFrom my:Element]
+ ; rdfs:subClassOf [owl:onProperty rdf:rest; owl:allValuesFrom my:EList]
+ .
+</pre>
+
+ <p>
+ The type <code>my:Element</code> is the element type of the
+ list, and the type <code>EList</code> is the resulting typed list.
+ The list inspector checks that all the subclasses of
+ <code>rdf:List</code> (such as <i>EList</i> above) that are also
+ subclasses of any bnode (such as the two other superclasses of
+ <i>EList) </i>that has any property (<i>eg</i>, <i>owl:onProperty</i>)
+ that has as an object either <code>rdf:first</code> or
+ <code>rdf:rest</code> is a subclass defined by the full idiom above:
+ if not, it reports it as a <code> suspectListIdiom</code>.
+ </p>
+
+ <h2><a name='toc-27'></a>Eyeball problem reports</h2>
+
+ <p>Eyeball generates its reports as <i>items</i> in a model. Each
+ item has <code>rdf:type</code> <code>eye:Item</code>, and its
+ other properties determine what problem report it is. The default
+ text renderer displays a prettified form of each item; use
+ <i>-render n3</i> to expose the complete report structure.
+ </p>
+
+ <p>One of the item's properties is its <i>main property</i>,
+ which identifies the problem; the others are qualifications
+ supplying additional detail.
+ </p>
+
+ <h3><a name='toc-28'></a>PropertyInspector: predicate not declared</h3>
+
+ <blockquote>
+ [] eye:unknownPredicate "<i>URIString</i>".
+ </blockquote>
+
+ <p>The predicate with the given URI is not defined in any
+ of the <i>-assumed</i> schemas.
+ </p>
+
+ <h3><a name='toc-29'></a>ClassInspector: class not declared</h3>
+
+ <blockquote>
+ [] eye:unknownClass "<i>URIString</i>".
+ </blockquote>
+
+ <p>The resource with the given URI is used as a Class, but not
+ defined in any of the <i>-assumed</i> schemas.
+ </p>
+
+ <h3><a name='toc-30'></a>URIInspector: bad URI</h3>
+
+ <blockquote>
+ [] eye:badURI "<i>URIString</i>"; eye:forReason <i>Reason</i>.
+ </blockquote>
+
+ <p>The <i>URIString</i> isn't legal as a URI, or is legal but fails
+ a user-specified spelling constraint. <i>Reason</i> is a
+ resource or string identifying the reason.
+ </p>
+
+ <table border='1' style='margin-left: 4ex; margin-right: 4ex; font-size: x-small'>
+ <thead>
+ <tr><th>reason</th><th>explanation</th></tr>
+ </thead>
+ <tr>
+ <td>eye:uriContainsSpaces</td>
+ <td>the URI contains unencoded spaces, probably as a result
+ of sloppy use of file: URLs.</td>
+ </tr>
+
+ <tr>
+ <td>eye:uriFileInappropriate</td>
+ <td>a URI used as a namespace is a file: URI, which is
+ inappropriate as a global identifier.</td>
+ </tr>
+
+ <tr>
+ <td>eye:uriHasNoScheme</td>
+ <td>a URI has no scheme field, probably a misused relative
+ URI.</td>
+ </tr>
+
+ <tr>
+ <td>eye:schemeShouldBeLowercase</td>
+ <td>the scheme part of a URI is not lower-case; while
+ technically correct, this is not usual practice.</td>
+ </tr>
+
+ <tr>
+ <td>eye:uriFailsPattern</td>
+ <td>a URI fails the pattern appropriate to its schema (as
+ defined in the configuration for this eyeball).</td>
+ </tr>
+
+ <tr>
+ <td>eye:unrecognisedScheme</td>
+ <td>the URI scheme is unknown, perhaps a misplaced
+ QName.</td>
+ </tr>
+
+ <tr>
+ <td>eye:uriNoHttpAuthority</td>
+ <td>an http: URI has no authority (domain name/port)
+ component.</td>
+ </tr>
+
+ <tr>
+ <td>eye:uriSyntaxFailure</td>
+ <td>the URI can't be parsed using the general URI syntax,
+ even with any spaces removed.</td>
+ </tr>
+
+ <tr>
+ <td>eye:namespaceEndsWithNameCharacter</td>
+ <td>a namespace URI ends in a character that can appear in a
+ name, leading to possible ambiguities.</td>
+ </tr>
+
+ <tr>
+ <td>eye:uriHasNoLocalname</td>
+ <td>a URI has no local name according to the XML
+ name-splitting rules. (For example, the URI
+ <i>http://x.com/foo#12345</i> has no local name because a
+ local name cannot start with a digit.)</td>
+ </tr>
+
+ <tr>
+ <td>"did not match required pattern <i>Tail<sub>i</sub></i> for prefix <i>Head</i>".
+ </td>
+ <td>This badURI starts with <i>Head</i>, but the remainder doesn't
+ match any of the <i>Tail<sub>i</sub></i>s associated with that
+ prefix.
+ </td>
+ </tr>
+
+ <tr>
+ <td>"matched prohibited pattern <i>Tail</i> for prefix <i>Head</i>".
+ </td>
+ <td>This badURI starts with <i>Head</i>, and the remainder matched
+ a prohibited <i>Tail</i> associated with that prefix.
+ </td>
+ </tr>
+ </table>
+
+ <h3><a name='toc-31'></a>LiteralInspector: illegal language code</h3>
+
+ <blockquote>
+ [] eye:badLanguage "<i>badCode</i>"; eye:onLiteral "<i>spelling</i>".
+ </blockquote>
+
+ <p>A literal with the lexical form <i>spelling</i> has the illegal
+ language code <i>badCode</i>.
+ </p>
+
+ <h3><a name='toc-32'></a>LiteralInspector: bad datatype URI</h3>
+
+ <blockquote>
+ [] eye:badDatatypeURI "<i>badURI</i>"; eye:onLiteral "<i>spelling</i>".
+ </blockquote>
+
+ <p>A literal with the lexical form <i>spelling</i> has the illegal
+ datatype URI <i>badURI</i>.
+ </p>
+
+ <h3><a name='toc-33'></a>LiteralInspector: bad lexical form</h3>
+
+ <blockquote>
+ [] eye:badLexicalForm "<i>spelling</i>"; eye:forDatatype "<i>dtURI</i>".
+ </blockquote>
+
+ <p>A literal with the datatype URI <i>dtURI</i> has the lexical form
+ <i>spelling</i>, which isn't legal for that datatype.
+ </p>
+
+ <h3><a name='toc-34'></a>PrefixInspector: bad namespace URI</h3>
+
+ <blockquote>
+ [] eye:badNamespaceURI "<i>URIString</i>"
+ ; eye:onPrefix "<i>prefix</i>"
+ ; eye:forReason <i>Reason</i>.
+ </blockquote>
+
+ <p>The namespace <i>URIString</i> for the declaration of <i>prefix</i>
+ is suspicious for the given <i>Reason</i> (see the URIInspector reports
+ for details of the possible reasons).
+ </p>
+
+ <h3><a name='toc-35'></a>PrefixInspector: Jena prefix found</h3>
+
+ <blockquote>
+ [] eye:jenaPrefixFound "<i>j.Digits</i>"; eye:forNamespace "<i>URIString</i>".
+ </blockquote>
+
+ <p>The namespace <i>URIString</i> has an automatically-generated
+ Jena prefix.
+ </p>
+
+ <h3><a name='toc-36'></a>PrefixInspector: multiple prefixes for namespace</h3>
+
+ <blockquote>
+ [] eye:multiplePrefixesForNamespace "<i>NameSpace</i>"
+ ; eye:onPrefix "<i>prefix<sub>1</sub>"</i> ...
+ </blockquote>
+
+ <p>
+ There are multiple prefix declarations for <i>NameSpace</i>,
+ namely, <i>prefix<sub>1</sub></i> etc.
+ </p>
+
+ <h3><a name='toc-37'></a>VocabularyInspector: not from schema</h3>
+
+ <blockquote>
+ [] eye:notFromSchema "<i>NameSpace</i>"; eye:onResource <i>Resource</i>.
+ </blockquote>
+
+ <p>The <i>Resource</i> has a URI in the <i>NameSpace</i>, but isn't declared
+ in the schema associated with that <i>NameSpace</i>.
+ </p>
+
+ <h3><a name='toc-38'></a>OwlSyntaxInspector: suspicious restriction</h3>
+
+ <blockquote>
+ [] eye:suspiciousRestriction <i>R</i>; eye:forReason <i>Reason</i>...
+ </blockquote>
+
+ <p>The presumed restriction <i>R</i> is suspicious for the given <i>Reason</i>s:
+ <ul>
+ <li><code>eye:missingOnProperty</code> -- there is no
+ <code>owl:onProperty</code> property in this suspicious restriction.
+ </li>
+ <li><code>eye:multipleOnProperty</code> -- there are multiple
+ <code>owl:onProperty</code> properties in this suspicious restriction.
+ </li>
+ <li><code>eye:missingConstraint</code> -- there is no <code>owl:hasValue</code>,
+ <code>owl:allValuesFrom</code>, <code>owl:someValuesFrom</code>,
+ or <code>owl:[minC|maxC|c]ardinality</code> property in this suspicious
+ restriction.
+ </li>
+ <li><code>eye:multipleConstraint</code> -- there are multiple constraints
+ (as above) in this suspicious restriction.
+ </li>
+ </ul>
+ </p>
+
+ <p>The restriction <i>R</i> is identified by (a) supplying its immediate properties,
+ and (b) identifying its named equivalent classes and subclasses.
+ </p>
+
+ <h3><a name='toc-39'></a>SparqlDrivenInspector: require failed</h3>
+
+ <blockquote>
+ [] eye:sparqlRequireFailed "<i>message</i>".
+ </blockquote>
+
+ <p>A SPARQL query that was required to succeed against the model did not.
+ The <i>message</i> is either the query that failed or a meaningful
+ description, depending on the inspector configuration.
+ </p>
+
+ <h3><a name='toc-40'></a>SparqlDrivenInspector: prohibit failed</h3>
+
+ <blockquote>
+ [] eye:sparqlProhibitFailed "<i>message</i>".
+ </blockquote>
+
+ <p>A SPARQL query that was required to fail against the model did not.
+ The <i>message</i> is either the query that succeeded or a meaningful
+ description, depending on the inspector configuration.
+ </p>
+
+ <h3><a name='toc-41'></a>AllTypedInspector: should have type</h3>
+
+ <blockquote>
+ [] eye:shouldHaveType <i>Resource</i>.
+ </blockquote>
+
+ <p>The <i>Resource</i> has no <code>rdf:type</code>. Note that
+ when using models with inference, this report is unlikely, since
+ inference may well give the resource a type even if it has
+ no explicit type in the original model.
+ </p>
+
+ <h3><a name='toc-42'></a>ConsistentTypeInspector: inconsistent types for resource</h3>
+
+ <blockquote>
+ [] eye:noConsistentTypeFor <i>URI</i>
+ ; eye:hasAttachedType <i>TypeURI<sub>i</sub></i> ...
+ </blockquote>
+
+ <p>
+ The resource <i>URI</i> has been given the various types
+ <i>TypeURI<sub>i</sub></i>, but if we assume that subtypes are
+ disjoint unless otherwise specified, these types have no
+ intersection.
+ </p>
+
+ <p>The ConsistentTypeInspector must do at least some type
+ inference. This release of Eyeball compromises by doing RDFS
+ inference augmented by (very) limited union and intersection
+ reasoning, as described in the Jena rules in
+ <code>etc/owl-like.rules</code>, so its reports must be
+ treated with caution. Even with these restrictions, doing type inference
+ over a large model is costly: you may need to suppress it with
+ <code>-exclude</code> until any other warnings are dealt
+ with.
+ </p>
+
+ <p>While, technically, a resource with no attached types at all
+ is automatically inconsistent, Eyeball quietly ignores such
+ resources, since they turn up quite often in simple RDF
+ models.
+ </p>
+
+ <h3><a name='toc-43'></a>CardinalityInspector: cardinality failure</h3>
+
+ <blockquote>
+ [] eye:cardinalityFailure <i>Subject</i>; eye:onType <i>T</i>; eye:onProperty <i>P</i>
+ </blockquote>
+
+ <p>
+ The <i>Subject</i> has a cardinality-constrained <code>rdf:type</code> <i>T</i>
+ with <code>owl:onProperty</code> <i>P</i>, but the number of distinct values
+ in the model isn't consistent with the cardinality restriction.
+ </p>
+
+ <p>Additional properties describe the cardinality restriction and the values found:
+
+ <ul>
+ <li><code>eye:numValues</code> <i>N</i>: the number of distinct values
+ for (<i>Subject</i>, <i>P</i>) in the model.
+ </li>
+ <li><code>eye:cardinality</code>
+ [<code>eye:min</code> <i>min</i>; <code>eye:max</code> <i>max</i>]:
+ the minimum and maximum cardinalities permitted.
+ </li>
+ <li><code>eye:values</code> <i>Set</i>:
+ A blank node of type <code>eye:Set</code> with an <code>rdfs:member</code>
+ value for each of the values of <i>P</i>.
+ </li>
+ </ul>
+ </p>
+
+ <h3><a name='toc-44'></a>ListInspector: ill-formed list</h3>
+
+ <blockquote>
+ [] eye:illFormedList <i>URI</i>
+ ; eye:because [eye:element <i>index<sub>i</sub></i>; <i>Problem<sub>i</sub></i>]<sub>i</sub> ...
+ </blockquote>
+
+ <p>The list starting at <i>URI</i> is ill-formed because the element with
+ index <i>index<sub>i</sub></i> had <i>Problem<sub>i</sub></i>. The
+ possible problems are:
+ <ul>
+ <li><code>eye:hasNoRest</code> -- the element has no <code>rdf:rest</code> property.
+ </li>
+ <li><code>eye:hasMultipleRests</code> -- the element has more than one
+ <code>rdf:rest</code> property.
+ </li>
+ <li><code>eye:hasNoFirst</code> -- the element has no <code>rdf:first</code> property.
+ </li>
+ <li><code>eye:hasMultipleFirsts</code> -- the element has more than one
+ <code>rdf:rest</code> property.
+ </li>
+ </ul>
+
+ </p>
+
+ <h3><a name='toc-45'></a>ListInspector: suspect list idiom</h3>
+
+ <blockquote>
+ [] eye:suspectListIdiom <i>Type</i>.
+ </blockquote>
+
+ <p>
+ The resource <i>Type</i> looks like it's supposed to be a use of the
+ "typed list idiom", but it isn't complete/accurate.
+ </p>
+
+ <h2><a name='toc-46'></a><a name='inside-configuration'>inside the Eyeball configuration file</a></h2>
+
+ <h3><a name='toc-47'></a><a name='load-config-files' id='load-config-files'/>configuration files</h3>
+
+ The Eyeball
+ command-line utility is configured by files (or URLs) specified
+ on the command line: their RDF contents are unioned together into
+ a single config model. If no config file is specified, then
+ <i>etc/eyeball-config.n3</i> is loaded.
+
+ <p>
+ The configuration file is a Jena assembler description
+ (see <a href='http://jena.sourceforge.net/assembler/index.html'>
+ http://jena.sourceforge.net/assembler/index.html</a>)
+ with added Eyeball vocabulary.
+ </p>
+
+ <p>Eyeball is also configured by the location-mapping file
+ <i>etc/location-mapping.n3</i>. The Eyeball jar contains copies
+ of both the default config and the location mapper; these are
+ used by default. You can provide your own
+ <i>etc/eyeball-config.n3</i> file earlier on your classpath or in
+ your current directory; this config replaces the default. You may
+ provide <i>additional</i> location-mapping files earlier on your
+ classpath or in your current directory.</p>
+
+ <h3><a name='toc-48'></a>configuring schema names</h3>
+
+ To avoid having to quote schema
+ names in full on the Eyeball command line, (collections of)
+ schemas can be given short names.
+
+ <pre>
+[] eye:shortName <i>shortNameLiteral</i>
+ ; eye:schema <i>fullSchemaURL</i>
+ ...
+ .
+</pre>
+
+ <p>
+ A shortname can name several schemas. The Eyeball
+ delivery has the short names <i>rdf</i>, <i>rdfs</i>, <i>owl</i>,
+ and <i>dc</i> for the corresponding schemas (and mirror versions
+ of those schemas so that they don't need to be downloaded each
+ time Eyeball is run.)
+ </p>
+
+ <h3><a name='toc-49'></a><a name='inspectors-configuration'>configuring inspectors</a></h3>
+
+ <p>
+ The inspectors that Eyeball runs
+ over the model are specfied by <i>eye:inspector</i> properties of
+ inspector resources. These resources are identified by
+ <code>eye:shortName</code>s (supplied on the command line). Each
+ such property value must be a plain string literal whose value is
+ the full name of the Inspector class to load and run; see the
+ Javadoc of Inspector for details.
+ </p>
+
+ <p>An inspector resource may refer to other inspector resources
+ to include their inspectors, using either of the two properties
+ <code>eye:include</code> or <code>eye:includeByName</code>. The
+ value of an <code>include</code> property should be another
+ inspector resource; the value of an <code>includeByName</code>
+ property should be the <code>shortName</code> of an inspector
+ resource.</p>
+
+ <h3><a name='toc-50'></a><a name='uri-configuration'>configuring the URI inspector</a></h3>
+
+ <p>As well as applying the standard URI rules, Eyeball allows
+ extra pattern-oriented checks to be applied to URIs. These are
+ specified by <code>eye:check</code> properties of the
+ <code>URIInspector</code> object in the configuration.</p>
+
+ <p>The object of an <code>eye:check</code> property is a bnode
+ with <code>eye:prefix</code>, <code>eye:prohibit</code>, and
+ <code>eye:require</code> properties. The objects of these
+ properties must be string literals.</p>
+
+ <p>If a URI <i>U</i> can be split into a prefix <i>P</i> and
+ suffix <i>S</i>, and there is a <i>check</i> property with that
+ prefix, and either:</p>
+
+ <ul>
+ <li>there's a <i>prohibit</i> property and <i>S</i> matches the
+ object of that property, or</li>
+
+ <li>there's a <i>require</i> property and <i>S</i> does not
+ match the object of that property,</li>
+ </ul>
+
+ <p>then a problem is reported. If there are multiple
+ <code>prohibit</code>s, then a problem is reported if <i>any</i>
+ prohibition is violated; if there are multiple
+ <code>require</code>s, a problem is reported if <i>none</i> of
+ them succeed.
+ </p>
+
+ <pre>
+eye:URIInspector eye:check
+ [eye:prefix "urn:x-hp:"; eye:prohibit ".*:.*"]
+ ; [eye:prefix "http://example.com/"; eye:require ".*eyeball.*"]
+</pre>The prefixes, requires, and prohibits are treated as Java
+patterns.
+
+ <p>
+ The URI inspector can be configured to report URIs with an
+ empty local name. These arise because the meaning of "local
+ name" comes from XML, and in XML a local name must start with
+ an NCName character, typically a letter but not a digit. Hence
+ URIs like <code>http://example.com/productCode#1829</code>
+ have an empty local name. This is sometimes confusing.
+ </p>
+
+ <p>
+ To report empty local names, add the property
+ <code>eye:reportEmptyLocalNames</code> to the inspector
+ <code>eye:URIInspector</code> with the property value
+ <code>true</code>. You may edit the configuration file
+ or use the <code>-set</code> command-line option.
+ </p>
+
+ <h3><a name='toc-51'></a><a name='configure-vocabulary'>configuring the vocabulary inspector</a></h3>
+
+ <p>The vocabulary inspector defaults to assuming that schema
+ namespaces are closed. To disable this for specified namespaces,
+ the inspector object in the configuration can be given
+ <code>eye:openNamespace</code> properties.</p>
+
+ <p>The object of each of these properties must be a resource; the
+ URI of this resource is an open namespace for which the inspector
+ will not report problems.</p>
+ <pre>
+eye:VocabularyInspector eye:openNamespace <http://example.com/examples#>
+</pre>
+
+ <h3><a name='toc-52'></a><a name='SPARQL-driven'>configuring the SPARQL-driven inspector</a></h3>
+
+ <p>The SPARQL inspector object in the configuration may be given
+ <code>eye:sparql</code> properties whose objects are resources
+ specifying SPARQL queries and problem messages.
+ </p>
+
+ <pre>
+eye:SparqlDrivenInspector eye:sparql [...]
+</pre>
+
+ <p>The resource may specify a SPARQL query which must succeed in
+ the model, and a message to produce if it does not.
+ </p>
+ <pre>
+eye:SparqlDrivenInspector eye:sparql
+ [eye:require "select * where {?s ?p ?o}"; eye:message "must be non-empty"]
+</pre>
+
+ <p>If the query is non-trivial, the string may contain a
+ reference to a file containing the query, rather than the entire
+ query.
+ </p>
+
+ <pre>
+eye:require "@'/home/kers/example/query-one.sparql'"
+</pre>
+
+ <p>The quoted filename is read using the Jena file manager and
+ so respects any filename mappings. "@" characters not followed
+ by "'" are not subject to substitution, except that the
+ sequence "@@" is replaced by "@".
+ </p>
+
+ <p>Using
+ <code>eye:prohibit</code> rather than <code>eye:require</code>
+ means that the problem is reported if the query succeeds, rather
+ than if it fails.
+ </p>
+
+ <h3><a name='toc-53'></a>configuring renderers</h3>
+
+ <p>
+ The renderer class that Eyeball
+ uses to render the report into text is giving in the config file
+ by triples of the form:
+ </p>
+
+ <pre>
+[]
+ eye:renderer FullClassName
+ ; eye:shortName ShortClassHandler
+</pre>
+
+ <p>
+ The <code>FullClassName</code> is a string literal giving the
+ full class name of the rendering class. That class must implement
+ the <i>Renderer</i> interface and have a constructor that takes a
+ <code>Resource</code>, its configuration root, as its argument.
+ </p>
+
+ <p>The <code>ShortClassHandle</code> is a string literal giving
+ the short name used to refer to the class. The default short name
+ used is <b>default</b>. There should be no more than one
+ <i>eye:shortName</i> statement with the same ShortClassHandle in
+ the configuation file, but the same class can have many different
+ short names.</p>
+
+ <p>The <code>TextRenderer</code> supports an additional property
+ <code>eye:labels</code> to allow the appropriate labels for an
+ ontology to be supplied to the renderer. Each object of a
+ <code>eye:labels</code> statement names a model; all the
+ <code>rdfs:label</code> statements in that model are used to
+ supply strings which are used to render resources.</p>
+
+ <p>The model names are strings which are interpreted by Jena's
+ <code>FileManager</code>, so they may be redirected using Jena's
+ file mappings.</p>
+
+ <h2><a name='toc-54'></a>inside the Eyeball code</h2>
+
+ <p>Eyeball can be used from within Java code; the command line
+ merely provides a convenient external interface.</p>
+
+ <h3><a name='toc-55'></a>creating an Eyeball</h3>
+
+ <p>An Eyeball object has three subcomponents: the assumptions
+ against which the model is to be checked, the inspectors which do
+ the checking, and the renderer used to display the reports.</p>
+
+ <p>The assumptions are bundled into a single OntModel. Multiple
+ assumptions can be supplied either by adding them as sub-models
+ or by loading their content directly into the OntModel.</p>
+
+ <p>The inspectors are supplied as a single Inspector object. The
+ method <code>Inspector.Operations.create(List)</code> creates a
+ single Inspector from a list of Inspectors; this inspector
+ delegates all its inspection methods to all of its
+ sub-inspectors.</p>
+
+ <p>The renderer can be anything that implements the (simple)
+ renderer interface.</p>
+
+ <p>To create an Eyeball:</p>
+
+ <pre>Eyeball eyeball = new Eyeball( inspector, assumptions, renderer );
+</pre>
+
+ <h3><a name='toc-56'></a>to eyeball a model</h3>
+
+ <p>Models to be inspected are provided as OntModels. The problems
+ are delivered to a Report object, where they are represented as
+ an RDF model.</p>
+
+ <blockquote>
+ eyeball.inspect( report, ontModelToBeInspected )
+ </blockquote>
+
+ <p>The result is that same report object. The
+ <i>Report::model()</i> method delivers an RDF model which
+ describes the problems found by the inspection. The inspections
+ supplied in the distribution use the EYE vocabulary, and are used
+ in the standard reports:
+ </p>
+
+ <p>Every report item in the model is a blank node with
+ <code>rdf:type eye:Item</code>. See earlier sections for
+ the descriptions of the properties attached to an Item.
+ </p>
+
+ <h2><a name='toc-57'></a>rebuilding Eyeball</h2>
+
+ <p>
+ The provided ant script can be used to rebuild Eyeball from
+ source:
+ </p>
+
+ <pre>
+ant clean build jar
+</pre>
+
+ <p>(Omitting <code>clean</code> will do an incremental build, useful
+ for small changes.)
+ </p>
+
+ <p>
+ The libraries required by Eyeball are all in the <code>lib</code>
+ directory, including the necessary Jena jars.
+ </p>
+
+ <h2><a name='toc-58'></a>creating and configuring an inspector</h2>
+
+ <p>
+ To make a new inspector available to Eyeball, a new Inspector
+ class must be created and that class has to be described in
+ the Eyeball configuration.
+ </p>
+
+ <h3><a name='toc-59'></a>creating an Inspector</h3>
+
+ <p>
+ Any inspector must implement the Inspector interface,
+ which has four operations:
+ </p>
+
+ <ul>
+ <li><i>begin( Report r, OntModel assume )</i>:
+ Begin a new inspection. <code>r</code> is the <code>Report</code>
+ object which will accept the reports in this inpsection;
+ <code>assume</code> is the model containing the assumed
+ ontologies. <code>begin</code> is responsible for declaring
+ this inspectors <i>report properties</i>.
+ </li>
+ <li><i>inspectModel( Report r, OntModel m )</i>:
+ Do a whole-model inspection of <code>m</code>, issuing
+ reports to <code>r</code>.
+ </li>
+ <li><i>inspectStatement( Report r, Statement s )</i>:
+ Inspect the single statement <code>s</code>, issuing
+ reports to <code>r</code>.
+ </li>
+ <li><i>end( Report r )</i>:
+ Do any tidying-up reports required.
+ </li>
+ </ul>
+
+ <p>
+ Typically <code>end</code> and one of <code>inspectModel</code> or
+ <code>inspectStatement</code> do nothing.
+ </p>
+
+ <p>
+ An inspector must also have a constructor that takes a <code>Resource</code>
+ argument. When Eyeball creates the Inspector object, it passes the
+ <code>Resource</code> which is the root of this inspector's
+ configuration. (This is, for example, how the SPARQL-driven inspector
+ receives the query strings to use.)
+ </p>
+
+ <p>
+ Developers may find the class <code>InpsectorBase</code> useful; it
+ has empty implementations for all the <code>Inspector</code> methods.
+ They may also find <code>InspectorTestBase</code> useful when writing
+ their inspector's tests, both for its convenience methods and because
+ it requires that their class has the appropriate constructors.
+ </p>
+
+ <h3><a name='toc-60'></a>reports and report properties</h3>
+
+ <p>
+ Eyeball reports are statements in a report model. To let the
+ renderer know which property of a report is the "main" one,
+ and which order the other properties should appear in, the
+ inspector's <code>begin</code> method should declare the
+ properties:
+ </p>
+
+ <pre>
+r.declareProperty( EYE.badDatatypeURI );
+r.declareOrder( EYE.badLanguage, EYE.onLiteral );
+</pre>
+
+ <p>
+ <code>declareProperty(P)</code> announces that <code>P</code>
+ is a report property of this inspector. <code>declareOrder(F,S)</code>
+ says that both <code>F</code> and <code>S</code> are report properties,
+ and that <code>F</code> should appear before <code>S</code> in the
+ rendered report.
+ </p>
+
+ <p>
+ Reports are made up of <i>report items</i>, which are the subjects
+ of the report properties. To create a report item, use one of
+ <code>reportItem()</code> or <code>reportItem(S)</code>. The
+ second form is appropriate when the report is attached to some
+ statement <code>S</code> of the model being inspected; a report
+ renderer will attempt to display <code>S</code>.
+ </p>
+
+ <p>
+ To add the main property to a report item <code>R</code>, use
+ <code>R.addMainProperty(P,O)</code>; to add non-main properties,
+ use <code>R.addProperty(P,O)</code>.
+ </p>
+
+ <h3><a name='toc-61'></a>configuring an inspector</h3>
+
+ <p>
+ To add an inspector to a configuration file, choose a URI for
+ it (here we're using <code>my:Fresh</code> and assuming
+ a prefix declaration for <code>my:</code>) and a short name
+ (here, "fresh") and add a description to the configuration file:
+ </p>
+
+ <pre>
+my:Fresh a eye:Inspector
+ ; eye:shortName "fresh"
+ ; rdfs:label "fresh checks for my application"
+ ; eye:className "full.path.to.Fresh"
+ .
+</pre>
+
+ <p>
+ Replace <code>full.path.to.Fresh</code> with the full classname
+ of your inspector. Now you can use <code>Fresh</code> by adding
+ <i>-include fresh</i> to the Eyeball command line (and ensuring
+ that the class is on your classpath).
+ </p>
+
+ <p>
+ If you want <code>Fresh</code> to be included by default, then
+ you must add it as an <code>eye:inspector</code> property
+ of the configuration root, <i>eg</i>:
+ </p>
+
+ <pre>
+eye:eyeball a eye:Eyeball
+ ; eye:inspector
+ eye:PrefixInspector, # as delivered
+ <span style='background: white'>my:FreshInspector</span>, # new inspector
+ eye:URIInspector, # as delivered
+ ...
+</pre>
+
+ <p>
+ </p>
+
+
+</body>
+</html>
Added: jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-index.html
URL: http://svn.apache.org/viewvc/jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-index.html?rev=1398843&view=auto
==============================================================================
--- jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-index.html (added)
+++ jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-index.html Tue Oct 16 15:20:36 2012
@@ -0,0 +1,76 @@
+<html>
+<head>
+<title>Eyeball</title>
+<link type="text/css" rel="stylesheet" href="styles/doc.css">
+</head>
+<body>
+
+<h1>Eyeball: checking RDF/OWL for common problems</h1>
+
+Eyeball is a Jena contrib for checking RDF models (including OWL) for
+common problems. It is user-extensible using plugins. The available
+documentation for this Eyeball, E2.4, is:
+
+<ul>
+<li>This index and one-minute introduction.
+<li>The <a href="brief.html">brief guide</a>.
+<li>The <i>experimental</i> <a href="gui.html">Eyeball GUI</a>.
+<li>The full <a href="full.html">manual</a>.
+<li>The <a href="javadoc/index.html">javadoc</a>.
+</ul>
+
+You can download Eyeball from the
+<a href="http://sourceforge.net/project/showfiles.php?group_id=40417&package_id=148927">
+Eyeball package page</a>. Eyeball needs Java 5 or later to run.
+
+<h1>one-minute introduction</h1>
+
+<h2>installation</h2>
+
+<p>
+If you haven't already, download Eyeball from the
+<a href="http://sourceforge.net/project/showfiles.php?group_id=40417&package_id=148927">Eyeball package page</a>
+and unzip it into a directory of your choice.
+The download is rather large, because Eyeball 2.4 includes the Jena
+jars so that it runs stand-alone.
+
+<p>If you have Ant installed, run the Eyeball test suite:
+
+<blockquote>
+ant test
+</blockquote>
+
+<p>
+If it doesn't say that the tests passed, let us know via the jena-dev
+mailing list <i>jena-dev@groups.yahoo.com</i> (registration required)
+and we'll see what we can do to fix the problem.
+
+<p>Ensure all the jars in the Eyeball lib directory are on your classpath.
+(You might find <a href="classpath.text">this list</a> helpful.)
+
+<h2>trying it out</h2>
+
+<p>
+Pick one of your RDF files; we'll call it FOO for now. Run the command-line
+command:
+
+<blockquote>
+java jena.eyeball -check FOO
+</blockquote>
+
+<p>
+You will likely get a whole bunch
+of messages about your RDF. The messages are supposed to be self-explanatory,
+so you may be able to go ahead and fix some problems straight away. If you
+get a Java error about <b>NoClassDefFoundError</b>, you've forgotten to
+set the classpath up or use the <i>-cp myClassPath</i> option to Java.
+
+<p>(You may also want to try the experimental <a href="gui.html">Eyeball GUI</a>,
+but you'll still need to start it from the command line.)
+
+<p>
+If the messages aren't self-explanatory, or you want more details,
+you'll want to move on to the <a href="brief.html">brief guide</a>.
+
+</body>
+</html>