svn commit: r868289 - in /websites/staging/jena/trunk/content: ./ documentation/query/http-auth.html

[bu...@apache.org]

Author: buildbot
Date: Wed Jul  3 16:08:51 2013
New Revision: 868289

Log:
Staging update by buildbot for jena

Modified:
    websites/staging/jena/trunk/content/   (props changed)
    websites/staging/jena/trunk/content/documentation/query/http-auth.html

Propchange: websites/staging/jena/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Wed Jul  3 16:08:51 2013
@@ -1 +1 @@
-1499155
+1499455

Modified: websites/staging/jena/trunk/content/documentation/query/http-auth.html
==============================================================================
--- websites/staging/jena/trunk/content/documentation/query/http-auth.html (original)
+++ websites/staging/jena/trunk/content/documentation/query/http-auth.html Wed Jul  3 16:08:51 2013
@@ -169,31 +169,43 @@ any service.</p>
 credentials will not actually be submitted.</p>
 <h4 id="scopedauthenticator">ScopedAuthenticator</h4>
 <p>The <a href="http://jena.apache.org/documentation/javadoc/arq/org/apache/jena/atlas/web/auth/ScopedAuthenticator.html">scoped authenticator</a> is an authenticator which maps credentials to different service URIs.  This allows you to specify different credentials for different services 
-as appropriate.  Similarly to the simple authenticator this is not preemptive authentication so credentials are not set unless the service requests them.</p>
+as appropriate.  Similarly to the simple authenticator this is not preemptive authentication so credentials are not sent unless the service requests them.</p>
 <p>Scoping of credentials is not based on exact mapping of the request URI to credentials but rather on a longest match approach.  For example if you define credentials
 for <code>http://example.org</code> then these are used for any request that requires authentication under that URI e.g. <code>http://example.org/some/path</code>.  However if you
 had defined credentials for <code>http://example.org/some/path</code> then these would be used in favor of those for <code>http://example.org</code></p>
 <h4 id="serviceauthenticator">ServiceAuthenticator</h4>
 <p>The <a href="http://jena.apache.org/documentation/javadoc/arq/org/apache/jena/atlas/web/auth/ServiceAuthenticator.html">service authenticator</a> is an authenticator which uses information encoded in the ARQ context and basically provides access to the existing credential provision
-mechanisms provided for the <code>SERVICE</code> clause, see <a href="service.html">Basic Federated Query</a> for more information on this.</p>
+mechanisms provided for the <code>SERVICE</code> clause, see <a href="service.html">Basic Federated Query</a> for more information on configuration for this.</p>
 <h4 id="formsauthenticator">FormsAuthenticator</h4>
 <p>The <a href="http://jena.apache.org/documentation/javadoc/arq/org/apache/jena/atlas/web/auth/FormsAuthenticator.html">forms authenticator</a> is an authenticator usable with services that require form based logins and use cookies to verify login state.  This is intended for use with
 services that don't support HTTP's built-in authentication mechanisms for whatever reason.  One example of this are servers secured using Apache HTTP Server <a href="https://httpd.apache.org/docs/2.4/mod/mod_auth_form.html">mod_auth_form</a>.</p>
 <h4 id="preemptivebasicauthenticator">PreemptiveBasicAuthenticator</h4>
 <p>This <a href="http://jena.apache.org/documentation/javadoc/arq/org/apache/jena/atlas/web/auth/PreemptiveBasicAuthenticator.html">authenticator</a> is a decorator over another authenticator that enables preemptive basic authentication.  This is not enabled by default because it reduces security as it can
  result in sending credentials to servers that don't actually require them.</p>
+<h4 id="delegatingauthenticator">DelegatingAuthenticator</h4>
+<p>The <a href="http://jena.apache.org/documentation/javadoc/arq/org/apache/jena/atlas/web/auth/DelegatingAuthenticator.html">delegating authenticator</a> allows for mapping different authenticators to different services, this is useful when you need to mix and match the types of authentication needed.</p>
 <h2 id="applying-authentication">Applying Authentication</h2>
 <p>APIs that support authentication typically provide two methods for providing authenticators, a <code>setAuthentication(String username, char[] password)</code> method
 which merely configures a <code>SimpleAuthenticator</code>.  There will also be a <code>setAuthenticator(HttpAuthenticator authenticator)</code> method
 that allows you to configure an arbitrary authenticator.</p>
 <p>Authenticators applied this way will only be used for requests by that specific API.  APIs that currently support this are as follows:</p>
 <ul>
-<li>[QueryEngineHTTP][9] - This is the <code>QueryExecution</code> implementation returned by <code>QueryExecutionFactory.sparqlService()</code> calls</li>
-<li>[UpdateProcessRemoteBase][10] - This is the base class of <code>UpdateProcessor</code> implementations returned by <code>UpdateExecutionFactory.createRemote()</code> and <code>UpdateExecutionFactory.createRemoteForm()</code> calls</li>
-<li>[DatasetGraphAccessorHTTP][11] - This is the <code>DatasetGraphAccessor</code> implementation underlying remote dataset accessors.</li>
+<li><a href="http://jena.apache.org/documentation/javadoc/arq/com/hp/hpl/jena/sparql/engine/http/QueryEngineHTTP.html">QueryEngineHTTP</a> - This is the <code>QueryExecution</code> implementation returned by <code>QueryExecutionFactory.sparqlService()</code> calls</li>
+<li><a href="http://jena.apache.org/documentation/javadoc/arq/com/hp/hpl/jena/sparql/modify/UpdateProcessRemoteBase.html">UpdateProcessRemoteBase</a> - This is the base class of <code>UpdateProcessor</code> implementations returned by <code>UpdateExecutionFactory.createRemote()</code> and <code>UpdateExecutionFactory.createRemoteForm()</code> calls</li>
+<li><a href="http://jena.apache.org/documentation/javadoc/arq/org/apache/jena/web/DatasetGraphAccessorHTTP.html">DatasetGraphAccessorHTTP</a> - This is the <code>DatasetGraphAccessor</code> implementation underlying remote dataset accessors.</li>
 </ul>
 <p>From 2.10.2 onwards the relevant factory methods include overloads that allow providing a <code>HttpAuthenticator</code> at creation time which
 avoids the needs to cast and manually set the authenticator afterwards.</p>
+<h2 id="the-default-authenticator">The Default Authenticator</h2>
+<p>Since it may not always be possible/practical to configure authenticators on a per-request basis the API includes a means to specify a default authenticator
+that is used when no authenticator is explicitly specified.  This may be configured via the <code>setDefaultAuthenticator(HttpAuthenticator authenticator)</code>
+method of the <a href="http://jena.apache.org/documentation/javadoc/arq/org/apache/jena/riot/web/HttpOp.html">HttpOp</a> class.</p>
+<p>By default there is already a default authenticator configured which is the <code>ServiceAuthenticator</code> since this preserves behavioural 
+backwards compatibility with prior versions of ARQ.</p>
+<p>You can configure the default authenticator to whatever you need so even if you don't directly control the code
+that is making HTTP requests provided that it is using ARQs APIs to make these then authentication will
+still be applied.</p>
+<p>Note that the default authenticator may be disabled by setting it to <code>null</code>.</p>
   </div>
 
   <div id="footer">