On Nov 8, 2016, at 11:53 AM, [email protected] wrote:
Author: ajs6f
Date: Tue Nov 8 16:53:48 2016
New Revision: 1768736
URL: http://svn.apache.org/viewvc?rev=1768736&view=rev
Log:
Updates for HTTP behavior in Jena 3.1.1
Modified:
jena/site/trunk/content/documentation/query/http-auth.mdtext
jena/site/trunk/content/documentation/query/service.mdtext
Modified: jena/site/trunk/content/documentation/query/http-auth.mdtext
URL:
http://svn.apache.org/viewvc/jena/site/trunk/content/documentation/query/http-auth.mdtext?rev=1768736&r1=1768735&r2=1768736&view=diff
==============================================================================
--- jena/site/trunk/content/documentation/query/http-auth.mdtext (original)
+++ jena/site/trunk/content/documentation/query/http-auth.mdtext Tue Nov 8
16:53:48 2016
@@ -16,10 +16,12 @@ Notice: Licensed to the Apache Softwa
specific language governing permissions and limitations
under the License.
-As of ARQ 2.11.0 there is a new unified HTTP operation framework that provides
a uniform mechanism for
-HTTP authentication that also allows ARQ to support a broader range of
authentication mechanisms than were previously possible.
+From ARQ 2.11.0 through ARQ 3.1.0 there is a Jena-specific unified HTTP
operation framework that provides a uniform mechanism for
+HTTP authentication that also allows ARQ to support a broader range of
authentication mechanisms than were previously possible. After ARQ 3.1.0, Jena
exposes the underlying HTTP Commons functionality to the same end. This
documentation is therefore devided into two sections. The first explains the
older Jena-specific functionality, and the second explains how to use HTTP
Commons code to the same ends.
-## Applying Authentication
+## HTTP Authentication before ARQ 3.1.0
+
+### Applying Authentication
APIs that support authentication typically provide two methods for providing
authenticators, a `setAuthentication(String username, char[] password)` method
which merely configures a `SimpleAuthenticator`. There will also be a
`setAuthenticator(HttpAuthenticator authenticator)` method
@@ -41,14 +43,14 @@ avoids the needs to cast and manually se
...
}
-### Authenticators
+#### Authenticators
Authentication mechanisms are provided by [HttpAuthenticator][1]
implementations of which a number are provided built into ARQ.
This API provides the authenticator with access to the `HttpClient`,
`HttpContext` and target `URI` of the request that is about to be carried
out. This allows for authenticators to add credentials to requests on a
per-request basis and/or to use different mechanisms and credentials for
different services.
-#### SimpleAuthenticator
+##### SimpleAuthenticator
The [simple authenticator][2] is as the name suggests the simplest
implementation. It takes a single set of credentials which is applied to
any service.
@@ -56,7 +58,7 @@ any service.
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.
-#### ScopedAuthenticator
+##### ScopedAuthenticator
The [scoped authenticator][3] 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
@@ -67,13 +69,13 @@ if you define credentialsfor `http://exa
e.g. `http://example.org/some/path`. However if you had also defined
credentials for `http://example.org/some/path` then these would be
used in favor of those for `http://example.org`
-#### ServiceAuthenticator
+##### ServiceAuthenticator
The [service authenticator][4] is an authenticator which uses information
encoded in the ARQ context and basically provides access to the
existing credential provision mechanisms provided for the `SERVICE` clause, see
[Basic Federated Query][5] for more information on
configuration for this.
-#### FormsAuthenticator
+##### FormsAuthenticator
The [forms authenticator][6] is an authenticator usable with services that
require form based logins and use session 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
@@ -104,7 +106,7 @@ that maps each service to an associated
Currently forms based login that require more than just a username and password
are not supported.
-#### PreemptiveBasicAuthenticator
+##### PreemptiveBasicAuthenticator
This [authenticator][8] is a decorator over another authenticator that enables
preemptive basic authentication, this **only** works for servers
that support basic authentication and so will cause authentication failures
when any other authentication scheme is required. You should **only**
@@ -121,20 +123,12 @@ Also be aware that basic authentication
many servers will use more secure schemes like Digest authentication which
**cannot** be done preemptively as they require more complex
challenge response sequences.
-#### DelegatingAuthenticator
+##### DelegatingAuthenticator
The [delegating authenticator][12] allows for mapping different authenticators
to different services, this is useful when you need to mix and
match the types of authentication needed.
-### Debugging Authentication
-
-ARQ uses [Apache Http Client][14] for all its HTTP operations and this
provides detailed logging information that can be used for debugging. To
-see this information you need to configure your logging framework to set the
`org.apache.http` package to either `DEBUG` or `TRACE` level.
-
-The `DEBUG` level will give you general diagnostic information about requests
and responses while the `TRACE` level will give you detailed
-HTTP traces i.e. allow you to see the exact HTTP requests and responses which
can be extremely useful for debugging authentication problems.
-
-### The Default Authenticator
+#### The Default Authenticator
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
@@ -148,6 +142,82 @@ provided that it is using ARQs APIs to m
Note that the default authenticator may be disabled by setting it to `null`.
+## HTTP Authentication after ARQ 3.1.0
+
+### Applying Authentication
+
+APIs that support authentication typically provide methods for providing an
[HttpClient] for use with the given instance of that API class. `HttpClient` is
[extremely flexible][16] and can handle most scenarios very well. 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 client that is used when no
other client is explicitly specified. This may be configured via the
+`setDefaultHttpClient(HttpClient httpClient)` method of the [HttpOp][13]
class. This allows for static-scoped configuration of HTTP behavior.
+
+#### Examples of authentication
+
+This section includes a series of examples showing how to use HTTP Commons
classes to perform authenticated work. Most of them take advantage of
`HttpOp.setDefaultHttpClient` as described above.
+
+##### Simple authentication using username and password
+
+First we build an authenticating client:
+
+ CredentialsProvider credsProvider = new BasicCredentialsProvider();
+ Credentials credentials = new UsernamePasswordCredentials("user",
"passwd");
+ credsProvider.setCredentials(AuthScope.ANY, credentials);
+ HttpClient httpclient = HttpClients.custom()
+ .setDefaultCredentialsProvider(credsProvider)
+ .build();
+ HttpOp.setDefaultHttpClient(httpclient);
+
+Notice that we gave no scope for use with the credentials (`AuthScope.ANY`).
We can make further use of that parameter if we want to assign a scope for some
credentials:
+
+ CredentialsProvider credsProvider = new BasicCredentialsProvider();
+ Credentials unscopedCredentials = new UsernamePasswordCredentials("user",
"passwd");
+ credsProvider.setCredentials(AuthScope.ANY, unscopedCredentials);
+ Credentials scopedCredentials = new UsernamePasswordCredentials("user",
"passwd");
+ final String host = "http://example.com/sparql";;
+ final int port = 80;
+ final String realm = "aRealm";
+ final String schemeName = "DIGEST";
+ AuthScope authscope = new AuthScope(host, port, realm, schemeName);
+ credsProvider.setCredentials(authscope, scopedCredentials);
+ HttpClient httpclient = HttpClients.custom()
+ .setDefaultCredentialsProvider(credsProvider)
+ .build();
+ HttpOp.setDefaultHttpClient(httpclient);
+
+##### Authenticating via a form
+
+For this case we introduce an [HttpClientContext][17], which we can use to
retrieve the cookie we get from logging into a form. We then use the cookie to
authenticate elsewhere.
+
+ // we'll use this context to maintain our HTTP "conversation"
+ HttpClientContext httpContext = new HttpClientContext();
+
+ // first we use a method on HttpOp to log in and get our cookie
+ Params params = new Params();
+ params.addParam("username", "Bob Wu");
+ params.addParam("password", "my password");
+ HttpOp.execHttpPostForm("http://example.com/loginform";, params , null,
null, null, httpContext);
+
+ // now our cookie is stored in httpContext
+ CookieStore cookieStore = httpContext.getCookieStore();
+
+ // lastly we build a client that uses that cookie
+ HttpClient httpclient = HttpClients.custom()
+ .setDefaultCookieStore(cookieStore)
+ .build();
+ HttpOp.setDefaultHttpClient(httpclient);
+
+## Other concerns
+
+### Debugging Authentication
+
+ARQ uses [Apache Http Client][14] for all its HTTP operations and this
provides detailed logging information that can be used for debugging. To
+see this information you need to configure your logging framework to set the
`org.apache.http` package to either `DEBUG` or `TRACE` level.
+
+The `DEBUG` level will give you general diagnostic information about requests
and responses while the `TRACE` level will give you detailed
+HTTP traces i.e. allow you to see the exact HTTP requests and responses which
can be extremely useful for debugging authentication problems.
+
+### Authenticating to a SPARQL federated service
+
+ARQ allows the user to configure HTTP behavior to use on a per-`SERVICE`
basis, including authentication behavior such as is described above. This works
via the ARQ context. See [Basic Federated Query][5] for more information on
configuring this functionality.
+
[1]:
http://jena.apache.org/documentation/javadoc/arq/org/apache/jena/atlas/web/auth/HttpAuthenticator.html
[2]:
http://jena.apache.org/documentation/javadoc/arq/org/apache/jena/atlas/web/auth/SimpleAuthenticator.html
[3]:
http://jena.apache.org/documentation/javadoc/arq/org/apache/jena/atlas/web/auth/ScopedAuthenticator.html
@@ -161,4 +231,7 @@ Note that the default authenticator may
[11]:
http://jena.apache.org/documentation/javadoc/arq/org/apache/jena/web/DatasetGraphAccessorHTTP.html
[12]:
http://jena.apache.org/documentation/javadoc/arq/org/apache/jena/atlas/web/auth/DelegatingAuthenticator.html
[13]:
http://jena.apache.org/documentation/javadoc/arq/org/apache/jena/riot/web/HttpOp.html
- [14]: http://hc.apache.org
\ No newline at end of file
+ [14]: http://hc.apache.org
+ [15]:
https://hc.apache.org/httpcomponents-client-ga/httpclient/apidocs/org/apache/http/client/HttpClient.html
+ [16]: https://hc.apache.org/httpcomponents-client-ga/examples.html
+ [17]:
https://hc.apache.org/httpcomponents-client-ga/httpclient/apidocs/org/apache/http/client/protocol/HttpClientContext.html
\ No newline at end of file
Modified: jena/site/trunk/content/documentation/query/service.mdtext
URL:
http://svn.apache.org/viewvc/jena/site/trunk/content/documentation/query/service.mdtext?rev=1768736&r1=1768735&r2=1768736&view=diff
==============================================================================
--- jena/site/trunk/content/documentation/query/service.mdtext (original)
+++ jena/site/trunk/content/documentation/query/service.mdtext Tue Nov 8
16:53:48 2016
@@ -48,19 +48,18 @@ distributed query evaluation. The algebr
without regard to how selective the pattern is. So the order of the
query will affect the speed of execution. Because it involves HTTP
operations, asking the query in the right order matters a lot.
-Don't ask for the whole of a bookstore just to find book whose
+Don't ask for the whole of a bookstore just to find a book whose
title comes from a local RDF file - ask the bookshop a query with
the title already bound from earlier in the query.
## Controlling `SERVICE` requests.
-The `SERVICE` operation in a SPARQL query may be configured via the Context.
-The values for configuration can be set in the global context (accessed via
+The `SERVICE` operation in a SPARQL query may be configured via the Context.
The values for configuration can be set in the global context (accessed via
`ARQ.getContext()`) or in the per-query execution context.
The prefix `srv:` is the IRI `<http://jena.hpl.hp.com/Service#>`.
-### Summary
+### Configuration for ARQ through version 3.1.0
Symbol | Usage
------ | -----
@@ -71,7 +70,7 @@ Symbol | Usage
`srv:queryAuthPwd` | Basic authentication
`srv:queryContext` | Per-endpoint configuration
-### `srv:queryTimeout`
+#### `srv:queryTimeout`
Set the connect and read timeouts for the query.
@@ -86,21 +85,21 @@ read timout = 0
Values of 0 indicate no timeout and service operation will wait until the
remote server responds.
-### `srv:queryGzip`
+#### `srv:queryGzip`
Sets the allow Gzip flag.
Boolean: True indicates that gzip compressed data is acceptable.
false
-### `srv:queryDeflate`
+#### `srv:queryDeflate`
Sets the allow Deflate flag.
Boolean: True indicates that deflate compression is acceptable
False
-### `srv:queryAuthUser`
+#### `srv:queryAuthUser`
Sets the user id for basic auth.
@@ -108,7 +107,7 @@ String: The user id to log in with
If null or null length no user id is sent.
-### `srv:queryAuthPwd`
+#### `srv:queryAuthPwd`
Sets the password for basic auth.
@@ -116,13 +115,43 @@ String: The password to log in with.
If null or null length no password is sent.
-### srv:serviceContext
+#### `srv:serviceContext`
Provides a mechanism to override system context settings on a per URI basis.
The value is a `Map<String,Context>` where the map key is the URI of the
service endpoint, and the `Context` is a set of values to override the default values.
If a context is provided for the URI the system context is copied and the URI
specific values are then copied in. This ensures that any URI specific
settings will be used.
+### Configuration for ARQ after version 3.1.0
+Symbol | Usage | Default
+------ | ----- | -------
+`srv:queryTimeout` | Set timeouts | none
+`srv:queryCompression` | Enable use of deflation and GZip | true
+`srv:queryClient` | Enable use of a specific client | none
+`srv:queryContext` | Per-endpoint configuration | none
+
+#### `srv:queryTimeout`
+
+As documented above.
+
+
+#### `srv:queryCompression`
+
+Sets the flag for use of deflation and GZip.
+
+Boolean: True indicates that gzip compressed data is acceptable.
+
+#### `srv:queryClient`
+
+Enable use of a specific client
+
+Provides a slot for a specific [HttpClient][1] for use with a specific
`SERVICE`
+
+#### `srv:serviceContext`
+
+As documented above.
[ARQ documentation index](index.html)
+
+[1]:
https://hc.apache.org/httpcomponents-client-ga/httpclient/apidocs/org/apache/http/client/HttpClient.html
