first HttpClient example, and a few @author changes

git-svn-id: https://svn.apache.org/repos/asf/jakarta/httpcomponents/httpclient/trunk@500781 13f79535-47bb-0310-9956-ffa450edef68

src/examples/org/apache/http/examples/client/ClientExecuteRequest.java

@@ -0,0 +1,190 @@
+/*
+ * $HeadURL$
+ * $Revision$
+ * $Date$
+ *
+ * ====================================================================
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ * ====================================================================
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals on behalf of the Apache Software Foundation.  For more
+ * information on the Apache Software Foundation, please see
+ * <http://www.apache.org/>.
+ *
+ */
+
+package org.apache.http.examples.client;
+
+
+import org.apache.http.HttpHost;
+import org.apache.http.Header;
+import org.apache.http.HttpRequest;
+import org.apache.http.HttpResponse;
+import org.apache.http.HttpVersion;
+import org.apache.http.message.BasicHttpRequest;
+import org.apache.http.params.HttpParams;
+import org.apache.http.params.HttpProtocolParams;
+import org.apache.http.impl.DefaultHttpParams;
+import org.apache.http.protocol.BasicHttpProcessor;
+import org.apache.http.protocol.RequestConnControl;
+import org.apache.http.protocol.RequestContent;
+import org.apache.http.protocol.RequestExpectContinue;
+import org.apache.http.protocol.RequestTargetHost;
+import org.apache.http.protocol.RequestUserAgent;
+
+import org.apache.http.conn.Scheme;
+import org.apache.http.conn.SocketFactory;
+import org.apache.http.conn.PlainSocketFactory;
+import org.apache.http.conn.ClientConnectionManager;
+import org.apache.http.conn.impl.ThreadSafeClientConnManager;
+import org.apache.http.client.HttpClient;
+import org.apache.http.client.impl.DefaultHttpClient;
+
+
+
+/**
+ * How to send a request using {@link HttpClient HttpClient}.
+ *
+ * @author <a href="mailto:rolandw at apache.org">Roland Weber</a>
+ *
+ *
+ * <!-- empty lines above to avoid 'svn diff' context problems -->
+ * @version $Revision$ $Date$
+ *
+ * @since 4.0
+ */
+public class ClientExecuteRequest {
+
+    /**
+     * The default parameters.
+     * Instantiated in {@link #setup setup}.
+     */
+    private static HttpParams defaultParameters = null;
+
+
+    /**
+     * Main entry point to this example.
+     *
+     * @param args      ignored
+     */
+    public final static void main(String[] args)
+        throws Exception {
+
+        final HttpHost target = new HttpHost("jakarta.apache.org", 80, "http");
+
+        setup(); // some general setup
+
+        HttpClient client = createHttpClient();
+
+        HttpRequest req = createRequest(target);
+
+        System.out.println("executing request to " + target);
+        try {
+            HttpResponse rsp = client.execute(target, req);
+
+            System.out.println("----------------------------------------");
+            System.out.println(rsp.getStatusLine());
+            Header[] headers = rsp.getAllHeaders();
+            for (int i=0; i<headers.length; i++) {
+                System.out.println(headers[i]);
+            }
+            System.out.println("----------------------------------------");
+
+            //@@@ there is no entity, so we can't call close() there
+            //@@@ there is no need to call close() either, since the
+            //@@@ connection will have been released immediately
+
+        } finally {
+            //@@@ any kind of cleanup that should be performed?
+        }
+    } // main
+
+
+    private final static HttpClient createHttpClient() {
+
+        ClientConnectionManager ccm =
+            new ThreadSafeClientConnManager(getParams());
+
+        DefaultHttpClient dhc =
+            new DefaultHttpClient(getParams(), ccm);
+
+        BasicHttpProcessor bhp = dhc.getProcessor();
+        // Required protocol interceptors
+        bhp.addInterceptor(new RequestContent());
+        bhp.addInterceptor(new RequestTargetHost());
+        // Recommended protocol interceptors
+        bhp.addInterceptor(new RequestConnControl());
+        bhp.addInterceptor(new RequestUserAgent());
+        bhp.addInterceptor(new RequestExpectContinue());
+
+        return dhc;
+    }
+
+
+    /**
+     * Performs general setup.
+     * This should be called only once.
+     */
+    private final static void setup() {
+
+        // Register the "http" protocol scheme, it is required
+        // by the default operator to look up socket factories.
+        SocketFactory sf = PlainSocketFactory.getSocketFactory();
+        Scheme.registerScheme("http", new Scheme("http", sf, 80));
+
+        // Prepare parameters.
+        // Since this example doesn't use the full core framework,
+        // only few parameters are actually required.
+        HttpParams params = new DefaultHttpParams();
+        HttpProtocolParams.setVersion(params, HttpVersion.HTTP_1_1);
+        HttpProtocolParams.setContentCharset(params, "UTF-8");
+        HttpProtocolParams.setUserAgent(params, "Jakarta-HttpClient/4.0");
+        HttpProtocolParams.setUseExpectContinue(params, true);
+        defaultParameters = params;
+
+    } // setup
+
+
+    private final static HttpParams getParams() {
+        return defaultParameters;
+    }
+
+
+    /**
+     * Creates a request to execute in this example.
+     * In a real application, request interceptors should be used
+     * to add the required headers.
+     *
+     * @param target    the target server for the request
+     *
+     * @return  a request without an entity
+     */
+    private final static HttpRequest createRequest(HttpHost target) {
+
+        HttpRequest req = new BasicHttpRequest
+            ("OPTIONS", "*", HttpVersion.HTTP_1_1);
+
+        req.addHeader("Host", target.getHostName());
+
+        return req;
+    }
+
+
+} // class ManagerConnectDirect
+

src/java/org/apache/http/client/ClientRequestDirector.java

@@ -60,7 +60,7 @@ import org.apache.http.conn.ManagedClientConnection;
  * <code>HttpMethodDirector</code> in HttpClient 3.
  * </p>
  *
- * @author <a href="mailto:rolandw@apache.org">Roland Weber</a>
+ * @author <a href="mailto:rolandw at apache.org">Roland Weber</a>
  *
  *
  * <!-- empty lines to avoid svn diff problems -->

src/java/org/apache/http/client/HttpClient.java

@@ -51,7 +51,7 @@ import org.apache.http.conn.ClientConnectionManager;
  * Thread safety of HTTP clients depends on the implementation
  * and configuration of the specific client.
  *
- * @author <a href="mailto:rolandw@apache.org">Roland Weber</a>
+ * @author <a href="mailto:rolandw at apache.org">Roland Weber</a>
  *
  *
  * <!-- empty lines to avoid svn diff problems -->

src/java/org/apache/http/client/RoutedRequest.java

@@ -38,7 +38,7 @@ import org.apache.http.conn.HostConfiguration;
 /**
  * A request with the route along which it should be sent.
  *
- * @author <a href="mailto:rolandw@apache.org">Roland Weber</a>
+ * @author <a href="mailto:rolandw at apache.org">Roland Weber</a>
  *
  *
  * <!-- empty lines to avoid svn diff problems -->

src/java/org/apache/http/client/impl/AbstractHttpClient.java

@@ -51,7 +51,7 @@ import org.apache.http.client.RoutedRequest;
 /**
  * Convenience base class for HTTP client implementations.
  *
- * @author <a href="mailto:rolandw@apache.org">Roland Weber</a>
+ * @author <a href="mailto:rolandw at apache.org">Roland Weber</a>
  *
  *
  * <!-- empty lines to avoid svn diff problems -->

src/java/org/apache/http/client/impl/DefaultClientRequestDirector.java

@@ -52,7 +52,7 @@ import org.apache.http.client.ClientRequestDirector;
  * <br/>
  * This class replaces the <code>HttpMethodDirector</code> in HttpClient 3.
  *
- * @author <a href="mailto:rolandw@apache.org">Roland Weber</a>
+ * @author <a href="mailto:rolandw at apache.org">Roland Weber</a>
  *
  *
  * <!-- empty lines to avoid svn diff problems -->

src/java/org/apache/http/client/impl/DefaultHttpClient.java

@@ -55,7 +55,7 @@ import org.apache.http.client.ClientRequestDirector;
  * <br/>
  * This class replaces <code>HttpClient</code> in HttpClient 3.
  *
- * @author <a href="mailto:rolandw@apache.org">Roland Weber</a>
+ * @author <a href="mailto:rolandw at apache.org">Roland Weber</a>
  *
  *
  * <!-- empty lines to avoid svn diff problems -->

src/java/org/apache/http/conn/ClientConnectionOperator.java

@@ -50,7 +50,7 @@ import org.apache.http.protocol.HttpContext;
  * sockets. Creating a tunnelled connection through a proxy, however,
  * is not within the scope of the operator.
  *
- * @author <a href="mailto:rolandw@apache.org">Roland Weber</a>
+ * @author <a href="mailto:rolandw at apache.org">Roland Weber</a>
  *
  *
  * <!-- empty lines to avoid svn diff problems -->

src/java/org/apache/http/conn/HostConfiguration.java

@@ -46,7 +46,7 @@ import org.apache.http.util.LangUtils;
  * Instances of this class are immutable.
  * Instances of derived classes should be immutable, too.
  * 
- * @author <a href="mailto:rolandw@apache.org">Roland Weber</a>
+ * @author <a href="mailto:rolandw at apache.org">Roland Weber</a>
  * @author <a href="mailto:becke@u.washington.edu">Michael Becke</a>
  * @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a>
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>

src/java/org/apache/http/conn/ManagedClientConnection.java

@@ -43,7 +43,7 @@ import org.apache.http.protocol.HttpContext;
  * A client-side connection with advanced connection logic.
  * Instances are typically obtained from a connection manager.
  *
- * @author <a href="mailto:rolandw@apache.org">Roland Weber</a>
+ * @author <a href="mailto:rolandw at apache.org">Roland Weber</a>
  *
  *
  * <!-- empty lines to avoid svn diff problems -->

src/java/org/apache/http/conn/OperatedClientConnection.java

@@ -47,7 +47,7 @@ import org.apache.http.params.HttpParams;
  * {@link ClientConnectionOperator operator}.
  *
  *
- * @author <a href="mailto:rolandw@apache.org">Roland Weber</a>
+ * @author <a href="mailto:rolandw at apache.org">Roland Weber</a>
  *
  *
  * <!-- empty lines to avoid svn diff problems -->

src/java/org/apache/http/conn/PlainSocketFactory.java

@@ -44,7 +44,7 @@ import org.apache.http.params.HttpParams;
  * This class just uses the {@link java.net.Socket socket} API
  * in Java 1.4 or greater.
  * 
- * @author <a href="mailto:rolandw@apache.org">Roland Weber</a>
+ * @author <a href="mailto:rolandw at apache.org">Roland Weber</a>
  * @author Michael Becke
  */
 public final class PlainSocketFactory implements SocketFactory {

src/java/org/apache/http/conn/SocketFactory.java

@@ -46,7 +46,7 @@ import org.apache.http.params.HttpParams;
  * and {@link java.lang.Object#hashCode() Object.hashCode()}
  * must be overridden for the correct operation of some connection managers.
  * 
- * @author <a href="mailto:rolandw@apache.org">Roland Weber</a>
+ * @author <a href="mailto:rolandw at apache.org">Roland Weber</a>
  * @author Michael Becke
  * @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a>
  */

src/java/org/apache/http/conn/impl/AbstractClientConnectionAdapter.java

@@ -53,7 +53,7 @@ import org.apache.http.conn.ManagedClientConnection;
  * are delegated to the wrapped connection if there is one, or
  * return a default value if there is none.
  *
- * @author <a href="mailto:rolandw@apache.org">Roland Weber</a>
+ * @author <a href="mailto:rolandw at apache.org">Roland Weber</a>
  *
  *
  * <!-- empty lines to avoid svn diff problems -->

src/java/org/apache/http/conn/impl/DefaultClientConnection.java

@@ -45,7 +45,7 @@ import org.apache.http.conn.OperatedClientConnection;
 /**
  * Default implementation of an operated client connection.
  *
- * @author <a href="mailto:rolandw@apache.org">Roland Weber</a>
+ * @author <a href="mailto:rolandw at apache.org">Roland Weber</a>
  *
  *
  * <!-- empty lines to avoid svn diff problems -->

src/java/org/apache/http/conn/impl/DefaultClientConnectionOperator.java

@@ -53,7 +53,7 @@ import org.apache.http.conn.ClientConnectionOperator;
  * It uses the {@link Scheme Scheme} class to look up
  * {@link SocketFactory SocketFactory} objects.
  *
- * @author <a href="mailto:rolandw@apache.org">Roland Weber</a>
+ * @author <a href="mailto:rolandw at apache.org">Roland Weber</a>
  *
  *
  * <!-- empty lines to avoid svn diff problems -->

src/java/org/apache/http/conn/impl/ThreadSafeClientConnManager.java

@@ -63,7 +63,7 @@ import org.apache.http.protocol.HttpContext;
  * in HttpClient 3. See there for original authors.
  * </p>
  *
- * @author <a href="mailto:rolandw@apache.org">Roland Weber</a>
+ * @author <a href="mailto:rolandw at apache.org">Roland Weber</a>
  * @author <a href="mailto:becke@u.washington.edu">Michael Becke</a>
  *
  *