diff --git a/src/site/apt/download.apt b/src/site/apt/download.apt index a1d7e39b7..71199bca3 100644 --- a/src/site/apt/download.apt +++ b/src/site/apt/download.apt @@ -36,13 +36,13 @@ HttpClient Downloads {{{http://www.apache.org/dist/httpcomponents/httpclient/RELEASE_NOTES.txt}Release Notes}} - {{{http://www.apache.org/licenses/LICENSE-2.0.html}License}} -Dependency management with Maven +{Dependency management with Maven} If you are using {{{http://maven.apache.org}Maven}} for your project, you can create a dependency in your {{{http://maven.apache.org/guides/introduction/introduction-to-the-pom.html}pom.xml}} by adding the following block to the dependency descriptor: -* HttpComponents Client +* {HttpComponents Client} ------------------------- @@ -53,7 +53,7 @@ Dependency management with Maven ------------------------- -* HttpComponents HttpMime +* {HttpComponents HttpMime} ------------------------- diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt index 1c7c6c7df..0ebee7290 100644 --- a/src/site/apt/index.apt +++ b/src/site/apt/index.apt @@ -45,13 +45,13 @@ HttpClient Overview service clients, or systems that leverage or extend the HTTP protocol for distributed communication. -Documentation +{Documentation} * HttpClient Tutorial ( {{{tutorial/html}HTML}} / {{{tutorial/pdf/httpclient-tutorial.pdf}PDF}} ) * Some examples of HttpClient in action can be found {{{examples.html}here}} -Features +{Features} * Standards based, pure Java, implementation of HTTP versions 1.0 and 1.1 @@ -93,7 +93,7 @@ Features * Source code is freely available under the Apache License. -Standards Compliance +{Standards Compliance} HttpClient strives to conform to the following specifications endorsed by the Internet Engineering Task Force (IETF) and the internet at large: diff --git a/src/site/apt/logging.apt b/src/site/apt/logging.apt index 18880e8bc..895bf765b 100644 --- a/src/site/apt/logging.apt +++ b/src/site/apt/logging.apt @@ -57,7 +57,7 @@ Logging Practices HttpClient performs three different kinds of logging: the standard context logging used within each class, HTTP header logging and full wire logging. -* Context Logging +* {Context Logging} Context logging contains information about the internal operation of HttpClient as it performs HTTP requests. Each class has its own log named according to the class's fully qualified name. @@ -66,24 +66,24 @@ Logging Practices it is possible to configure context logging for all classes using the single log named <<>>. -* Wire Logging +* {Wire Logging} The wire log is used to log all data transmitted to and from servers when executing HTTP requests. The wire log uses the {{{org.apache.http.wire}}} logging category. This log should only be enabled to debug problems, as it will produce an extremely large amount of log data. -* HTTP header Logging +* {HTTP header Logging} Because the content of HTTP requests is usually less important for debugging than the HTTP headers, the {{{org.apache.http.headers}}} logging category for capturing HTTP headers only. -* Configuration Examples +* {Configuration Examples} <<>> can delegate to a variety of loggers for processing the actual output. Below are configuration examples for <<>>, <<>> and <<>>. -** Commons Logging Examples +** {Commons Logging Examples} <<>> comes with a basic logger called <<>>. This logger writes all logged messages to <<>>. The following examples show how to configure @@ -126,7 +126,7 @@ Logging Practices -Dorg.apache.commons.logging.simplelog.log.org.apache.http.client=DEBUG -------------------------------------- -** Log4j Examples +** {Log4j Examples} The simplest way to configure <<>> is via a <<>> file. <<>> will automatically read and configure itself using a file named <<>> when @@ -194,7 +194,7 @@ log4j.logger.org.apache.http.client=DEBUG {{{http://logging.apache.org/log4j/docs/manual.html} http://logging.apache.org/log4j/docs/manual.html}}. -** java.util.logging Examples +** {java.util.logging Examples} Since JDK 1.4 there has been a package {{{http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/package-summary.html} @@ -236,7 +236,7 @@ java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter java.util.logging.ConsoleHandler.level = ALL org.apache.http.level = FINEST -org.apache.http.wire.level = ERROR +org.apache.http.wire.level = SEVERE -------------------------------------- * Enable full wire + context logging diff --git a/src/site/apt/ntlm.apt b/src/site/apt/ntlm.apt index af062a44c..ec27c0166 100644 --- a/src/site/apt/ntlm.apt +++ b/src/site/apt/ntlm.apt @@ -34,7 +34,7 @@ NTLM support in HttpClient out of the box and probably never will. The reasons for that are legal rather than technical. -* Background +* {Background} NTLM is a proprietary authentication scheme developed by Microsoft and optimized for Windows operating system. @@ -54,7 +54,7 @@ NTLM support in HttpClient commercial users of open-source NTLM implementations liable for the use of Microsoft intellectual property. -* Enabling NTLM support in HttpClient 4.x +* {Enabling NTLM support in HttpClient 4.x} The good news is HttpClient is fully NTLM capable right out of the box. HttpClient ships with the NTLM authentication scheme, which, if configured @@ -78,7 +78,7 @@ public interface NTLMEngine { } ---------------------------------------- -* Using Samba JCIFS as an NTLM engine +* {Using Samba JCIFS as an NTLM engine} Follow these instructions to build an NTLMEngine implementation using JCIFS library @@ -171,7 +171,7 @@ httpclient.getCredentialsProvider().setCredentials( * You are done. -* Why this code is not distributed with HttpClient +* {Why this code is not distributed with HttpClient} JCIFS is licensed under the Lesser General Public License (LGPL). This license is not compatible with the Apache Licenses under which all Apache Software is diff --git a/src/site/apt/primer.apt b/src/site/apt/primer.apt index 676e20020..2386db8d4 100644 --- a/src/site/apt/primer.apt +++ b/src/site/apt/primer.apt @@ -30,7 +30,7 @@ Client HTTP Programming Primer -* About +* {About} This document is intended for people who suddenly have to or want to implement an application that automates something usually done with a browser, @@ -52,7 +52,7 @@ Client HTTP Programming Primer It is merely a way for us to reduce the noise on the mailing list without just leaving the newbies out in the cold. -* Scenario +* {Scenario} Let's assume that you have some kind of repetitive, web-based task that you want to automate. Something like: @@ -71,7 +71,7 @@ Client HTTP Programming Primer into a sample application. So this document is all bla-bla, and you will have to work out the details - all the details - yourself. Such is life. -* Caveat +* {Caveat} This scenario describes a hobbyist usage of HTTP, in other words: <>. Web sites are designed for user interaction, not @@ -107,13 +107,13 @@ Client HTTP Programming Primer that the provider will not change without notice. -* Not a Browser +* {Not a Browser} HttpClient is not a browser. Here's the difference. <> -[images/browser.png] Browser +[images/browser.png] {Browser} The figure shows some of the components you will find in a browser. To the left, there is the user interface. The browser needs a rendering @@ -148,7 +148,7 @@ Client HTTP Programming Primer <> -[images/httpclient.png] HTTP Client +[images/httpclient.png] {HTTP Client} The figure shows some of the components you will find in a browser, and highlights the scope of HttpClient. The primary responsibility @@ -168,24 +168,24 @@ Client HTTP Programming Primer tolerance for flaws in server behavior, but there are limits to the deviations HttpClient can handle. -* Terminology +* {Terminology} This section introduces some important terms you have to know to understand the rest of this document. - <<>> + <<<{HTTP Message}>>> consists of a header section and an optional entity. There are two kinds of messages, requests and responses. They differ in the format of the first line, but both can have header fields and an optional entity. - <<>> + <<<{HTTP Request}>>> is sent from a client to a server. The first line includes the URI for which the request is sent, and a method that the server should execute for the client. - <<>> + <<<{HTTP Response}>>> is sent from a server to a client in response to a request. The first line includes a status code that tells about success or failure of @@ -193,13 +193,13 @@ Client HTTP Programming Primer and 404 for not found. Other protocols based on HTTP can define additional status codes. - <<>> + <<<{Method}>>> is an operation requested from the server. HTTP defines a set of operations, the most frequent being GET and POST. Other protocols based on HTTP can define additional methods. - <<
>> + <<<{Header Fields}>>> are name-value pairs, where both name and value are text. The name of a header field is not case sensitive. Multiple values can be assigned @@ -210,7 +210,7 @@ Client HTTP Programming Primer meant for exclusive use with either requests or responses, still others are meant for use only with an entity. - <<>> + <<<{Entity}>>> is data sent with an HTTP message. For example, a response can contain the page or image you are downloading as an entity, or a request can @@ -218,7 +218,7 @@ Client HTTP Programming Primer The entity of an HTTP message can have an arbitrary data format, which is usually specified as a MIME type in a header field. - <<>> + <<<{Session}>>> is a series of requests from a single source to a server. The server can keep session data, and needs to recognize the session to which @@ -229,7 +229,7 @@ Client HTTP Programming Primer that it is you and your session for which more results are requested, and not me and my session. That's because I searched for something else. - <<>> + <<<{Cookies}>>> are the preferred way for servers to track sessions. The server supplies a piece of data, called a cookie, in response to a request. The server @@ -239,9 +239,9 @@ Client HTTP Programming Primer which session a request belongs by looking at the cookie. If the cookie is missing from a request, the server will not respond as expected. -* Step by Step +* {Step by Step} -** GET the Login Page +** {GET the Login Page} Create and execute a GET request for the login page. Just use the link you would type into the browser as the URL. @@ -274,7 +274,7 @@ Client HTTP Programming Primer If you can't get the login page, get the home page instead now. Get the login page in the next step, when you establish the session. -** Establish the Session +** {Establish the Session} Create and execute another GET request for a page. You can simply request the login page again, or some other page @@ -358,7 +358,7 @@ Client HTTP Programming Primer instructions in step 5 for POST requests apply for GET requests as well. It's even simpler with GET, since you don't have an entity. -** Analyze the Form +** {Analyze the Form} Now it is time to analyze the form defined in the HTML markup of the page. A form in HTML is a set of name-value-pairs called parameters, where some @@ -369,9 +369,9 @@ Client HTTP Programming Primer Look for the
tag in the page source. There may be several forms in the page, but they can not be nested. Locate the form you want to submit. Locate the matching
tag. Everything in between the two may be - relevant. Let's start with the attributes of the
tag: + relevant. Let's start with the {attributes of the tag}: - <<>> + <<<{method}=>>> specifies the method used for submitting the form. If it is GET or not specified at all, then you need to create a GET request. The parameters @@ -380,7 +380,7 @@ Client HTTP Programming Primer of the request, also referred to as the request body. How to do that is discussed in step 5. - <<>> + <<<{action}=>>> specifies the URL to which the request has to be sent. Do not try to get this URL from the address bar of your browser! A browser will @@ -389,7 +389,7 @@ Client HTTP Programming Primer It is possible that the URL includes a query string that specifies some parameters. If so, keep that in mind. - <<>> + <<<{enctype}=>>> specifies the MIME type for the entity of the request generated by the form. The two common cases are url-encoded (default) and multipart-mime. @@ -398,7 +398,7 @@ Client HTTP Programming Primer This attribute is only used for the POST method. If the method is GET, the parameters will always be url-encoded, but not in an entity. - <<>> + <<<{accept-charset}=>>> specifies the character set that the browser should allow for user input. It will not be discussed here, but you will have to consider this value @@ -500,7 +500,7 @@ Client HTTP Programming Primer that behavior. -** Analyze the Form, Again +** {Analyze the Form, Again} After you have determined the action URL and name-value-pairs of a form, you should exit the program you used to get the HTML source, @@ -525,7 +525,7 @@ Client HTTP Programming Primer application accordingly. -** POST the Form +** {POST the Form} After analyzing the form, it is time to create a request that matches what a browser would generate. If the method is GET, just add the @@ -582,33 +582,33 @@ Client HTTP Programming Primer can not be set explicitly. Other header fields are used to indicate capabilities which a browser has, but your application probably has not. For these, the request from your application has to and should differ. - Here is a possibly incomplete list of headers that need special consideration: + Here is a possibly incomplete {list of headers that need special consideration}: - <<>> + <<<{Host}:>>> controlled by HttpClient. The value is usually obtained from the URL you are posting to. It is possible to set a different value, called a "virtual host". - <<>> + <<<{Content-Type}:>>> - <<>> + <<<{Content-Length}:>>> - <<>> + <<<{Transfer-Encoding}:>>> controlled by HttpClient. The values are obtained from the request entity. - <<>> + <<<{Connection}:>>> usually controlled by HttpClient to handle connection keep-alive. Leave it alone or set the value to "close". - <<>> + <<<{Content-Encoding}:>>> used to indicate the capability to process compressed responses. Do not set this, unless you are prepared to implement decompression. -** Follow Redirects +** {Follow Redirects} It is quite common for servers to respond with a 303 or 307 status code to a POST request. These redirects indicate that your application has to @@ -630,7 +630,7 @@ Client HTTP Programming Primer than two redirects in succession, something probably is fishy. -** Logout +** {Logout} Your application can send as many GET and POST requests and follow as many redirects as is required. But you should remember that there is a session @@ -640,7 +640,7 @@ Client HTTP Programming Primer server prevents multiple logins with the same user ID and your application has to run repeatedly, logout may even be required. -* Further Reading +* {Further Reading} ReferenceMaterials: a list of technical specifications for HTTP and related stuff.