jena-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r975173 - in /websites/staging/jena/trunk/content: ./ documentation/permissions/
Date Thu, 10 Dec 2015 09:51:32 GMT
Author: buildbot
Date: Thu Dec 10 09:51:32 2015
New Revision: 975173

Log:
Staging update by buildbot for jena

Modified:
    websites/staging/jena/trunk/content/   (props changed)
    websites/staging/jena/trunk/content/documentation/permissions/assembler.html
    websites/staging/jena/trunk/content/documentation/permissions/design.html
    websites/staging/jena/trunk/content/documentation/permissions/evaluator.html
    websites/staging/jena/trunk/content/documentation/permissions/example.html
    websites/staging/jena/trunk/content/documentation/permissions/index.html
    websites/staging/jena/trunk/content/documentation/permissions/migration2To3.html

Propchange: websites/staging/jena/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Thu Dec 10 09:51:32 2015
@@ -1 +1 @@
-1718960
+1719046

Modified: websites/staging/jena/trunk/content/documentation/permissions/assembler.html
==============================================================================
--- websites/staging/jena/trunk/content/documentation/permissions/assembler.html (original)
+++ websites/staging/jena/trunk/content/documentation/permissions/assembler.html Thu Dec 10 09:51:32 2015
@@ -19,7 +19,7 @@
     limitations under the License.
 -->
 
-  <title>Apache Jena - Jena Permissions - Assembler For a Secured Model</title>
+  <title>Apache Jena - Jena Permissions - Assembler for a Secured Model</title>
   <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
 
@@ -143,7 +143,7 @@
     <div class="row">
     <div class="col-md-12">
     <div id="breadcrumbs"></div>
-    <h1 class="title">Jena Permissions - Assembler For a Secured Model</h1>
+    <h1 class="title">Jena Permissions - Assembler for a Secured Model</h1>
   <style type="text/css">
 /* The following code is added by mdx_elementid.py
    It was originally lifted from http://subversion.apache.org/style/site.css */
@@ -155,28 +155,46 @@
   visibility: hidden;
 }
 h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
-<p>Jena Permissions provides a standard Jena assembler making it easy to use the <code>SecuredModel</code> in an Assembler based environment.  To use the permissions assembler the assembler file must contain the lines:</p>
+<p>Jena Permissions provides a standard Jena assembler making it easy to use the <code>SecuredModel</code> in an Assembler based environment. To use the permissions assembler the assembler file must contain the lines:</p>
 <div class="codehilite"><pre><span class="p">[]</span> <span class="n">ja</span><span class="p">:</span><span class="n">loadClass</span>    &quot;<span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">jena</span><span class="p">.</span><span class="n">permissions</span><span class="p">.</span><span class="n">SecuredAssembler</span>&quot; <span class="p">.</span>
  <span class="nb">sec</span><span class="p">:</span><span class="n">Model</span>       <span class="n">rdfs</span><span class="p">:</span><span class="n">subClassOf</span>  <span class="n">ja</span><span class="p">:</span><span class="n">NamedModel</span> <span class="p">.</span>
 </pre></div>
 
 
 <p>The secured assembler provides XXXXXXXXXXXx properties for the assembler files.</p>
-<p>Assuming we define</p>
+<p>Assuming we define:</p>
 <div class="codehilite"><pre> <span class="p">@</span><span class="n">prefix</span> <span class="nb">sec</span><span class="p">:</span>    <span class="o">&lt;</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">apache</span><span class="p">.</span><span class="n">org</span><span class="o">/</span><span class="n">jena</span><span class="o">/</span><span class="n">permissions</span><span class="o">/</span><span class="n">Assembler</span>#<span class="o">&gt;</span> <span class="p">.</span>
 </pre></div>
 
 
-<p>Then the following resources are defined</p>
-<p><code>sec:Model</code> - A secured model.  One against which the security evaluator is running access checks.  All sec:Model instances must have a ja:ModelName to identify it to the <code>SecurityEvaluator</code></p>
-<p><code>sec:Evaluator</code> -  An instance of <code>SecurityEvaluator</code>.</p>
+<p>Then the following resources are defined:</p>
+<ul>
+<li>
+<p><code>sec:Model</code> - A secured model. One against which the security evaluator is running access checks. All sec:Model instances must have a ja:ModelName to identify it to the <code>SecurityEvaluator</code></p>
+</li>
+<li>
+<p><code>sec:Evaluator</code> - An instance of <code>SecurityEvaluator</code>.</p>
+</li>
+</ul>
 <p>The following are properties are also defined:</p>
+<ul>
+<li>
 <p><code>sec:evaluatorFactory</code> - Identifies the class name of a factory class that implements a no-argument <code>getInstance()</code> method that returns an instance of <code>SecurityEvaluator</code>.</p>
+</li>
+<li>
 <p><code>sec:baseModel</code> - Identifies the ja:Model that is to have permissions applied to it.</p>
+</li>
+<li>
 <p><code>sec:evaluatorImpl</code> - Identifies an instance of <code>SecurityEvaluator</code>.</p>
+</li>
+<li>
 <p><code>sec:evaluatorClass</code> - Identifies a class that implements <code>SecurityEvaluator</code></p>
+</li>
+<li>
 <p><code>sec:args</code> - Identifies arguments to the sec:evaluatorClass constructor.</p>
-<p>The secured assembler provides two (2) mechanisms to create a secured graph.  The first is to use a <code>SecurityEvaluator</code> factory</p>
+</li>
+</ul>
+<p>The secured assembler provides two (2) mechanisms to create a secured graph. The first is to use a <code>SecurityEvaluator</code> factory.</p>
 <div class="codehilite"><pre><span class="n">my</span><span class="o">:</span><span class="n">securedModel</span> <span class="n">rdf</span><span class="o">:</span><span class="n">type</span> <span class="n">sec</span><span class="o">:</span><span class="n">Model</span> <span class="o">;</span>
     <span class="n">sec</span><span class="o">:</span><span class="n">baseModel</span> <span class="n">my</span><span class="o">:</span><span class="n">baseModel</span> <span class="o">;</span>
     <span class="n">ja</span><span class="o">:</span><span class="n">modelName</span> <span class="s2">&quot;https://example.org/securedBaseModel&quot;</span> <span class="o">;</span>
@@ -184,13 +202,13 @@ h2:hover > .headerlink, h3:hover > .head
 </pre></div>
 
 
-<p>In the above example static method <code>getInstance()</code> is called on the.evaluator.factory.class.name and the result is used as the SecurityEvaluator.  This is used to create a secured model (<code>my:securedModel</code>) that wraps the model  <code>my:baseModel</code> and identifies itself to the <code>SecurityEvaluator</code> with the URI <code>"https://example.org/securedBaseModel"</code>. </p>
+<p>In the above example static method <code>getInstance()</code> is called on the.evaluator.factory.class.name and the result is used as the SecurityEvaluator. This is used to create a secured model (<code>my:securedModel</code>) that wraps the model <code>my:baseModel</code> and identifies itself to the <code>SecurityEvaluator</code> with the URI <code>"https://example.org/securedBaseModel"</code>.</p>
 <p>The second mechanism is to use the <code>sec:Evaluator</code> method.</p>
 <div class="codehilite"><pre><span class="n">my</span><span class="o">:</span><span class="n">secEvaluator</span> <span class="n">rdf</span><span class="o">:</span><span class="n">type</span> <span class="n">sec</span><span class="o">:</span><span class="n">Evaluator</span> <span class="o">;</span>
-    <span class="n">sec</span><span class="o">:</span><span class="n">args</span> <span class="o">[</span>  
+    <span class="n">sec</span><span class="o">:</span><span class="n">args</span> <span class="o">[</span>
         <span class="n">rdf</span><span class="o">:</span><span class="n">_1</span> <span class="n">my</span><span class="o">:</span><span class="n">secInfoModel</span> <span class="o">;</span>
     <span class="o">]</span> <span class="o">;</span>
-    <span class="n">sec</span><span class="o">:</span><span class="n">evaluatorClass</span>    <span class="s2">&quot;your.implementation.SecurityEvaluator&quot;</span> 
+    <span class="n">sec</span><span class="o">:</span><span class="n">evaluatorClass</span>    <span class="s2">&quot;your.implementation.SecurityEvaluator&quot;</span>
 <span class="o">.</span>
 
 <span class="n">my</span><span class="o">:</span><span class="n">securedModel</span> <span class="n">rdf</span><span class="o">:</span><span class="n">type</span> <span class="n">sec</span><span class="o">:</span><span class="n">Model</span> <span class="o">;</span>
@@ -200,8 +218,8 @@ h2:hover > .headerlink, h3:hover > .head
 </pre></div>
 
 
-<p>In the above example <code>my:secEvaluator</code> is defined as a <code>sec:Evaluator</code> implemented by the class <code>"your.implementation.SecurityEvaluator"</code>.  When the instance is constructed the constructor with one (1) argument is used and it is passed <code>my:secInfoModel</code> as an argument.  <code>my:secInfoModel</code> may be any type supported by the assembler.  If more than one argument is desired then <code>rdf:_2</code>, <code>rdf:_3</code>, <code>rdf:_4</code>, etc. may be added to the <code>sec:args</code> list.  The  <code>"your.implementation.SecurityEvaluator"</code> with the proper number of arguments will be called.  It is an error to have more than one argument with the proper number of arguments.  </p>
-<p>After construction the value of <code>my:securedModel</code> is used to construct the <code>my:securedModel</code> instance.  This has the same properties as the previous example other than that the <code>SecurityEvaluator</code> instance is different.</p>
+<p>In the above example <code>my:secEvaluator</code> is defined as a <code>sec:Evaluator</code> implemented by the class <code>"your.implementation.SecurityEvaluator"</code>. When the instance is constructed the constructor with one argument is used and it is passed <code>my:secInfoModel</code> as an argument. <code>my:secInfoModel</code> may be any type supported by the assembler. If more than one argument is desired then <code>rdf:_2</code>, <code>rdf:_3</code>, <code>rdf:_4</code>, etc. may be added to the <code>sec:args</code> list. The <code>"your.implementation.SecurityEvaluator"</code> with the proper number of arguments will be called. It is an error to have more than one argument with the proper number of arguments.</p>
+<p>After construction the value of <code>my:securedModel</code> is used to construct the <code>my:securedModel</code> instance. This has the same properties as the previous example other than that the <code>SecurityEvaluator</code> instance is different.</p>
   </div>
 </div>
 

Modified: websites/staging/jena/trunk/content/documentation/permissions/design.html
==============================================================================
--- websites/staging/jena/trunk/content/documentation/permissions/design.html (original)
+++ websites/staging/jena/trunk/content/documentation/permissions/design.html Thu Dec 10 09:51:32 2015
@@ -155,54 +155,54 @@
   visibility: hidden;
 }
 h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
-<p>Jena-permissions is designed to allow integrators to implement almost any security policy.  Fundamentally it works by implementing dynamic proxies on top of the Jena Graph and Model interfaces as well as objects returned by those interfaces.  The proxy verifies that the actions on those objects are permitted by the policy before allowing the actions to proceed.</p>
-<p>The graph or model is created by the <code>org.apache.jena.permissions.Factory</code> object by wrapping a Graph or Model implementation and associating it with a URI (<code>graphIRI</code>) and a SecurityEvaluator implementation.  The <code>graphIRI</code> is the URI that will be used to identify the graph/model to the security evaluator.</p>
-<p>The SecurityEvaluator is an object implemented by the integrator to perform the necessary permission checks.  A discussion of the SecurityEvaluator implementation can be found in the <a href="evaluator.html">Security Evaluator</a> documentation.</p>
+<p>Jena Permissions is designed to allow integrators to implement almost any security policy. Fundamentally it works by implementing dynamic proxies on top of the Jena Graph and Model interfaces as well as objects returned by those interfaces. The proxy verifies that the actions on those objects are permitted by the policy before allowing the actions to proceed.</p>
+<p>The graph or model is created by the <code>org.apache.jena.permissions.Factory</code> object by wrapping a Graph or Model implementation and associating it with a URI (<code>graphIRI</code>) and a SecurityEvaluator implementation. The <code>graphIRI</code> is the URI that will be used to identify the graph/model to the security evaluator.</p>
+<p>The SecurityEvaluator is an object implemented by the integrator to perform the necessary permission checks. A discussion of the SecurityEvaluator implementation can be found in the <a href="evaluator.html">Security Evaluator</a> documentation.</p>
 <p>Access to methods in secured objects are determined by the CRUD (Create, Read, Update and Delete) permissions assigned to the user.</p>
 <p>The system is designed to allow shallow (graph/model level) or deep (triple/statement level) decisions.</p>
 <p>When a secured method is called the system performs the following checks in order:</p>
 <ul>
 <li>
-<p>Determines if the user has proper access to the underlying graph/model.  Generally the required permission is Update (for add or delete methods), or Read.</p>
+<p>Determines if the user has proper access to the underlying graph/model. Generally the required permission is Update (for add or delete methods), or Read.</p>
 </li>
 <li>
-<p>If the user has access to the graph/model determine if the user has permission to execute the method against <strong>all</strong> triples/statements in the graph/model.  This is performed by calling <code>SecurityEvaluator.evaluate(principal, action, graphIRI, Triple.ANY)</code>.  If the evaluator returns <code>true</code> then the action is permitted.  This is general case for shallow permission systems.  For deep permissions systems <code>false</code> may be returned.</p>
+<p>If the user has access to the graph/model determine if the user has permission to execute the method against <strong>all</strong> triples/statements in the graph/model. This is performed by calling <code>SecurityEvaluator.evaluate(principal, action, graphIRI, Triple.ANY)</code>. If the evaluator returns <code>true</code> then the action is permitted. This is general case for shallow permission systems. For deep permissions systems <code>false</code> may be returned.</p>
 </li>
 <li>
-<p>if the user does not have permission to execute the method against <strong>all</strong> triples/statements the <code>SecurityEvaluator.evaluate(principal, action, graphIRI, triple)</code> method is called with the specific triple (note special cases below).  If the evaluator returns <code>true</code> the action is permitted, otherwise a properly detailed PermissionDeniedException is thrown.</p>
+<p>if the user does not have permission to execute the method against <strong>all</strong> triples/statements the <code>SecurityEvaluator.evaluate(principal, action, graphIRI, triple)</code> method is called with the specific triple (note special cases below). If the evaluator returns <code>true</code> the action is permitted, otherwise a properly detailed PermissionDeniedException is thrown.</p>
 </li>
 </ul>
 <h1 id="special-cases">Special Cases<a class="headerlink" href="#special-cases" title="Permanent link">&para;</a></h1>
 <h2 id="securityevaluatorfuture">SecurityEvaluator.FUTURE<a class="headerlink" href="#securityevaluatorfuture" title="Permanent link">&para;</a></h2>
-<p>There are a couple of special cases where the Node/Resource is not known when the permission check is made.  An example is the creation of a RDF List object.  For example to create an empty list the following triple/statement must be constructed:</p>
+<p>There are a couple of special cases where the Node/Resource is not known when the permission check is made. An example is the creation of a RDF List object. For example to create an empty list the following triple/statement must be constructed:</p>
 <div class="codehilite"><pre><span class="n">_</span><span class="o">:</span><span class="n">b1</span> <span class="n">rdf</span><span class="o">:</span><span class="n">first</span> <span class="n">rdf</span><span class="o">:</span><span class="n">nil</span> <span class="o">.</span>
 </pre></div>
 
 
-<p>However, the permissions system can not know the value of <code>_:b1</code> until after the triple/statement is constructed and added to the graph/model.  To handle this situation the permissions system asks the evaluator to evaluate the triple: <code>(SecurityEvaluator.FUTURE, RDF.first, RDF.nill)</code>  Similar situations are found when adding to a list, creating reified statements, RDF alt objects, RDF sequences, or RDF anonymous resources of a specific type.</p>
+<p>However, the permissions system can not know the value of <code>_:b1</code> until after the triple/statement is constructed and added to the graph/model. To handle this situation the permissions system asks the evaluator to evaluate the triple: <code>(SecurityEvaluator.FUTURE, RDF.first, RDF.nill)</code> Similar situations are found when adding to a list, creating reified statements, RDF alt objects, RDF sequences, or RDF anonymous resources of a specific type.</p>
 <h2 id="securityevaluatorvariable">SecurityEvaluator.VARIABLE<a class="headerlink" href="#securityevaluatorvariable" title="Permanent link">&para;</a></h2>
-<p>The <code>Node.ANY</code> node is used to identify the case where any node may be returned.  Specifically it asks can the user perform the action on <strong>All</strong> the nodes in this position in the triple.  For example:</p>
+<p>The <code>Node.ANY</code> node is used to identify the case where any node may be returned. Specifically it asks if the user can perform the action on <strong>All</strong> the nodes in this position in the triple. For example:</p>
 <div class="codehilite"><pre> <span class="n">Node</span><span class="p">.</span><span class="n">ANY</span> <span class="n">RDF</span><span class="p">:</span><span class="n">type</span> <span class="n">FOAF</span><span class="p">:</span><span class="n">Person</span>
 </pre></div>
 
 
-<p>asks if the operation can be performed on all of the nodes of type FOAF:Person.</p>
-<p>The <code>SecurityEvaluator.VARIABLE</code> differs from <code>Node.ANY</code> in that the system is asking if there are any prohibitions not if the user may perform. Thus queries with the <code>VARIABLE</code> type node should return <code>true</code> where <code>ANY</code>
-returns <code>false</code>. In general this type is used in query evaluation to determine if triple level filtering of results must be performed.  Thus:</p>
+<p>Asks if the operation can be performed on all of the nodes of type FOAF:Person.</p>
+<p>The <code>SecurityEvaluator.VARIABLE</code> differs from <code>Node.ANY</code> in that the system is asking if there are any prohibitions, and not if the user may perform. Thus queries with the <code>VARIABLE</code> type node should return <code>true</code> where <code>ANY</code>
+returns <code>false</code>. In general this type is used in query evaluation to determine if triple level filtering of results must be performed. Thus:</p>
 <div class="codehilite"><pre> <span class="n">SecurityEvaluator</span><span class="p">.</span><span class="n">VARIABLE</span> <span class="n">RDF</span><span class="p">:</span><span class="n">type</span> <span class="n">FOAF</span><span class="p">:</span><span class="n">Person</span>
 </pre></div>
 
 
-<p>asks if there are any restrictions against the user performing the action against all triples of type FOAF:Person.  The assumption is that checking for restrictions may be a faster check than checking for all access.  Note that by returning <code>true</code> the permissions system will check each explicit triple for access permissions.  So if the system can not determine if there are access restrictions it is safe to return <code>true</code>.</p>
+<p>Asks if there are any restrictions against the user performing the action against all triples of type FOAF:Person. The assumption is that checking for restrictions may be a faster check than checking for all access. Note that by returning <code>true</code> the permissions system will check each explicit triple for access permissions. So if the system can not determine if there are access restrictions it is safe to return <code>true</code>.</p>
 <h1 id="objects-returned-from-secured-objects">Objects Returned from Secured Objects<a class="headerlink" href="#objects-returned-from-secured-objects" title="Permanent link">&para;</a></h1>
-<p>Models and Graphs often return objects from methods.  For example the <code>model.createStatement()</code> returns a <code>Statement</code> object.  That object holds a reference to the model and performs operations against the model (for example <code>Statement.changeLiteralObject()</code>).  Since permissions provides a dynamic wrapper around the base model to create the secured model, returning the model <code>Statement</code> would return an object that no longer has any permissions applied.  Therefore the permissions system creates a <code>SecuredStatement</code> that applies permission checks to all operations before calling the base <code>Statement</code> methods.</p>
+<p>Models and Graphs often return objects from methods. For example the <code>model.createStatement()</code> returns a <code>Statement</code> object. That object holds a reference to the model and performs operations against the model (for example <code>Statement.changeLiteralObject()</code>). Since permissions provides a dynamic wrapper around the base model to create the secured model, returning the model <code>Statement</code> would return an object that no longer has any permissions applied. Therefore the permissions system creates a <code>SecuredStatement</code> that applies permission checks to all operations before calling the base <code>Statement</code> methods.</p>
 <p>All secured objects return secured objects if those objects may read or alter the underlying graph/model.</p>
 <p>All secured objects are defined as interfaces and are returned as dynamic proxies.</p>
-<p>All secured objects have concrete implementations.  These implementations must remain concrete to ensure that we handle all cases where returned objects may alter the the underlying graph/model.</p>
+<p>All secured objects have concrete implementations. These implementations must remain concrete to ensure that we handle all cases where returned objects may alter the the underlying graph/model.</p>
 <h2 id="secured-listeners">Secured Listeners<a class="headerlink" href="#secured-listeners" title="Permanent link">&para;</a></h2>
-<p>Both the Graph and the Model interfaces provide a listener framework.  Listeners are attached to the graph/model and changes to the graph/model are reported to them.  In order to ensure that listeners do not leak information, the principal that was active when the listener was attached is preserved in a <code>CachedSecurityEvaluator</code> instance.  This security evaluator implementation, wraps the original implementation and retains the current user.  Thus when the listener performs the permission checks the original user is used not the current user.  This is why the SecurityEvaluator <strong>must</strong> use the <code>principal</code> parameters and not call <code>getPrinciapl()</code> directly during evaluation calls.</p>
+<p>Both the Graph and the Model interfaces provide a listener framework. Listeners are attached to the graph/model and changes to the graph/model are reported to them. In order to ensure that listeners do not leak information, the principal that was active when the listener was attached is preserved in a <code>CachedSecurityEvaluator</code> instance. This security evaluator implementation, wraps the original implementation and retains the current user. Thus when the listener performs the permission checks the original user is used not the current user. This is why the SecurityEvaluator <strong>must</strong> use the <code>principal</code> parameters and not call <code>getPrincipal()</code> directly during evaluation calls.</p>
 <h1 id="proxy-implementation">Proxy Implementation<a class="headerlink" href="#proxy-implementation" title="Permanent link">&para;</a></h1>
-<p>The proxy implementation is uses a reflection <code>InvocationHandler</code> strategy.  This strategy results in a proxy that implements all the interfaces of the original object.  The original object along with its <code>InvocationHandler</code> instance are kept together in an <code>ItemHolder</code> instance variable in the secured instance.  When the invoker is called it determines if the called method is on the secured interface or not.  If the method is on the secured interface the invocation handler method is called, otherwise the method on the base class is called.</p>
+<p>The proxy implementation uses a reflection <code>InvocationHandler</code> strategy. This strategy results in a proxy that implements all the interfaces of the original object. The original object along with its <code>InvocationHandler</code> instance are kept together in an <code>ItemHolder</code> instance variable in the secured instance. When the invoker is called it determines if the called method is on the secured interface or not. If the method is on the secured interface the invocation handler method is called, otherwise the method on the base class is called.</p>
   </div>
 </div>
 

Modified: websites/staging/jena/trunk/content/documentation/permissions/evaluator.html
==============================================================================
--- websites/staging/jena/trunk/content/documentation/permissions/evaluator.html (original)
+++ websites/staging/jena/trunk/content/documentation/permissions/evaluator.html Thu Dec 10 09:51:32 2015
@@ -156,24 +156,24 @@
 }
 h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
 <h2 id="overview">Overview<a class="headerlink" href="#overview" title="Permanent link">&para;</a></h2>
-<p>The SecurityEvaluator interface defines the access control operations. It provides the interface between the authentication (answers the question: "who are you?") and the authorization (answers the question: "what can you do?"), as such it provides access to the current principal (user).  The javadocs contain detailed requirements for implementations of the SecurityEvaluator interface, short notes are provided below.</p>
-<p><strong>NOTE</strong> The permissions system caches intermediate results and will only call the evaluator if the answer is not already in the cache.  There is little or advantage to implementing caching in the SecurityEvaluator itself.</p>
+<p>The SecurityEvaluator interface defines the access control operations. It provides the interface between the authentication (answers the question: "who are you?") and the authorization (answers the question: "what can you do?"), as such it provides access to the current principal (user). The javadocs contain detailed requirements for implementations of the SecurityEvaluator interface, short notes are provided below.</p>
+<p><strong>NOTE</strong> The permissions system caches intermediate results and will only call the evaluator if the answer is not already in the cache. There is little or no advantage to implementing caching in the SecurityEvaluator itself.</p>
 <h3 id="actions">Actions<a class="headerlink" href="#actions" title="Permanent link">&para;</a></h3>
-<p>Principals may perform Create, Read, Update or Delete operations on secured resources.  These operations are defined in the <code>Action</code> enum in the SecurtyEvaluator interface.</p>
+<p>Principals may perform Create, Read, Update or Delete operations on secured resources. These operations are defined in the <code>Action</code> enum in the SecurtyEvaluator interface.</p>
 <h3 id="node">Node<a class="headerlink" href="#node" title="Permanent link">&para;</a></h3>
 <p>The permission system uses the standard Node.ANY to represent a wild-card in a permission check and the standard <code>Triple.ANY</code> to represent a triple with wild-cards in each of the three positions: subject, predicate and object.</p>
-<p>The permission system introduces two (2) new node types <code>SecurityEvaluator.VARIABLE</code>, which represents a variable in a permissions query, and <code>SecurityEvaluator.FUTURE</code>, which represents an anonymous node that will be created in the future.</p>
+<p>The permission system introduces two new node types <code>SecurityEvaluator.VARIABLE</code>, which represents a variable in a permissions query, and <code>SecurityEvaluator.FUTURE</code>, which represents an anonymous node that will be created in the future.</p>
 <h3 id="evaluator-methods">Evaluator Methods<a class="headerlink" href="#evaluator-methods" title="Permanent link">&para;</a></h3>
-<p>The SecurityEvaluator connects the Jena permissions system with the authentication system used by the application.  The SecurityEvaluator must be able to query the authentication system, or its proxy, to determine who the "current user" is.  In this context the "current user" is the one making the request.  In certain instances (specifically when using listeners on secured graphs and models) the "current user" may not be the user identified by the authentication system at the time of the query. </p>
-<p>The SecurityEvaluator must implement the following methods.  Any of these methods may throw an <code>AuthenticationRequriedException</code> if there is no authenticated user. </p>
-<p>Most of these methods have a <code>principal</code> parameter.  The value of that parameter is guaranteed to be a value returned from an earlier calls to getPrincipal().  The <code>principal</code> parameter, not the "current user" as identified by <code>getPrincipal()</code>, should be used for the permissions evaluation.</p>
-<p>None of these methods should throw any of the PermissionDeniedException based exceptions.  That is handled in a different layer.</p>
-<p>See the <a href="../javadoc/permissions/org/apache/jena/permissions/SecurityEvaluator.html">SecurityEvaluator javadocs</a> for detailed implementation notes. </p>
+<p>The SecurityEvaluator connects the Jena permissions system with the authentication system used by the application. The SecurityEvaluator must be able to query the authentication system, or its proxy, to determine who the "current user" is. In this context the "current user" is the one making the request. In certain instances (specifically when using listeners on secured graphs and models) the "current user" may not be the user identified by the authentication system at the time of the query.</p>
+<p>The SecurityEvaluator must implement the following methods. Any of these methods may throw an <code>AuthenticationRequriedException</code> if there is no authenticated user.</p>
+<p>Most of these methods have a <code>principal</code> parameter. The value of that parameter is guaranteed to be a value returned from an earlier calls to getPrincipal(). The <code>principal</code> parameter, not the "current user" as identified by <code>getPrincipal()</code>, should be used for the permissions evaluation.</p>
+<p>None of these methods should throw any of the PermissionDeniedException based exceptions. That is handled in a different layer.</p>
+<p>See the <a href="../javadoc/permissions/org/apache/jena/permissions/SecurityEvaluator.html">SecurityEvaluator javadocs</a> for detailed implementation notes.</p>
 <div class="codehilite"><pre><span class="n">public</span> <span class="n">boolean</span> <span class="n">evaluate</span><span class="p">(</span> <span class="n">Object</span> <span class="n">principal</span><span class="p">,</span> <span class="n">Action</span> <span class="n">action</span><span class="p">,</span> <span class="n">Node</span> <span class="n">graphIRI</span> <span class="p">)</span> <span class="n">throws</span> <span class="n">AuthenticationRequiredException</span><span class="p">;</span>
 </pre></div>
 
 
-<p>Determine if the action is permitted on the graph.  </p>
+<p>Determine if the action is permitted on the graph.</p>
 <div class="codehilite"><pre><span class="n">public</span> <span class="n">boolean</span> <span class="n">evaluate</span><span class="p">(</span> <span class="n">Object</span> <span class="n">principal</span><span class="p">,</span> <span class="n">Action</span> <span class="n">action</span><span class="p">,</span> <span class="n">Node</span> <span class="n">graphIRI</span><span class="p">,</span> <span class="n">Triple</span> <span class="n">triple</span> <span class="p">)</span> <span class="n">throws</span> <span class="n">AuthenticationRequiredException</span><span class="p">;</span>
 </pre></div>
 
@@ -188,7 +188,7 @@ h2:hover > .headerlink, h3:hover > .head
 </pre></div>
 
 
-<p>Determine if all the actions are allowed on the triple within the graph.            </p>
+<p>Determine if all the actions are allowed on the triple within the graph.</p>
 <div class="codehilite"><pre><span class="n">public</span> <span class="n">boolean</span> <span class="n">evaluateAny</span><span class="p">(</span> <span class="n">Object</span> <span class="n">principal</span><span class="p">,</span> <span class="n">Set</span><span class="o">&lt;</span><span class="n">Action</span><span class="o">&gt;</span> <span class="n">actions</span><span class="p">,</span> <span class="n">Node</span> <span class="n">graphIRI</span> <span class="p">)</span> <span class="n">throws</span> <span class="n">AuthenticationRequiredException</span><span class="p">;</span>
 </pre></div>
 
@@ -203,17 +203,17 @@ h2:hover > .headerlink, h3:hover > .head
 </pre></div>
 
 
-<p>Determine if the user is allowed to update the "from" triple to the "to" triple.            </p>
+<p>Determine if the user is allowed to update the "from" triple to the "to" triple.</p>
 <div class="codehilite"><pre><span class="n">public</span> <span class="n">Object</span> <span class="n">getPrincipal</span><span class="p">()</span> <span class="n">throws</span> <span class="n">AuthenticationRequiredException</span><span class="p">;</span>
 </pre></div>
 
 
-<p>Returns the current principal or null if there is no current principal.    </p>
+<p>Return the current principal or null if there is no current principal.</p>
 <h2 id="sample-implementation">Sample Implementation<a class="headerlink" href="#sample-implementation" title="Permanent link">&para;</a></h2>
-<p>This sample is for a graph that contains a set of messages, access to the messages are limited to 
-principals that the messages are to or from.  Any triple that is not a message is not affected. This 
-implementation simply has a <code>setPrincipal(String name)</code> method.  A real implementation would request the  user principal or name from the authentication system.  This implementation also requires access to the underlying model to determine if the user has access, however, that is not a requirement of the SecurityEvaluator in general. Determining access from the information provided is an exercise for the implementer. </p>
-<p>Note that this implementation does not vary based on the graph being evaluated (graphIRI).  The <code>graphIRI</code> parameter is provided for implementations where such variance is desired. </p>
+<p>This sample is for a graph that contains a set of messages, access to the messages are limited to
+principals that the messages are to or from. Any triple that is not a message is not affected. This
+implementation simply has a <code>setPrincipal(String name)</code> method. A real implementation would request the user principal or name from the authentication system. This implementation also requires access to the underlying model to determine if the user has access, however, that is not a requirement of the SecurityEvaluator in general. Determining access from the information provided is an exercise for the implementer.</p>
+<p>Note that this implementation does not vary based on the graph being evaluated (graphIRI). The <code>graphIRI</code> parameter is provided for implementations where such variance is desired.</p>
 <p>See the example jar for another implementation example.</p>
 <!-- language: lang-java -->
 
@@ -226,7 +226,7 @@ implementation simply has a <code>setPri
     <span class="n">private</span> <span class="n">Property</span> <span class="n">pFrom</span> <span class="p">=</span> <span class="n">ResourceFactory</span><span class="p">.</span><span class="n">createProperty</span><span class="p">(</span> &quot;<span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">example</span><span class="p">.</span><span class="n">com</span><span class="o">/</span><span class="n">from</span>&quot; <span class="p">);</span>
 
     <span class="o">/**</span>
-     <span class="o">*</span> 
+     <span class="o">*</span>
      <span class="o">*</span> <span class="p">@</span><span class="n">param</span> <span class="n">model</span> <span class="n">The</span> <span class="n">graph</span> <span class="n">we</span> <span class="n">are</span> <span class="n">going</span> <span class="n">to</span> <span class="n">evaluate</span> <span class="n">against</span><span class="p">.</span>
      <span class="o">*/</span>
     <span class="n">public</span> <span class="n">ExampleEvaluator</span><span class="p">(</span> <span class="n">Model</span> <span class="n">model</span> <span class="p">)</span>
@@ -240,9 +240,9 @@ implementation simply has a <code>setPri
         <span class="k">return</span> <span class="n">true</span><span class="p">;</span>
     <span class="p">}</span>
 
-    <span class="o">//</span> <span class="n">not</span> <span class="n">that</span> <span class="n">in</span> <span class="n">this</span> <span class="n">implementation</span> <span class="n">all</span> <span class="n">permission</span> <span class="n">checks</span> <span class="n">flow</span> <span class="n">through</span> 
-    <span class="o">//</span> <span class="n">this</span> <span class="n">method</span><span class="p">.</span>  <span class="n">We</span> <span class="n">can</span> <span class="n">do</span> <span class="n">this</span> <span class="n">because</span> <span class="n">we</span> <span class="n">have</span> <span class="n">a</span> <span class="n">simple</span> <span class="n">permissions</span> 
-    <span class="o">//</span> <span class="n">requirement</span><span class="p">.</span>  <span class="n">A</span> <span class="n">more</span> <span class="nb">complex</span> <span class="n">set</span> <span class="n">of</span> <span class="n">permissions</span> <span class="n">requirement</span> <span class="n">would</span> 
+    <span class="o">//</span> <span class="n">not</span> <span class="n">that</span> <span class="n">in</span> <span class="n">this</span> <span class="n">implementation</span> <span class="n">all</span> <span class="n">permission</span> <span class="n">checks</span> <span class="n">flow</span> <span class="n">through</span>
+    <span class="o">//</span> <span class="n">this</span> <span class="n">method</span><span class="p">.</span> <span class="n">We</span> <span class="n">can</span> <span class="n">do</span> <span class="n">this</span> <span class="n">because</span> <span class="n">we</span> <span class="n">have</span> <span class="n">a</span> <span class="n">simple</span> <span class="n">permissions</span>
+    <span class="o">//</span> <span class="n">requirement</span><span class="p">.</span> <span class="n">A</span> <span class="n">more</span> <span class="nb">complex</span> <span class="n">set</span> <span class="n">of</span> <span class="n">permissions</span> <span class="n">requirement</span> <span class="n">would</span>
     <span class="o">//</span> <span class="n">require</span> <span class="n">a</span> <span class="n">different</span> <span class="n">strategy</span><span class="p">.</span>
     <span class="n">private</span> <span class="n">boolean</span> <span class="n">evaluate</span><span class="p">(</span> <span class="n">Object</span> <span class="n">principalObj</span><span class="p">,</span> <span class="n">Resource</span> <span class="n">r</span> <span class="p">)</span>
     <span class="p">{</span>
@@ -262,16 +262,16 @@ implementation simply has a <code>setPri
             <span class="k">return</span> <span class="n">r</span><span class="p">.</span><span class="n">hasProperty</span><span class="p">(</span> <span class="n">pTo</span><span class="p">,</span> <span class="n">principal</span><span class="p">.</span><span class="n">getName</span><span class="p">()</span> <span class="p">)</span> <span class="o">||</span>
                     <span class="n">r</span><span class="p">.</span><span class="n">hasProperty</span><span class="p">(</span> <span class="n">pFrom</span><span class="p">,</span> <span class="n">principal</span><span class="p">.</span><span class="n">getName</span><span class="p">());</span>
         <span class="p">}</span>
-        <span class="k">return</span> <span class="n">true</span><span class="p">;</span>    
+        <span class="k">return</span> <span class="n">true</span><span class="p">;</span>
     <span class="p">}</span>
 
     <span class="o">//</span> <span class="n">evaluate</span> <span class="n">a</span> <span class="n">node</span><span class="p">.</span>
     <span class="n">private</span> <span class="n">boolean</span> <span class="n">evaluate</span><span class="p">(</span> <span class="n">Object</span> <span class="n">principal</span><span class="p">,</span> <span class="n">Node</span> <span class="n">node</span> <span class="p">)</span>
     <span class="p">{</span>
         <span class="k">if</span> <span class="p">(</span><span class="n">node</span><span class="p">.</span><span class="n">equals</span><span class="p">(</span> <span class="n">Node</span><span class="p">.</span><span class="n">ANY</span> <span class="p">))</span> <span class="p">{</span>
-            <span class="o">//</span> <span class="n">all</span> <span class="n">wildcards</span> <span class="n">are</span> <span class="n">false</span><span class="p">.</span>  <span class="n">This</span> <span class="n">forces</span> <span class="n">each</span> <span class="n">triple</span>
+            <span class="o">//</span> <span class="n">all</span> <span class="n">wildcards</span> <span class="n">are</span> <span class="n">false</span><span class="p">.</span> <span class="n">This</span> <span class="n">forces</span> <span class="n">each</span> <span class="n">triple</span>
             <span class="o">//</span> <span class="n">to</span> <span class="n">be</span> <span class="n">explicitly</span> <span class="n">checked</span><span class="p">.</span>
-            <span class="k">return</span> <span class="n">false</span><span class="p">;</span>  
+            <span class="k">return</span> <span class="n">false</span><span class="p">;</span>
         <span class="p">}</span>
 
         <span class="o">//</span> <span class="k">if</span> <span class="n">the</span> <span class="n">node</span> <span class="n">is</span> <span class="n">a</span> <span class="n">URI</span> <span class="n">or</span> <span class="n">a</span> <span class="n">blank</span> <span class="n">node</span> <span class="n">evaluate</span> <span class="n">it</span> <span class="n">as</span> <span class="n">a</span> <span class="n">resource</span><span class="p">.</span>

Modified: websites/staging/jena/trunk/content/documentation/permissions/example.html
==============================================================================
--- websites/staging/jena/trunk/content/documentation/permissions/example.html (original)
+++ websites/staging/jena/trunk/content/documentation/permissions/example.html Thu Dec 10 09:51:32 2015
@@ -19,7 +19,7 @@
     limitations under the License.
 -->
 
-  <title>Apache Jena - Adding Jena-Permissions to Fuseki</title>
+  <title>Apache Jena - Adding Jena Permissions to Fuseki</title>
   <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
 
@@ -143,7 +143,7 @@
     <div class="row">
     <div class="col-md-12">
     <div id="breadcrumbs"></div>
-    <h1 class="title">Adding Jena-Permissions to Fuseki</h1>
+    <h1 class="title">Adding Jena Permissions to Fuseki</h1>
   <style type="text/css">
 /* The following code is added by mdx_elementid.py
    It was originally lifted from http://subversion.apache.org/style/site.css */
@@ -156,23 +156,23 @@
 }
 h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
 <h2 id="overview">Overview<a class="headerlink" href="#overview" title="Permanent link">&para;</a></h2>
-<p>The goal of this document is to add jena-permissions to a fuseki deployment to restrict access to graph data.  This example will take the jena-permission example application, deploy the data to a fuseki instance and add the jena-permission to achieve the same access restrictions that the example  application has.</p>
-<p>To do this you will need a Fuseki installation, the Permissions Packages and a SecurityEvaluator implementation.  For this example we will use the SecurityEvaluator from the Permissions-Examples.</p>
+<p>The goal of this document is to add Jena Permissions to a fuseki deployment to restrict access to graph data. This example will take the example application, deploy the data to a fuseki instance and add the Jena Permissions to achieve the same access restrictions that the example application has.</p>
+<p>To do this you will need a Fuseki installation, the Permissions Packages and a SecurityEvaluator implementation. For this example we will use the SecurityEvaluator from the permissions-example.</p>
 <h2 id="set-up">Set up<a class="headerlink" href="#set-up" title="Permanent link">&para;</a></h2>
-<p>This example uses Fuseki 2.3.0, Permissions 3.0.0 and Apache Commons Collections v4. </p>
-<p>Fuseki can be downloaded from: 
+<p>This example uses Fuseki 2.3.0, Permissions 3.0.0 and Apache Commons Collections v4.</p>
+<p>Fuseki can be downloaded from:
 [https://repository.apache.org/content/repositories/snapshots/org/apache/jena/apache-jena-fuseki/]</p>
-<p>Jena Permissions jars can be downloaded from: 
+<p>Jena Permissions jars can be downloaded from:
 [https://repository.apache.org/content/repositories/snapshots/org/apache/jena/jena-permissions/]</p>
 <ol>
 <li>
-<p>Download and unpack Fuseki.  The directory that you unpack Fuseki into will be referred to as the <code>Fuseki Home</code> directory for the remainder of this document.</p>
+<p>Download and unpack Fuseki. The directory that you unpack Fuseki into will be referred to as the <code>Fuseki Home</code> directory for the remainder of this document.</p>
 </li>
 <li>
 <p>Download permissions 3.0.0 jar and 3.0.0 permissions-example jar.</p>
 </li>
 <li>
-<p>Copy the permissions jar and the permissions-example jar into the Fuseki Home directory.  For the rest of this document the permissions jar will be referred to as <code>permissions.jar</code> and the permissions-example.jar as <code>example.jar</code></p>
+<p>Copy the permissions jar and the permissions-example jar into the Fuseki Home directory. For the rest of this document the permissions jar will be referred to as <code>permissions.jar</code> and the permissions-example.jar as <code>example.jar</code></p>
 </li>
 <li>
 <p>Download the Apache Commons Collections v4
@@ -183,7 +183,7 @@ Uncompress the <code>commons-collections
 <p>Add security jars to the startup script/batch file.</p>
 <ul>
 <li>
-<p>On *NIX edit fuseki-server script </p>
+<p>On *NIX edit fuseki-server script</p>
 <ol>
 <li>Comment out the line that reads <code>exec java  $JVM_ARGS -jar "$JAR" "$@"</code></li>
 <li>Uncomment the line that reads <code>\#\#   APPJAR=MyCode.jar</code></li>
@@ -205,11 +205,11 @@ Uncompress the <code>commons-collections
 <p>Run the fuseki-server script or batch file.</p>
 </li>
 <li>
-<p>Stop the server. </p>
+<p>Stop the server.</p>
 </li>
 <li>
 <p>Extract the example configuration into the newly created <code>Fuseki Home/run</code> directory.
-    From the example.jar archive: </p>
+    From the example.jar archive:</p>
 <ul>
 <li>extract <code>/org/apache/jena/permissions/example/example.ttl</code> into the <code>Fuseki Home/run</code> directory</li>
 <li>extract <code>/org/apache/jena/permissions/example/fuseki/config.ttl</code> into the <code>Fuseki Home/run</code> directory</li>
@@ -233,10 +233,10 @@ Uncompress the <code>commons-collections
 
 <p>The messages graph is defined in the <code>run/example.ttl</code> file.</p>
 <p>The <code>run/shiro.ini</code> file lists the users and their passwords and configures Fuseki to require authentication to access to the graphs.</p>
-<p>The <code>run/config.ttl</code> file adds the permissions to the graph as follows by applying the 
+<p>The <code>run/config.ttl</code> file adds the permissions to the graph as follows by applying the
 <code>org.apache.jena.permissions.example.ShiroExampleEvaluator</code> security evaluator to the message
 graph.</p>
-<p>Define all the prefixes </p>
+<p>Define all the prefixes.</p>
 <div class="codehilite"><pre><span class="p">@</span><span class="n">prefix</span> <span class="n">fuseki</span><span class="p">:</span>  <span class="o">&lt;</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">jena</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">org</span><span class="o">/</span><span class="n">fuseki</span>#<span class="o">&gt;</span> <span class="p">.</span>
 <span class="p">@</span><span class="n">prefix</span> <span class="n">tdb</span><span class="p">:</span>     <span class="o">&lt;</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">jena</span><span class="p">.</span><span class="n">hpl</span><span class="p">.</span><span class="n">hp</span><span class="p">.</span><span class="n">com</span><span class="o">/</span>2008<span class="o">/</span><span class="n">tdb</span>#<span class="o">&gt;</span> <span class="p">.</span>
 <span class="p">@</span><span class="n">prefix</span> <span class="n">rdf</span><span class="p">:</span>     <span class="o">&lt;</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">www</span><span class="p">.</span><span class="n">w3</span><span class="p">.</span><span class="n">org</span><span class="o">/</span>1999<span class="o">/</span>02<span class="o">/</span>22<span class="o">-</span><span class="n">rdf</span><span class="o">-</span><span class="n">syntax</span><span class="o">-</span><span class="n">ns</span>#<span class="o">&gt;</span> <span class="p">.</span>
@@ -255,12 +255,12 @@ graph.</p>
 
 <p>Define the base model that contains the unsecured data.</p>
 <div class="codehilite"><pre><span class="n">my</span><span class="o">:</span><span class="n">baseModel</span> <span class="n">rdf</span><span class="o">:</span><span class="n">type</span> <span class="n">ja</span><span class="o">:</span><span class="n">MemoryModel</span><span class="o">;</span>
-    <span class="n">ja</span><span class="o">:</span><span class="n">content</span> <span class="o">[</span><span class="n">ja</span><span class="o">:</span><span class="n">externalContent</span> <span class="o">&lt;</span><span class="n">file</span><span class="o">:./</span><span class="n">example</span><span class="o">.</span><span class="na">ttl</span><span class="o">&gt;]</span> 
+    <span class="n">ja</span><span class="o">:</span><span class="n">content</span> <span class="o">[</span><span class="n">ja</span><span class="o">:</span><span class="n">externalContent</span> <span class="o">&lt;</span><span class="n">file</span><span class="o">:./</span><span class="n">example</span><span class="o">.</span><span class="na">ttl</span><span class="o">&gt;]</span>
     <span class="o">.</span>
 </pre></div>
 
 
-<p>Define the secured model.  This is where permissions is applied to the my:baseModel to create a model that has permission restrictions.  Note that it is using the security evaluator implementation (sec:evaluatorImpl) called my:secEvaluator which we will define next.</p>
+<p>Define the secured model. This is where permissions is applied to the my:baseModel to create a model that has permission restrictions. Note that it is using the security evaluator implementation (sec:evaluatorImpl) called my:secEvaluator which we will define next.</p>
 <div class="codehilite"><pre><span class="n">my</span><span class="o">:</span><span class="n">securedModel</span> <span class="n">rdf</span><span class="o">:</span><span class="n">type</span> <span class="n">sec</span><span class="o">:</span><span class="n">Model</span> <span class="o">;</span>
     <span class="n">perm</span><span class="o">:</span><span class="n">baseModel</span> <span class="n">my</span><span class="o">:</span><span class="n">baseModel</span> <span class="o">;</span>
     <span class="n">ja</span><span class="o">:</span><span class="n">modelName</span> <span class="s2">&quot;https://example.org/securedModel&quot;</span> <span class="o">;</span>
@@ -268,9 +268,9 @@ graph.</p>
 </pre></div>
 
 
-<p>Define the security evaluator.  This is where we use the example ShiroExampleEvaluator.  For your production environment you will replace "org.apache.jena.security.example.ShiroExampleEvaluator"  with your SecurityEvaluator implementation.  Note that  ShiroExampleEvaluator constructor takes a Model argument.  We pass in the unsecured baseModel so that the evaluator can read it unencumbered.  Your implementation of SecurityEvaluator may have different parameters to meet your specific needs.</p>
+<p>Define the security evaluator. This is where we use the example ShiroExampleEvaluator. For your production environment you will replace "org.apache.jena.security.example.ShiroExampleEvaluator" with your SecurityEvaluator implementation. Note that ShiroExampleEvaluator constructor takes a Model argument. We pass in the unsecured baseModel so that the evaluator can read it unencumbered. Your implementation of SecurityEvaluator may have different parameters to meet your specific needs.</p>
 <div class="codehilite"><pre><span class="n">my</span><span class="o">:</span><span class="n">secEvaluator</span> <span class="n">rdf</span><span class="o">:</span><span class="n">type</span> <span class="n">perm</span><span class="o">:</span><span class="n">Evaluator</span> <span class="o">;</span>
-    <span class="n">perm</span><span class="o">:</span><span class="n">args</span> <span class="o">[</span>  
+    <span class="n">perm</span><span class="o">:</span><span class="n">args</span> <span class="o">[</span>
         <span class="n">rdf</span><span class="o">:</span><span class="n">_1</span> <span class="n">my</span><span class="o">:</span><span class="n">baseModel</span> <span class="o">;</span>
     <span class="o">]</span> <span class="o">;</span>
     <span class="n">perm</span><span class="o">:</span><span class="n">evaluatorClass</span> <span class="s2">&quot;org.apache.jena.permissions.example.ShiroExampleEvaluator&quot;</span> <span class="o">.</span>
@@ -291,7 +291,7 @@ graph.</p>
 </pre></div>
 
 
-<p>Define the service for the fuseki:Service.  Note that the fuseki:dataset served by this server is the secured dataset defined above.</p>
+<p>Define the service for the fuseki:Service. Note that the fuseki:dataset served by this server is the secured dataset defined above.</p>
 <div class="codehilite"><pre><span class="n">my</span><span class="o">:</span><span class="n">service1</span> <span class="n">rdf</span><span class="o">:</span><span class="n">type</span> <span class="n">fuseki</span><span class="o">:</span><span class="n">Service</span> <span class="o">;</span>
     <span class="n">rdfs</span><span class="o">:</span><span class="n">label</span>                        <span class="s2">&quot;My Secured Data Service&quot;</span> <span class="o">;</span>
     <span class="n">fuseki</span><span class="o">:</span><span class="n">name</span>                       <span class="s2">&quot;myAppFuseki&quot;</span> <span class="o">;</span>       <span class="err">#</span> <span class="n">http</span><span class="o">://</span><span class="n">host</span><span class="o">:</span><span class="n">port</span><span class="o">/</span><span class="n">myAppFuseki</span>

Modified: websites/staging/jena/trunk/content/documentation/permissions/index.html
==============================================================================
--- websites/staging/jena/trunk/content/documentation/permissions/index.html (original)
+++ websites/staging/jena/trunk/content/documentation/permissions/index.html Thu Dec 10 09:51:32 2015
@@ -155,25 +155,25 @@
   visibility: hidden;
 }
 h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
-<p>Jena-permissions is a SecurityEvaluator interface and a set of dynamic proxies that apply that interface to Jena Graphs, Models, and associated methods and classes.  It does not implement any specific security policy but provides a framework for developers or integrators to implement any desired policy.</p>
+<p>Jena Permissions is a SecurityEvaluator interface and a set of dynamic proxies that apply that interface to Jena Graphs, Models, and associated methods and classes. It does not implement any specific security policy but provides a framework for developers or integrators to implement any desired policy.</p>
 <h2 id="documentation">Documentation<a class="headerlink" href="#documentation" title="Permanent link">&para;</a></h2>
 <ul>
 <li><a href="index.html#overview">Overview</a></li>
 <li><a href="index.html#usage-notes">Usage Notes</a></li>
-<li><a href="design.html">Jena Permissions Design</a></li>
-<li><a href="evaluator.html">Security Evaluator</a></li>
-<li><a href="assembler.html">Assembler</a></li>
-<li><a href="example.html">Adding Jena-Permissions to Fuseki</a></li>
+<li><a href="design.html">Design</a></li>
+<li><a href="evaluator.html">Security Evaluator implementation</a></li>
+<li><a href="assembler.html">Assembler for a Secured Model</a></li>
+<li><a href="example.html">Adding Jena Permissions to Fuseki</a></li>
 </ul>
 <h2 id="overview">Overview<a class="headerlink" href="#overview" title="Permanent link">&para;</a></h2>
-<p>Jena-permissions transparently intercepts calls to the Graph or Model interface, evaluates access restrictions and either allows or rejects the access.  The system is authentication agnostic and will work with most authentication systems.  The system uses dynamic proxies to wrap any Graph or Model implementation.  The jena-permissions module includes an Assembler module to extend the standard Assembler to include the ability to create secured models and graphs.  A complete example application is also available.</p>
-<p>The developer using jena-permissions is required to implement a SecurityEvaluator that provides access to the Principal (User) using the system and also determines if that Principal has the proper access to execute a method.  Through the SecurityEvaluator the developer may apply full CRUD (Create, Read, Update, and Delete) restrictions to graphs and optionally triples within the graphs. </p>
+<p>Jena Permissions transparently intercepts calls to the Graph or Model interface, evaluates access restrictions and either allows or rejects the access. The system is authentication agnostic and will work with most authentication systems. The system uses dynamic proxies to wrap any Graph or Model implementation. The Jena Permissions module includes an Assembler module to extend the standard Assembler to include the ability to create secured models and graphs. A complete example application is also available.</p>
+<p>The developer using Jena Permissions is required to implement a SecurityEvaluator that provides access to the Principal (User) using the system and also determines if that Principal has the proper access to execute a method. Through the SecurityEvaluator the developer may apply full CRUD (Create, Read, Update, and Delete) restrictions to graphs and optionally triples within the graphs.</p>
 <p>The javadocs have additional annotations that specify what permissions at graph and triple levels are required for the user to execute the method.</p>
 <p>There is an example jar that contains configuration examples for both a stand alone application and a Fuseki configuration option.</p>
 <h2 id="usage-notes">Usage Notes<a class="headerlink" href="#usage-notes" title="Permanent link">&para;</a></h2>
 <p>When the system is correctly configured the developer creates a SecuredGraph by calling <code>Factory.getInstance( SecurityEvaluator, String, Graph );</code>. Once created the resulting graph automatically makes the appropriate calls to the SecurityEvaluator before passing any approved requests to the underlying graph.</p>
 <p>Secured models are created by calling <code>Factory.getInstance( SecurityEvaluator, String, Model );</code> or <code>ModelFactory.createModelForGraph( SecuredGraph );</code></p>
-<p><strong>NOTE:</strong> when creating a model by wrapping a secured graph (e.g. <code>ModelFactory.createModelForGraph( SecuredGraph );</code>) the resulting Model does not have the same security requirements that the standard secured model.  For example When creating a list on a secured model calling <code>model.createList( RDFNode[] );</code>, the standard secured model verifies that the user has the right to <strong>update</strong> the triples and allows or denies the entire operation accordingly. The wrapped secured graph does not have visibility to the <code>createList()</code> command and can only operate on the instructions issued by the <code>model.createList()</code> implementation. In the standard implementation the model requests the graph to delete one triple and then insert another. Thus the user must have <strong>delete</strong> and <strong>add</strong> permissions, not the <strong>update</strong> permission.</p>
+<p><strong>NOTE:</strong> when creating a model by wrapping a secured graph (e.g. <code>ModelFactory.createModelForGraph( SecuredGraph );</code>) the resulting Model does not have the same security requirements that the standard secured model. For example When creating a list on a secured model calling <code>model.createList( RDFNode[] );</code>, the standard secured model verifies that the user has the right to <strong>update</strong> the triples and allows or denies the entire operation accordingly. The wrapped secured graph does not have visibility to the <code>createList()</code> command and can only operate on the instructions issued by the <code>model.createList()</code> implementation. In the standard implementation the model requests the graph to delete one triple and then insert another. Thus the user must have <strong>delete</strong> and <strong>add</strong> permissions, not the <strong>update</strong> permission.</p>
 <p>There are several other cases where the difference in the layer can trip up the security system. In all known cases the result is a tighter security definition than was requested. For simplicity sake we recommend that the wrapped secured graph only be used in cases where access to the graph as a whole is granted/denied. In these cases the user either has all CRUD capabilities or none.</p>
   </div>
 </div>

Modified: websites/staging/jena/trunk/content/documentation/permissions/migration2To3.html
==============================================================================
--- websites/staging/jena/trunk/content/documentation/permissions/migration2To3.html (original)
+++ websites/staging/jena/trunk/content/documentation/permissions/migration2To3.html Thu Dec 10 09:51:32 2015
@@ -155,13 +155,13 @@
   visibility: hidden;
 }
 h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
-<p>When Jena moved from version 2 to version 3 there was a major renaming of packages.  One of the packages renamed was the Jena Permsissions package.  It was formerly named Jena Security. There are several changes that need to occur to migrate from jena-security version 2.x to jena-permissions version 3.x</p>
+<p>When Jena moved from version 2 to version 3 there was a major renaming of packages. One of the packages renamed was the Jena Permissions package. It was formerly named Jena Security. There are several changes that need to occur to migrate from jena-security version 2.x to jena-permissions version 3.x.</p>
 <h1 id="changes">Changes<a class="headerlink" href="#changes" title="Permanent link">&para;</a></h1>
 <h2 id="package-rename">Package Rename<a class="headerlink" href="#package-rename" title="Permanent link">&para;</a></h2>
 <p>There are two major changes to package names.</p>
 <ul>
 <li>
-<p>As with the rest of the Jena code all refrerences to <em>com.hp.hpl.jena</em> have been changed to <em>org.apache.jena</em>.  For integrator code this means that a simple rename of the includes is generally all that is required for this.  See the main Migration Notes page for other hints and tips regarding this change.</p>
+<p>As with the rest of the Jena code all references to <em>com.hp.hpl.jena</em> have been changed to <em>org.apache.jena</em>. For integrator code this means that a simple rename of the includes is generally all that is required for this. See the main Migration Notes page for other hints and tips regarding this change.</p>
 </li>
 <li>
 <p>Jena Security has been renamed Jena Permissions and the Maven <em>artifact id</em> has been changed to <em>jena-permissions</em> to reflect this change.</p>
@@ -171,38 +171,38 @@ h2:hover > .headerlink, h3:hover > .head
 </li>
 </ul>
 <h1 id="exceptions">Exceptions<a class="headerlink" href="#exceptions" title="Permanent link">&para;</a></h1>
-<p>Formerly jena-permissions uses a single exception to identify the access restriction violations.  With the tighter integration of permission concepts into the Jena core there are now 7 exceptions.  This change will probably not required modification to the SecurityEvaluator implementation but may require modification to classes that utilize the permissions based object.</p>
-<p>All exceptions are runtime exceptions and so do not have to be explicitly caught.  Java docs indicate which methods throw which exceptions.</p>
+<p>Formerly Jena Permissions uses a single exception to identify the access restriction violations. With the tighter integration of permission concepts into the Jena core there are now 7 exceptions. This change will probably not required modification to the SecurityEvaluator implementation but may require modification to classes that utilize the permissions based object.</p>
+<p>All exceptions are runtime exceptions and so do not have to be explicitly caught. Javadocs indicate which methods throw which exceptions.</p>
 <ul>
 <li>
-<p>Removal of org.apache.jena.permissions.AccessDeniedException.  This is replace by 5 individual exceptions.</p>
+<p>Removal of org.apache.jena.permissions.AccessDeniedException. This is replace by 5 individual exceptions.</p>
 </li>
 <li>
-<p>Addition of org.apache.jena.shared.OperationDeniedException.  This exception is a child of the <em>JenaException</em> and is the root of all operation denied states whether through process errors or through permissions violations.</p>
+<p>Addition of org.apache.jena.shared.OperationDeniedException. This exception is a child of the <em>JenaException</em> and is the root of all operation denied states whether through process errors or through permissions violations.</p>
 </li>
 <li>
-<p>Addition of org.apache.jena.shared.PermissionDeniedException.  This exception is a child of the <em>OperationDeniedException</em> and is the root of all operations denied through permission violations.  These can be because the object was staticly prohibited from performing an operation (e.g. a read-only graph) or due to the jena-permissions layer.</p>
+<p>Addition of org.apache.jena.shared.PermissionDeniedException. This exception is a child of the <em>OperationDeniedException</em> and is the root of all operations denied through permission violations. These can be because the object was staticly prohibited from performing an operation (e.g. a read-only graph) or due to the Jena Permissions layer.</p>
 </li>
 <li>
-<p>Addition of org.apache.jena.shared.AddDeniedException.  This exception is a child of <em>PermissionDeniedException</em> and used to indicate that an attempt was made to add to an unmodifiable object.  It may be thrown by read-only graphs or by the permission layer when a create restriction is violated.</p>
+<p>Addition of org.apache.jena.shared.AddDeniedException. This exception is a child of <em>PermissionDeniedException</em> and used to indicate that an attempt was made to add to an unmodifiable object. It may be thrown by read-only graphs or by the permission layer when a create restriction is violated.</p>
 </li>
 <li>
-<p>Addition of org.apache.jena.shared.DeleteDeniedException.  This exception is a child of <em>PermissionDeniedException</em> and used to indicate that an attempt was made to delete from an unmodifiable object.  It may be thrown by read-only graphs or by the permission layer when a delete restriction is violated.</p>
+<p>Addition of org.apache.jena.shared.DeleteDeniedException. This exception is a child of <em>PermissionDeniedException</em> and used to indicate that an attempt was made to delete from an unmodifiable object. It may be thrown by read-only graphs or by the permission layer when a delete restriction is violated.</p>
 </li>
 <li>
-<p>Addition of org.apache.jena.shared.ReadDeniedException.  This exception is a child of <em>PermissionDeniedException</em> and used to indicate that a read restriction was violated.  </p>
+<p>Addition of org.apache.jena.shared.ReadDeniedException. This exception is a child of <em>PermissionDeniedException</em> and used to indicate that a read restriction was violated.</p>
 </li>
 <li>
-<p>Addition of org.apache.jena.shared.UpdateDeniedException.  This exception is a child of <em>PermissionDeniedException</em> and used to indicate that a update restriction was violated.  </p>
+<p>Addition of org.apache.jena.shared.UpdateDeniedException. This exception is a child of <em>PermissionDeniedException</em> and used to indicate that a update restriction was violated.</p>
 </li>
 <li>
-<p>Addition of org.apache.jena.shared.AuthenticationRequiredException.  This exception is a child of <em>OperationDeniedException</em> and used to indicate that user authentication is required but has not occurred.  This exception should be thrown when the SecurityEvaluator attempts to evaluate an operation and there is both a permissions restriction and the object returned by getPrincipal() indicates that the user is unauthenticated.</p>
+<p>Addition of org.apache.jena.shared.AuthenticationRequiredException. This exception is a child of <em>OperationDeniedException</em> and used to indicate that user authentication is required but has not occurred. This exception should be thrown when the SecurityEvaluator attempts to evaluate an operation and there is both a permissions restriction and the object returned by getPrincipal() indicates that the user is unauthenticated.</p>
 </li>
 </ul>
 <h1 id="removal-of-classes">Removal of Classes<a class="headerlink" href="#removal-of-classes" title="Permanent link">&para;</a></h1>
-<p>The original "security" code was intended to be graph agnostic and so injected a "shim" layer to convert from graph specific classes to security specific classes.  With the renaming of the package to "permissions" and the tighter integration to the Jena core the "shim" structure has been removed.  This should make the permissions layer faster and cleaner to implement.   </p>
+<p>The original "security" code was intended to be graph agnostic and so injected a "shim" layer to convert from graph specific classes to security specific classes. With the renaming of the package to "permissions" and the tighter integration to the Jena core the "shim" structure has been removed. This should make the permissions layer faster and cleaner to implement.</p>
 <h2 id="secnode">SecNode<a class="headerlink" href="#secnode" title="Permanent link">&para;</a></h2>
-<p>The SecNode class has been removed.  This was effectively a proxy for the Jena Node object and has been replaced with that object.  The SecNode maintained its type (e.g. URI, Literal or Variable) using an internal Enumeration.  The method getType() was used to identify the internal type.  With the Jena node replacement statements of the form</p>
+<p>The SecNode class has been removed. This was effectively a proxy for the Jena Node object and has been replaced with that object. The SecNode maintained its type (e.g. URI, Literal or Variable) using an internal Enumeration. The method getType() was used to identify the internal type. With the Jena node replacement statements of the form</p>
 <div class="codehilite"><pre> <span class="k">if</span> <span class="p">(</span><span class="n">secNode</span><span class="p">.</span><span class="n">getType</span><span class="p">().</span><span class="n">equals</span><span class="p">(</span> <span class="n">SecNode</span><span class="p">.</span><span class="n">Type</span><span class="p">.</span><span class="n">Literal</span> <span class="p">))</span>
  <span class="p">{</span>
      <span class="o">//</span> <span class="n">do</span> <span class="n">something</span>
@@ -210,7 +210,7 @@ h2:hover > .headerlink, h3:hover > .head
 </pre></div>
 
 
-<p>are replaced with </p>
+<p>are replaced with</p>
 <div class="codehilite"><pre> <span class="k">if</span> <span class="p">(</span><span class="n">node</span><span class="p">.</span><span class="n">isLiteral</span><span class="p">())</span>
  <span class="p">{</span>
      <span class="o">//</span> <span class="n">do</span> <span class="n">something</span>
@@ -222,13 +222,13 @@ h2:hover > .headerlink, h3:hover > .head
 <p><code>SecNode.FUTURE</code> has been replaced with <code>SecurityEvaluator.FUTURE</code> and is now implemented as a blank node with the label <code>urn:jena-permissions:FUTURE</code>.</p>
 <p><code>SecNode.VARIABLE</code> has been replaced with <code>SecurityEvaluator.VARIABLE</code> and is now implemented as a blank node with the label <code>urn:jena-permissions:VARIABLE</code>.</p>
 <h2 id="sectriple">SecTriple<a class="headerlink" href="#sectriple" title="Permanent link">&para;</a></h2>
-<p>The SecTriple class has been removed.  This was effectively a proxy for the Jena Triple object and has been replaced with that object.</p>
+<p>The SecTriple class has been removed. This was effectively a proxy for the Jena Triple object and has been replaced with that object.</p>
 <h1 id="movement-of-classes">Movement of Classes<a class="headerlink" href="#movement-of-classes" title="Permanent link">&para;</a></h1>
 <h2 id="secureditem">SecuredItem<a class="headerlink" href="#secureditem" title="Permanent link">&para;</a></h2>
-<p>The SecuredItem interface was moved from org.apache.jena.permissions.impl to org.apache.jena.</p>
+<p>The SecuredItem interface was moved from org.apache.jena.permissions.impl to org.apache.jena.permissions.</p>
 <h1 id="additional-methods">Additional Methods<a class="headerlink" href="#additional-methods" title="Permanent link">&para;</a></h1>
 <h2 id="securityevaluator">SecurityEvaluator<a class="headerlink" href="#securityevaluator" title="Permanent link">&para;</a></h2>
-<p>The method <code>isAuthenticatedUser( Object principal )</code> has been added.  The SecurityEvaluator should respond <code>true</code> if the principal is recognized as an authenticated user.  The <code>principal</code> object is guaranteed to have been returend from an earlier <code>getPrincipal()</code> call.</p>
+<p>The method <code>isAuthenticatedUser( Object principal )</code> has been added. The SecurityEvaluator should respond <code>true</code> if the principal is recognized as an authenticated user. The <code>principal</code> object is guaranteed to have been returned from an earlier <code>getPrincipal()</code> call.</p>
   </div>
 </div>
 



Mime
View raw message