hc-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ol...@apache.org
Subject svn commit: r732065 - in /httpcomponents/httpcore/trunk: module-main/src/main/java/org/apache/http/io/ module-nio/src/main/java/org/apache/http/nio/reactor/
Date Tue, 06 Jan 2009 19:10:48 GMT
Author: olegk
Date: Tue Jan  6 11:10:48 2009
New Revision: 732065

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

Modified:
    httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/SessionInputBuffer.java
    httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/SessionOutputBuffer.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/ConnectingIOReactor.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/IOReactorExceptionHandler.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/ListenerEndpoint.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/ListeningIOReactor.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionBufferStatus.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionInputBuffer.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionOutputBuffer.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/package.html

Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/SessionInputBuffer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/SessionInputBuffer.java?rev=732065&r1=732064&r2=732065&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/SessionInputBuffer.java
(original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/SessionInputBuffer.java
Tue Jan  6 11:10:48 2009
@@ -37,8 +37,7 @@
 
 /**
  * Session input buffer for blocking connections. This interface is similar to 
- * InputStream class, but it also provides methods for reading CR-LF delimited 
- * lines. 
+ * InputStream class, but it also provides methods for reading lines of text. 
  * <p>
  * Implementing classes are also expected to manage intermediate data buffering
  * for optimal input performance.  
@@ -112,8 +111,8 @@
      * the value <code>-1</code> is returned. This method blocks until input

      * data is available, end of file is detected, or an exception is thrown.
      * <p>
-     * Implementing classes can choose a char encoding and a line delimiter 
-     * as appropriate. 
+     * The choice of a char encoding and line delimiter sequence is up to the 
+     * specific implementations of this interface. 
      *
      * @param      buffer   the line buffer.
      * @return     one line of characters
@@ -128,8 +127,8 @@
      * <code>null</code> is returned. This method blocks until input data is

      * available, end of file is detected, or an exception is thrown.
      * <p>
-     * Implementing classes can choose a char encoding and a line delimiter 
-     * as appropriate. 
+     * The choice of a char encoding and line delimiter sequence is up to the 
+     * specific implementations of this interface. 
      * 
      * @return HTTP line as a string
      * @exception  IOException  if an I/O error occurs.

Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/SessionOutputBuffer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/SessionOutputBuffer.java?rev=732065&r1=732064&r2=732065&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/SessionOutputBuffer.java
(original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/SessionOutputBuffer.java
Tue Jan  6 11:10:48 2009
@@ -37,8 +37,7 @@
 
 /**
  * Session output buffer for blocking connections. This interface is similar to 
- * OutputStream class, but it also provides methods for writing CR-LF delimited 
- * lines. 
+ * OutputStream class, but it also provides methods for writing lines of text. 
  * <p>
  * Implementing classes are also expected to manage intermediate data buffering
  * for optimal output performance.  
@@ -87,8 +86,8 @@
      * Writes characters from the specified string followed by a line delimiter 
      * to this session buffer.
      * <p>
-     * Implementing classes can choose a char encoding and a line delimiter 
-     * as appropriate. 
+     * The choice of a char encoding and line delimiter sequence is up to the 
+     * specific implementations of this interface. 
      *
      * @param      s   the line.
      * @exception  IOException  if an I/O error occurs.
@@ -99,8 +98,8 @@
      * Writes characters from the specified char array followed by a line 
      * delimiter to this session buffer.
      * <p>
-     * Implementing classes can choose a char encoding and a line delimiter 
-     * as appropriate. 
+     * The choice of a char encoding and line delimiter sequence is up to the 
+     * specific implementations of this interface. 
      *
      * @param      buffer   the buffer containing chars of the line.
      * @exception  IOException  if an I/O error occurs.

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/ConnectingIOReactor.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/ConnectingIOReactor.java?rev=732065&r1=732064&r2=732065&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/ConnectingIOReactor.java
(original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/ConnectingIOReactor.java
Tue Jan  6 11:10:48 2009
@@ -33,8 +33,48 @@
 
 import java.net.SocketAddress;
 
+/**
+ * ConnectingIOReactor represents an I/O reactor capable of establishing 
+ * connections to remote hosts.
+ * 
+ * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ *
+ * @version $Revision$
+ */
 public interface ConnectingIOReactor extends IOReactor {
 
+    /**
+     * Requests a connection to a remote host.
+     * <p>
+     * Opening a connection to a remote host usually tends to be a time 
+     * consuming process and may take a while to complete. One can monitor and 
+     * control the process of session initialization by means of the 
+     * {@link SessionRequest} interface.
+     * <p>
+     * There are several parameters one can use to exert a greater control over 
+     * the process of session initialization:
+     * <p>
+     * A non-null local socket address parameter can be used to bind the socket 
+     * to a specific local address.
+     * <p>
+     * An attachment object can added to the new session's context upon 
+     * initialization. This object can be used to pass an initial processing 
+     * state to the protocol handler.
+     * <p>
+     * It is often desirable to be able to react to the completion of a session 
+     * request asynchronously without having to wait for it, blocking the 
+     * current thread of execution. One can optionally provide an implementation 
+     * {@link SessionRequestCallback} instance to get notified of events related 
+     * to session requests, such as request completion, cancellation, failure or 
+     * timeout.
+     * 
+     * @param remoteAddress the socket address of the remote host.
+     * @param localAddress the local socket address. Can be <code>null</code>,
+     *    in which can the default local address and a random port will be used.
+     * @param attachment the attachment object. Can be <code>null</code>.
+     * @param callback interface. Can be <code>null</code>.
+     * @return session request object.
+     */
     SessionRequest connect(
             SocketAddress remoteAddress, 
             SocketAddress localAddress, 

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/IOReactorExceptionHandler.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/IOReactorExceptionHandler.java?rev=732065&r1=732064&r2=732065&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/IOReactorExceptionHandler.java
(original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/IOReactorExceptionHandler.java
Tue Jan  6 11:10:48 2009
@@ -35,16 +35,19 @@
 
 /**
  * Abstract exception handler intended to deal with potentially recoverable 
- * I/O exceptions thrown by an I/O reactor
+ * I/O exceptions thrown by an I/O reactor.
  * 
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ *
+ * @version $Revision$
  * 
  */
 public interface IOReactorExceptionHandler {
 
     /**
-     * This method is expected to examine the I/O exception passed as a parameter
-     * and decide whether it is safe to continue execution of the I/O reactor 
+     * This method is expected to examine the I/O exception passed as 
+     * a parameter and decide whether it is safe to continue execution of 
+     * the I/O reactor. 
      * 
      * @param ex potentially recoverable I/O exception 
      * @return <code>true</code> if it is safe to ignore the exception 
@@ -54,8 +57,9 @@
     boolean handle(IOException ex); 
     
     /**
-     * This method is expected to examine the runtime exception passed as a parameter
-     * and decide whether it is safe to continue execution of the I/O reactor 
+     * This method is expected to examine the runtime exception passed as 
+     * a parameter and decide whether it is safe to continue execution of 
+     * the I/O reactor. 
      * 
      * @param ex potentially recoverable runtime exception 
      * @return <code>true</code> if it is safe to ignore the exception 

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/ListenerEndpoint.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/ListenerEndpoint.java?rev=732065&r1=732064&r2=732065&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/ListenerEndpoint.java
(original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/ListenerEndpoint.java
Tue Jan  6 11:10:48 2009
@@ -1,7 +1,7 @@
 /*
- * $HeadURL:$
- * $Revision:$
- * $Date:$
+ * $HeadURL$
+ * $Revision$
+ * $Date$
  *
  * ====================================================================
  * Licensed to the Apache Software Foundation (ASF) under one
@@ -34,16 +34,53 @@
 import java.io.IOException;
 import java.net.SocketAddress;
 
+/**
+ * ListenerEndpoint interface represents an endpoint used by an I/O reactor
+ * to listen for incoming connection from remote clients.
+ * 
+ * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ *
+ * @version $Revision$
+ * 
+ */
 public interface ListenerEndpoint {
 
+    /**
+     * Returns the socket address of this endpoint.
+     * 
+     * @return socket address.
+     */
     SocketAddress getAddress();
     
+    /**
+     * Returns an instance of {@link IOException} thrown during initialization 
+     * of this endpoint or <code>null</code>, if initialization was successful.
+     * 
+     * @return I/O exception object or <code>null</code>.
+     */
     IOException getException();
 
+    /**
+     * Waits for completion of initialization process of this endpoint.
+     * 
+     * @throws InterruptedException in case the initialization process was 
+     *   interrupted.
+     */
     void waitFor() throws InterruptedException;
     
+    /**
+     * Determines if this endpoint has been closed and is no longer listens
+     * for incoming connections.
+     * 
+     * @return <code>true</code> if the endpoint has been closed,
+     *   <code>false</code> otherwise.
+     */
     boolean isClosed();
     
+    /**
+     * Closes this endpoint. The endpoint will stop accepting incoming 
+     * connection.
+     */
     void close();
     
 }

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/ListeningIOReactor.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/ListeningIOReactor.java?rev=732065&r1=732064&r2=732065&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/ListeningIOReactor.java
(original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/ListeningIOReactor.java
Tue Jan  6 11:10:48 2009
@@ -35,16 +35,51 @@
 import java.util.Set;
 import java.io.IOException;
 
+/**
+ * ListeningIOReactor represents an I/O reactor capable of listening for 
+ * incoming connections on one or several ports.
+ *  
+ * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ *
+ * @version $Revision$
+ * 
+ */
 public interface ListeningIOReactor extends IOReactor {
 
+    /**
+     * Opens a new listener endpoint with the given socket address. Once 
+     * the endpoint is fully initialized it starts accepting incoming 
+     * connections and propagates I/O activity notifications to the I/O event
+     * dispatcher. 
+     * 
+     * @param address the socket address to listen on.
+     * @return listener endpoint.
+     */
     ListenerEndpoint listen(SocketAddress address);
 
+    /**
+     * Suspends the I/O reactor preventing it from accepting new connections on
+     * all active endpoints.
+     * 
+     * @throws IOException in case of an I/O error.
+     */
     void pause()
         throws IOException;
 
+    /**
+     * Resumes the I/O reactor restoring its ability to accept incoming 
+     * connections on all active endpoints.
+     * 
+     * @throws IOException in case of an I/O error.
+     */
     void resume()
         throws IOException;
 
+    /**
+     * Returns a set of endpoints for this I/O reactor.
+     * 
+     * @return set of endpoints. 
+     */
     Set<ListenerEndpoint> getEndpoints();
     
 }

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionBufferStatus.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionBufferStatus.java?rev=732065&r1=732064&r2=732065&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionBufferStatus.java
(original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionBufferStatus.java
Tue Jan  6 11:10:48 2009
@@ -36,6 +36,8 @@
  * I/O buffers. 
  * 
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ * 
+ * @version $Revision$
  */
 public interface SessionBufferStatus {
 

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionInputBuffer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionInputBuffer.java?rev=732065&r1=732064&r2=732065&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionInputBuffer.java
(original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionInputBuffer.java
Tue Jan  6 11:10:48 2009
@@ -44,11 +44,11 @@
  * intermediate buffering of input data streamed from a source channel and 
  * reading buffered data to a destination, usually {@link ByteBuffer} or 
  * {@link WritableByteChannel}. This interface also provides methods for reading 
- * CR-LF delimited lines.
+ * lines of text.
  *
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
  *
- * @since 4.0
+ * @version $Revision$
  */
 public interface SessionInputBuffer {
     
@@ -145,8 +145,8 @@
      * been reached and the content currently stored in the buffer should be 
      * treated as a complete line.  
      * <p>
-     * Implementing classes can choose a char encoding and a line delimiter 
-     * as appropriate. 
+     * The choice of a char encoding and line delimiter sequence is up to the 
+     * specific implementations of this interface. 
      * 
      * @param dst the destination buffer.
      * @param endOfStream
@@ -171,8 +171,8 @@
      * been reached and the content currently stored in the buffer should be 
      * treated as a complete line.  
      * <p>
-     * Implementing classes can choose a char encoding and a line delimiter 
-     * as appropriate. 
+     * The choice of a char encoding and line delimiter sequence is up to the 
+     * specific implementations of this interface. 
      * 
      * @param endOfStream
      * @return a string representing a complete line, if available. 

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionOutputBuffer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionOutputBuffer.java?rev=732065&r1=732064&r2=732065&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionOutputBuffer.java
(original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionOutputBuffer.java
Tue Jan  6 11:10:48 2009
@@ -44,29 +44,81 @@
  * facilitates intermediate buffering of output data streamed out to 
  * a destination channel and writing data to the buffer from a source, usually 
  * {@link ByteBuffer} or {@link ReadableByteChannel}. This interface also 
- * provides methods for writing CR-LF delimited lines.
+ * provides methods for writing lines of text.
  *
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
  *
- * @since 4.0
+ * @version $Revision$
  */
 public interface SessionOutputBuffer {
 
+    /**
+     * Determines if the buffer contains data.
+     * 
+     * @return <code>true</code> if there is data in the buffer,
+     *   <code>false</code> otherwise.
+     */
     boolean hasData();
     
+    /**
+     * Returns the length of this buffer.
+     * 
+     * @return buffer length.
+     */
     int length();
     
+    /**
+     * Makes an attempt to flush the content of this buffer to the given
+     * destination {@link WritableByteChannel}.
+     *  
+     * @param channel the destination channel.
+     * @return The number of bytes written, possibly zero.
+     * @throws IOException in case of an I/O error.
+     */
     int flush(WritableByteChannel channel) 
         throws IOException;
 
+    /**
+     * Copies content of the source buffer into this buffer. The capacity of 
+     * the destination will be expanded in order to accommodate the entire
+     * content of the source buffer.
+     *    
+     * @param src the source buffer.
+     */
     void write(ByteBuffer src);
 
+    /**
+     * Reads a sequence of bytes from the source channel into this buffer.
+     *    
+     * @param src the source channel.
+     */
     void write(ReadableByteChannel src) 
         throws IOException;
     
-    void writeLine(CharArrayBuffer linebuffer) 
+    /**
+     * Copies content of the source buffer into this buffer as one line of text
+     * including a line delimiter. The capacity of the destination will be 
+     * expanded in order to accommodate the entire content of the source buffer.
+     * <p>
+     * The choice of a char encoding and line delimiter sequence is up to the 
+     * specific implementations of this interface. 
+     *    
+     * @param src the source buffer.
+     */
+    void writeLine(CharArrayBuffer src) 
         throws CharacterCodingException;
     
+    /**
+     * Copies content of the given string into this buffer as one line of text
+     * including a line delimiter. 
+     * The capacity of the destination will be expanded in order to accommodate 
+     * the entire string.
+     * <p>
+     * The choice of a char encoding and line delimiter sequence is up to the 
+     * specific implementations of this interface. 
+     *    
+     * @param s the string.
+     */
     void writeLine(String s) 
         throws IOException;
     

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/package.html
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/package.html?rev=732065&r1=732064&r2=732065&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/package.html
(original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/package.html
Tue Jan  6 11:10:48 2009
@@ -40,7 +40,5 @@
 This API is not specific to HTTP communication.
 However, it is minimal in the sense that it defines only
 what is required within the scope of HTTP components.
-If you are looking for something more general, please use
-<a href="http://directory.apache.org/subprojects/mina/">MINA</a>.
 </body>
 </html>



Mime
View raw message