new connection interfaces, step 4 - first example, plus a debug contrib

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

build.xml

@@ -412,14 +412,19 @@ Output
           </packageset>
 
           <group title="API">
+            <package name="org.apache.http.auth" />
             <package name="org.apache.http.conn" />
-            <package name="org.apache.http.conn*" />
+            <package name="org.apache.http.conn.params" />
+            <package name="org.apache.http.conn.ssl" />
             <package name="org.apache.http.cookie" />
             <package name="org.apache.http.cookie.params" />
             <package name="org.apache.httpclient" />
           </group>
           <group title="Implementation">
-            <package name="*.impl.*" />
+            <package name="org.apache.http.auth.impl*" />
+            <package name="org.apache.http.conn.impl*" />
+            <package name="org.apache.http.cookie.impl*" />
+            <package name="org.apache.httpclient.impl*" />
           </group>
     
           <classpath refid="classpath.client.javadoc"/>
@@ -445,25 +450,40 @@ Output
         >
           <packageset dir="${comp.client.src}">
             <include name="org/apache/http/**" />
+            <include name="org/apache/httpclient/**" />
           </packageset>
           <packageset dir="${comp.client.xmpls}">
             <include name="org/apache/http/**" />
+            <include name="org/apache/httpclient/**" />
           </packageset>
           <packageset dir="${comp.client.contr}">
             <include name="org/apache/http/**" />
           </packageset>
 
+
           <group title="API">
-            <package name="org.apache.http.client" />
+            <package name="org.apache.http.auth" />
+            <package name="org.apache.http.conn" />
+            <package name="org.apache.http.conn.params" />
+            <package name="org.apache.http.conn.ssl" />
+            <package name="org.apache.http.cookie" />
+            <package name="org.apache.http.cookie.params" />
+            <package name="org.apache.httpclient" />
           </group>
           <group title="Implementation">
-            <package name="org.apache.http.client.impl*" />
+            <package name="org.apache.http.auth.impl*" />
+            <package name="org.apache.http.conn.impl*" />
+            <package name="org.apache.http.cookie.impl*" />
+            <package name="org.apache.httpclient.impl*" />
           </group>
+
           <group title="Examples">
             <package name="org.apache.http.examples*" />
+            <package name="org.apache.httpclient.examples*" />
           </group>
           <group title="Contributions (unsupported)">
-            <package name="org.apache.http.client.contrib*" />
+            <package name="org.apache.http.contrib*" />
+            <package name="org.apache.httpclient.contrib*" />
           </group>
     
           <classpath refid="classpath.client.javadoc"/>

src/contrib/org/apache/http/contrib/conn/TalkativeSocketFactory.java

@@ -0,0 +1,335 @@
+/*
+ * $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.contrib.conn;
+
+
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.io.PrintStream;
+import java.io.IOException;
+import java.io.FilterInputStream;
+import java.io.FilterOutputStream;
+import java.net.Socket;
+import java.net.InetAddress;
+
+import org.apache.http.params.HttpParams;
+import org.apache.http.conn.SocketFactory;
+import org.apache.http.conn.PlainSocketFactory;
+
+
+/**
+ * A factory for sockets that debug-print the transmitted data.
+ *
+ * @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 TalkativeSocketFactory implements SocketFactory {
+
+    /** Where to print the debug output to. */
+    private final PrintStream debugStream;
+
+
+    /**
+     * Creates a new talkative socket factory.
+     *
+     * @param ps        where to print the debug output to
+     */
+    public TalkativeSocketFactory(PrintStream ps) {
+
+        if (ps == null) {
+            throw new IllegalArgumentException
+                ("Print stream must not be null.");
+        }
+        debugStream = ps;
+    }
+
+
+    /**
+     * Creates a new talkative socket.
+     *
+     * @return  the talkative socket
+     */
+    public Socket createSocket() {
+
+        return new TalkativeSocket();
+    }
+
+
+    // non-javadoc, see interface org.apache.http.conn.SocketFactory
+    public Socket connectSocket(Socket sock, String host, int port, 
+                                InetAddress localAddress, int localPort,
+                                HttpParams params)
+        throws IOException {
+
+        // just delegate the call to the default
+        return PlainSocketFactory.getSocketFactory().connectSocket
+            (sock, host, port, localAddress, localPort, params);
+    }
+
+
+    /**
+     * Prepares a byte for debug printing.
+     *
+     * @param sb        the string buffer to append to
+     * @param data      the byte to append. For consistency with
+     *                  java.io streams, the byte is passed as int.
+     */
+    public final static void appendByte(StringBuffer sb, int data) {
+
+        if (data < 32) {
+            switch (data) {
+            case 10: sb.append("[\\n]"); break;
+            case 13: sb.append("[\\r]"); break;
+            default: sb.append("[0x")
+                         .append(Integer.toHexString(data)).append("]");
+            }
+        } else if (data > 127) {
+            sb.append("[0x")
+                .append(Integer.toHexString(data)).append("]");
+        } else {
+            sb.append((char) data);
+        }
+    } // appendByte
+
+
+    /**
+     * A talkative socket.
+     * That's a plain socket that creates talkative
+     * input and output streams.
+     */
+    public class TalkativeSocket extends Socket {
+
+        protected InputStream  talkativeInput;
+        protected OutputStream talkativeOutput;
+
+        // default constructor only
+
+        public InputStream getInputStream() throws IOException {
+            if (talkativeInput == null) {
+                debugStream.println(">>>> (wrapping input stream)");
+                talkativeInput = new TalkativeInputStream
+                    (super.getInputStream(), debugStream);
+            }
+            return talkativeInput;
+        }
+
+        public OutputStream getOutputStream() throws IOException {
+            if (talkativeOutput == null) {
+                debugStream.println(">>>> (wrapping output stream)");
+                talkativeOutput = new TalkativeOutputStream
+                    (super.getOutputStream(), debugStream);
+            }
+            return talkativeOutput;
+        }
+
+
+        public String toString() {
+            return "Talkative" + super.toString();
+        }
+
+    } // class TalkativeSocket
+
+
+    /**
+     * Output stream that debug-prints the written data.
+     *
+     * @author <a href="mailto:rolandw at apache.org">Roland Weber</a>
+     */
+    public static class TalkativeOutputStream extends FilterOutputStream {
+
+        /** Where to debug-print to. */
+        private final PrintStream debug;
+
+        private static final String PREFIX_STRING = ">> ";
+        private static final int    PREFIX_LENGTH = PREFIX_STRING.length();
+
+        /**
+         * A string buffer for building debug output.
+         * The prefix will never change.
+         */
+        private final StringBuffer buffer;
+
+
+        /**
+         * Creates a new talkative output stream.
+         *
+         * @param out   the underlying output stream
+         * @param ps    the print stream for debug output
+         */
+        public TalkativeOutputStream(OutputStream out, PrintStream ps) {
+            super(out);
+            if (ps == null) {
+                throw new IllegalArgumentException
+                    ("Print stream must not be null.");
+            }
+            debug = ps;
+            buffer = new StringBuffer(128);
+            buffer.append(PREFIX_STRING);
+        }
+
+        public void close() throws IOException {
+            debug.println(">>>> close");
+            super.close();
+        }
+
+        public void flush() throws IOException {
+            debug.println(">>>> flush");
+            super.flush();
+        }
+
+        public void write(byte[] b) throws IOException {
+            buffer.setLength(PREFIX_LENGTH);
+            for (int i=0; i<b.length; i++)
+                appendByte(buffer, b[i]);
+            debug.println(buffer);
+
+            super.write(b);
+        }
+
+        public void write(byte[] b, int off, int len) throws IOException {
+            buffer.setLength(PREFIX_LENGTH);
+            final int end = off+len;
+            for (int i=off; i<end; i++)
+                appendByte(buffer, b[i]);
+            debug.println(buffer);
+
+            super.write(b, off, len);
+        }
+
+        public void write(int b) throws IOException {
+            buffer.setLength(PREFIX_LENGTH);
+            appendByte(buffer, b);
+            debug.println(buffer);
+
+            super.write(b);
+        }
+
+    } // class TalkativeOutputStream
+
+
+    /**
+     * Input stream that debug-prints the read data.
+     *
+     * @author <a href="mailto:rolandw at apache.org">Roland Weber</a>
+     */
+    public static class TalkativeInputStream extends FilterInputStream {
+
+        /** Where to debug-print to. */
+        private final PrintStream debug;
+
+        private static final String PREFIX_STRING = "<< ";
+        private static final int    PREFIX_LENGTH = PREFIX_STRING.length();
+
+        /**
+         * A string buffer for building debug output.
+         * The prefix will never change.
+         */
+        private final StringBuffer buffer;
+
+
+        /**
+         * Creates a new talkative input stream.
+         *
+         * @param in    the underlying input stream
+         * @param ps    the print stream for debug output
+         */
+        public TalkativeInputStream(InputStream in, PrintStream ps) {
+            super(in);
+            if (ps == null) {
+                throw new IllegalArgumentException
+                    ("Print stream must not be null.");
+            }
+            debug = ps;
+            buffer = new StringBuffer(128);
+            buffer.append(PREFIX_STRING);
+        }
+
+
+        public void close() throws IOException {
+            debug.println("<<<< close");
+            super.close();
+        }
+
+        public long skip(long n) throws IOException {
+            long skipped = super.skip(n);
+
+            debug.print("<<<< skip ");
+            debug.println(skipped);
+
+            return skipped;
+        }
+
+        public int read() throws IOException {
+            int data = super.read();
+            if (data < 0)
+                debug.print("<<<< EOF");
+            else
+            {
+                buffer.setLength(PREFIX_LENGTH);
+                appendByte(buffer, data);
+                debug.println(buffer);
+            }
+            return data;
+        }
+
+        public int read(byte[] b) throws IOException {
+            int length = super.read(b);
+
+            buffer.setLength(PREFIX_LENGTH);
+            for (int i=0; i<length; i++)
+                appendByte(buffer, b[i]);
+            debug.println(buffer);
+
+            return length;
+        }
+
+        public int read(byte[] b, int off, int len) throws IOException {
+            int length = super.read(b, off, len);
+
+            buffer.setLength(PREFIX_LENGTH);
+            final int end = off+length; // received length, not argument len
+            for (int i=off; i<end; i++)
+                appendByte(buffer, b[i]);
+            debug.println(buffer);
+
+            return length;
+        }
+
+    } // class TalkativeInputStream
+
+
+} // class TalkativeSocketFactory

src/examples/org/apache/http/examples/conn/OperatorConnectDirect.java

@@ -0,0 +1,192 @@
+/*
+ * $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.conn;
+
+
+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.HttpContext;
+import org.apache.http.protocol.HttpExecutionContext;
+
+import org.apache.http.conn.Scheme;
+import org.apache.http.conn.SocketFactory;
+import org.apache.http.conn.PlainSocketFactory;
+import org.apache.http.conn.UnmanagedClientConnection;
+import org.apache.http.conn.SocketConnectionOperator;
+import org.apache.http.conn.impl.DefaultClientConnection;
+import org.apache.http.conn.impl.DefaultSocketConnectionOperator;
+
+
+
+/**
+ * How to open a direct connection using
+ * {@link SocketConnectionOperator SocketConnectionOperator}.
+ * This exemplifies the <i>opening</i> of the connection only.
+ * The subsequent message exchange should not be used as a template.
+ *
+ * @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 OperatorConnectDirect {
+
+    /**
+     * 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
+
+        // one operator can be used for many connections
+        SocketConnectionOperator  scop = createOperator();
+        UnmanagedClientConnection conn = createConnection();
+
+        HttpRequest req = createRequest(target);
+        HttpContext ctx = createContext();
+
+        System.out.println("opening connection to " + target);
+        scop.openConnection(conn, target, ctx, getParams());
+
+        System.out.println("sending request");
+        conn.sendRequestHeader(req);
+        // there is no request entity
+        conn.flush();
+
+        System.out.println("receiving response header");
+        HttpResponse rsp = conn.receiveResponseHeader(getParams());
+
+        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("----------------------------------------");
+
+        System.out.println("closing connection");
+        conn.close();
+
+    } // main
+
+
+    private final static SocketConnectionOperator createOperator() {
+        return new DefaultSocketConnectionOperator();
+    }
+
+    private final static UnmanagedClientConnection createConnection() {
+        return new DefaultClientConnection();
+    }
+
+
+    /**
+     * 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.setUseExpectContinue(params, false);
+        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;
+    }
+
+
+    /**
+     * Creates a context for executing a request.
+     * Since this example doesn't really use the execution framework,
+     * the context can be left empty.
+     *
+     * @return  a new, empty context
+     */
+    private final static HttpContext createContext() {
+        return new HttpExecutionContext(null);
+    }
+
+} // class OperatorConnectDirect
+