hc-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ol...@apache.org
Subject svn commit: r732797 - in /httpcomponents/httpcore/trunk: module-main/src/main/java/org/apache/http/ module-nio/src/main/java/org/apache/http/nio/ module-nio/src/main/java/org/apache/http/nio/reactor/
Date Thu, 08 Jan 2009 19:16:34 GMT
Author: olegk
Date: Thu Jan  8 11:16:33 2009
New Revision: 732797

URL: http://svn.apache.org/viewvc?rev=732797&view=rev
Log:
Javadoc updates

Added:
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/package.html
Modified:
    httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/package.html
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/ContentDecoder.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/ContentDecoderChannel.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/ContentEncoder.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/ContentEncoderChannel.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/IOControl.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionRequest.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionRequestCallback.java

Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/package.html
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/package.html?rev=732797&r1=732796&r2=732797&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/package.html (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/package.html Thu
Jan  8 11:16:33 2009
@@ -34,7 +34,7 @@
 -->
 </head>
 <body>
-The core interfaces and classes of the HTTP components.
+The core HTTP components (HttpCore).
 
 These deal with the fundamental things required for using the
 HTTP protocol, such as representing a

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/ContentDecoder.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/ContentDecoder.java?rev=732797&r1=732796&r2=732797&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/ContentDecoder.java
(original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/ContentDecoder.java
Thu Jan  8 11:16:33 2009
@@ -40,6 +40,8 @@
  * chunks and apply the required coding transformation.
  * 
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ *
+ * @version $Revision$
  */
 public interface ContentDecoder {
 
@@ -54,11 +56,11 @@
     int read(ByteBuffer dst) throws IOException;
     
     /**
-     * Returns <tt>true</tt> if the entity has been received in its
+     * Returns <code>true</code> if the entity has been received in its
      * entirety.
      * 
-     * @return <tt>true</tt> if all the content has been consumed, 
-     * <tt>false</tt> otherwise.
+     * @return <code>true</code> if all the content has been consumed, 
+     * <code>false</code> otherwise.
      */
     boolean isCompleted();
     

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/ContentDecoderChannel.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/ContentDecoderChannel.java?rev=732797&r1=732796&r2=732797&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/ContentDecoderChannel.java
(original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/ContentDecoderChannel.java
Thu Jan  8 11:16:33 2009
@@ -1,7 +1,7 @@
 /*
- * $HeadURL:$
- * $Revision:$
- * $Date:$
+ * $HeadURL$
+ * $Revision$
+ * $Date$
  *
  * ====================================================================
  * Licensed to the Apache Software Foundation (ASF) under one
@@ -37,9 +37,12 @@
 
 /**
  * A {@link ReadableByteChannel} that delegates to a {@link ContentDecoder}.
- * Attempts to close this channel are ignored, and isOpen always returns true.
+ * Attempts to close this channel are ignored, and {@link #isOpen} always 
+ * returns <code>true</code>.
  *
  * @author <a href="mailto:sberlin at gmail.com">Sam Berlin</a>
+ *
+ * @version $Revision$
  */
 public class ContentDecoderChannel implements ReadableByteChannel {
 

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/ContentEncoder.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/ContentEncoder.java?rev=732797&r1=732796&r2=732797&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/ContentEncoder.java
(original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/ContentEncoder.java
Thu Jan  8 11:16:33 2009
@@ -40,6 +40,8 @@
  * content to the underlying channel in small chunks.
  * 
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ *
+ * @version $Revision$
  */
 public interface ContentEncoder {
 
@@ -60,11 +62,11 @@
     void complete() throws IOException;
     
     /**
-     * Returns <tt>true</tt> if the entity has been transferred in its
+     * Returns <code>true</code> if the entity has been transferred in its
      * entirety.
      * 
-     * @return <tt>true</tt> if all the content has been produced, 
-     * <tt>false</tt> otherwise.
+     * @return <code>true</code> if all the content has been produced, 
+     * <code>false</code> otherwise.
      */
     boolean isCompleted();
     

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/ContentEncoderChannel.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/ContentEncoderChannel.java?rev=732797&r1=732796&r2=732797&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/ContentEncoderChannel.java
(original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/ContentEncoderChannel.java
Thu Jan  8 11:16:33 2009
@@ -1,7 +1,7 @@
 /*
- * $HeadURL:$
- * $Revision:$
- * $Date:$
+ * $HeadURL$
+ * $Revision$
+ * $Date$
  *
  * ====================================================================
  * Licensed to the Apache Software Foundation (ASF) under one
@@ -39,9 +39,12 @@
 
 /**
  * A {@link WritableByteChannel} that delegates to a {@link ContentEncoder}.
- * Attempts to close this channel are ignored, and isOpen always returns true.
+ * Attempts to close this channel are ignored, and {@link #isOpen} always 
+ * returns <code>true</code>.
  *
  * @author <a href="mailto:sberlin at gmail.com">Sam Berlin</a>
+ *
+ * @version $Revision$
  */
 public class ContentEncoderChannel implements WritableByteChannel {
 

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/IOControl.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/IOControl.java?rev=732797&r1=732796&r2=732797&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/IOControl.java
(original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/IOControl.java
Thu Jan  8 11:16:33 2009
@@ -34,17 +34,22 @@
 import java.io.IOException;
 
 /**
- * Connection input/output control interface. It can be used to request or
- * temporarily suspend event notifications that are triggered when the underlying
- * channel is ready for input / output operations. 
+ * Connection input/output control interface. It can be used to control interest 
+ * in I/O event notifications for non-blocking HTTP connections.
+ * <p>
+ * Implementations of this interface are expected to be threading safe. 
+ * Therefore it can be used to request / suspend I/O event notifications from 
+ * any thread of execution.
  * 
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ *
+ * @version $Revision$
  */
 public interface IOControl {
 
     /**
      * Requests event notifications to be triggered when the underlying
-     * channel is ready for input oprtations.
+     * channel is ready for input operations.
      */
     void requestInput();
     
@@ -56,7 +61,7 @@
     
     /**
      * Requests event notifications to be triggered when the underlying
-     * channel is ready for output oprtations.
+     * channel is ready for output operations.
      */
     void requestOutput();
     

Added: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/package.html
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/package.html?rev=732797&view=auto
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/package.html
(added)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/package.html
Thu Jan  8 11:16:33 2009
@@ -0,0 +1,43 @@
+<html>
+<head>
+<!--
+/*
+ * $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/>.
+ *
+ */
+-->
+</head>
+<body>
+The core HTTP components based on non-blocking I/O model (HttpCore NIO).
+<p/>
+This layer defines interfaces for transferring HTTP messages over non-blocking
+HTTP connections and protocol handlers for processing HTTP messages 
+asynchronously.
+</body>
+</html>

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionRequest.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionRequest.java?rev=732797&r1=732796&r2=732797&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionRequest.java
(original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionRequest.java
Thu Jan  8 11:16:33 2009
@@ -34,26 +34,96 @@
 import java.io.IOException;
 import java.net.SocketAddress;
 
+/**
+ * SessionRequest interface represents a request to establish a new connection
+ * (or session) to a remote host. It can be used to monitor the status of the 
+ * request, to block waiting for its completion, or to cancel the request. 
+ * <p>
+ * Implementations of this interface are expected to be threading safe.
+ * 
+ * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ *
+ * @version $Revision$
+ */
 public interface SessionRequest {
 
+    /**
+     * Returns socket address of the remote host.
+     * 
+     * @return socket address of the remote host
+     */
     SocketAddress getRemoteAddress();
     
+    /**
+     * Returns local socket address.
+     * 
+     * @return local socket address.
+     */
     SocketAddress getLocalAddress();
     
+    /**
+     * Returns attachment object will be added to the session's context upon 
+     * initialization. This object can be used to pass an initial processing 
+     * state to the protocol handler.
+     * 
+     * @return attachment object.
+     */
     Object getAttachment();
     
+    /**
+     * Determines whether the request has been completed (either successfully
+     * or unsuccessfully).
+     * 
+     * @return <code>true</true> if the request has been completed,
+     *  <code>false</true> if still pending.
+     */
     boolean isCompleted();
     
+    /**
+     * Returns {@link IOSession} instance created as a result of this request
+     * or <code>null</code> if the request is still pending.
+     * 
+     * @return I/O session or <code>null</code> if the request is still pending.
+     */
     IOSession getSession();
     
+    /**
+     * Returns {@link IOException} instance if the request could not be 
+     * successfully executed due to an I/O error or <code>null</code> if no
+     * error occurred to this point.
+     * 
+     * @return I/O exception or <code>null</code> if no error occurred to 
+     * this point.
+     */
     IOException getException();
 
+    /**
+     * Waits for completion of this session request.
+     * 
+     * @throws InterruptedException in case the execution process was 
+     *   interrupted.
+     */
     void waitFor() throws InterruptedException;
     
+    /**
+     * Sets connect timeout value in milliseconds.
+     * 
+     * @param timeout connect timeout value in milliseconds.
+     */
     void setConnectTimeout(int timeout);
     
+    /**
+     * Returns connect timeout value in milliseconds.
+     * 
+     * @return connect timeout value in milliseconds.
+     */
     int getConnectTimeout();
     
+    /**
+     * Cancels the request. Invocation of this method will set the status of 
+     * the request to completed and will unblock threads blocked in 
+     * the {{@link #waitFor()}} method.
+     */
     void cancel();
     
 }

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionRequestCallback.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionRequestCallback.java?rev=732797&r1=732796&r2=732797&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionRequestCallback.java
(original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionRequestCallback.java
Thu Jan  8 11:16:33 2009
@@ -31,14 +31,47 @@
 
 package org.apache.http.nio.reactor;
 
+/**
+ * SessionRequestCallback interface can be used to get notifications of 
+ * completion of session requests asynchronously without having to wait 
+ * for it, blocking the current thread of execution. 
+ *
+ * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ *
+ * @version $Revision$
+ */
 public interface SessionRequestCallback {
 
+    /**
+     * Triggered on successful completion of a {@link SessionRequest}. 
+     * The {@link SessionRequest#getSession()} method can now be used to obtain 
+     * the new I/O session. 
+     *  
+     * @param request session request.
+     */
     void completed(SessionRequest request);
     
+    /**
+     * Triggered on unsuccessful completion a {@link SessionRequest}. 
+     * The {@link SessionRequest#getException()} method can now be used to 
+     * obtain the cause of the error. 
+     *  
+     * @param request session request.
+     */
     void failed(SessionRequest request);
     
+    /**
+     * Triggered if a {@link SessionRequest} times out. 
+     *  
+     * @param request session request.
+     */
     void timeout(SessionRequest request);
 
+    /**
+     * Triggered on cancellation of a {@link SessionRequest}. 
+     *  
+     * @param request session request.
+     */
     void cancelled(SessionRequest request);
     
 }



Mime
View raw message