svn commit: r1594839 - /jena/site/trunk/content/documentation/query/http-auth.mdtext

[rv...@apache.org]

Author: rvesse
Date: Thu May 15 09:48:45 2014
New Revision: 1594839

URL: http://svn.apache.org/r1594839
Log:
Further clarify forms authenticator documentation

Modified:
    jena/site/trunk/content/documentation/query/http-auth.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=1594839&r1=1594838&r2=1594839&view=diff
==============================================================================
--- jena/site/trunk/content/documentation/query/http-auth.mdtext (original)
+++ jena/site/trunk/content/documentation/query/http-auth.mdtext Thu May 15 09:48:45 2014
@@ -71,28 +71,34 @@ configuration for this.
 
 #### FormsAuthenticator
 
-The [forms authenticator][6] 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 [mod_auth_form][7].
+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 
+are servers secured using Apache HTTP Server [mod_auth_form][7].
 
 This is one of the more complex authenticators to configure because it requires you to know certain details of the form login mechanism of 
 the service you are authenticating against.  In the simplest case where a site is using Apache [mod_auth_form][7] in its default configuration you
-can do the following to configure an authenticator:
+merely need to know the URL to which login requests should be POSTed and your credentials.  Therefore you can do the following to configure 
+an authenticator:
 
     URI targetService = new URI("http://example.org/sparql");
     FormLogin formLogin = new ApacheModAuthFormLogin("http://example.org/login", "user", "password".toCharArray());
     FormsAuthenticator authenticator = new FormsAuthenticator(targetService, formLogin);
 
-However if the service is using a more complicated forms login setup you will need to know what the names of the form fields used to submit
-the username and password.  For example say we were authenticating to a service where the form fields were called **id** and **pwd** we'd
-need to configure our authenticator as follows:
+In the above example the service we want to authenticate against is `http://example.org/sparql` and it requires us to first login by POSTing
+our credentials to `http://example.org/login`.
+
+However if the service is using a more complicated forms login setup you will additionally need to know what the names of the form fields used 
+to submit the username and password.  For example say we were authenticating to a service where the form fields were called **id** and **pwd**
+we'd need to configure our authenticator as follows:
 
     URI targetService = new URI("http://example.org/sparql");
     FormLogin formLogin = new ApacheModAuthFormLogin("http://example.org/login", "id", "pwd", "user", "password".toCharArray());
     FormsAuthenticator authenticator = new FormsAuthenticator(targetService, formLogin);
 
 Note that you can also create a forms authenticator that uses different login forms for different services by creating a `Map<URI, FormLogin>`
-that maps each service to an associated form login and passing that to the `FormsAuthenticator` constructor
+that maps each service to an associated form login and passing that to the `FormsAuthenticator` constructor.
+
+Currently forms based login that require more than just a username and password are not supported.
 
 #### PreemptiveBasicAuthenticator