Author: buildbot
Date: Wed Jul 3 00:01:50 2013
New Revision: 868200
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 00:01:50 2013
@@ -1 +1 @@
-1499150
+1499155
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 00:01:50 2013
@@ -162,17 +162,38 @@ HTTP authentication that also allows ARQ
<p>Authentication mechanisms are provided by <a
href="http://jena.apache.org/documentation/javadoc/arq/org/apache/jena/atlas/web/auth/HttpAuthenticator.html";>HttpAuthenticator</a>
implementations of which a number are provided built into ARQ.</p>
<p>This API provides the authenticator with access to the
<code>HttpClient</code>, <code>HttpContext</code> and target <code>URI</code>
of the request that is about to be carried out. This allows for authenticators
to add credentials to requests on a pre-request basis and to use different
mechanisms and credentials for different services.</p>
-<p>The following details the available implementations:</p>
<h4 id="simpleauthenticator">SimpleAuthenticator</h4>
<p>The <a
href="http://jena.apache.org/documentation/javadoc/arq/org/apache/jena/atlas/web/auth/SimpleAuthenticator.html";>simple
authenticator</a> is as the name suggests the simplest implementation. It
takes a single set of credentials which is applied to
any service.</p>
<p>Authentication however is not preemptive so unless the remote service sends
a HTTP challenge (401 Unauthorized or 407 Proxy Authorization Required) then
credentials will not actually be submitted.</p>
<h4 id="scopedauthenticator">ScopedAuthenticator</h4>
-<p>The [scoped authenticator][3] is an authenticator which maps credentials to
different service URIs. This allows you to specify different credentials for
different services
+<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>
<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></p>
+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>
+<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>
+<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>
+</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>
</div>
<div id="footer">
