[jboss-remoting-commits] JBoss Remoting SVN: r3485 - remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/protocol.

[jboss-remoting-commits at lists.jboss.org]

Author: david.lloyd at jboss.com
Date: 2008-02-22 12:23:32 -0500 (Fri, 22 Feb 2008)
New Revision: 3485

Modified:
   remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/protocol/ProtocolHandler.java
Log:
javadoc cleanup

Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/protocol/ProtocolHandler.java
===================================================================
--- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/protocol/ProtocolHandler.java	2008-02-22 16:58:26 UTC (rev 3484)
+++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/protocol/ProtocolHandler.java	2008-02-22 17:23:32 UTC (rev 3485)
@@ -37,14 +37,37 @@
      * the protocol handler on the remote side.
      *
      * @param remoteServiceIdentifier the remote service identifier
-     * @throws IOException if an error occurs
+     * @throws IOException if an I/O error occurs
      */
     void sendServiceActivate(ServiceIdentifier remoteServiceIdentifier) throws IOException;
 
+    /**
+     * Send the reply to a request.
+     *
+     * @param remoteContextIdentifier the context that the request was received under
+     * @param requestIdentifier the request identifier
+     * @param reply the reply to send
+     * @throws IOException if an I/O error occurs
+     */
     void sendReply(ContextIdentifier remoteContextIdentifier, RequestIdentifier requestIdentifier, Object reply) throws IOException;
 
+    /**
+     * Send an exception reply to a request.
+     *
+     * @param remoteContextIdentifier the context that the request was received under
+     * @param requestIdentifier the request identifier
+     * @param exception the exception to send
+     * @throws IOException if an I/O error occurs
+     */
     void sendException(ContextIdentifier remoteContextIdentifier, RequestIdentifier requestIdentifier, RemoteExecutionException exception) throws IOException;
 
+    /**
+     * Send a notification to the client that a request was cancelled.
+     *
+     * @param remoteContextIdentifier the context that the request was received under
+     * @param requestIdentifier the request identifier
+     * @throws IOException if an I/O error occurs
+     */
     void sendCancelAcknowledge(ContextIdentifier remoteContextIdentifier, RequestIdentifier requestIdentifier) throws IOException;
 
     /**
@@ -52,7 +75,7 @@
      * if it is undeployed, the session is being shut down, or if the activation request was not accepted.
      *
      * @param remoteServiceIdentifier the remote service identifier
-     * @throws IOException if an error occurs
+     * @throws IOException if an I/O error occurs
      */
     void sendServiceTerminate(ServiceIdentifier remoteServiceIdentifier) throws IOException;
 
@@ -66,7 +89,7 @@
      *
      * @param serviceIdentifier the service identifier
      * @return a context identifier associated with the given service identifier
-     * @throws IOException if an error occurs
+     * @throws IOException if an I/O error occurs
      */
     ContextIdentifier openContext(ServiceIdentifier serviceIdentifier) throws IOException;
 
@@ -76,17 +99,24 @@
      * on the remote side for this context identifier.
      *
      * @param contextIdentifier
-     * @throws IOException
+     * @throws IOException if an I/O error occurs
      */
     void closeContext(ContextIdentifier contextIdentifier) throws IOException;
 
+    /**
+     * Acquire a new request identifier that will be used to send a request.
+     *
+     * @param contextIdentifier the context identifier
+     * @return the new request identifier
+     * @throws IOException if an I/O error occurs
+     */
     RequestIdentifier openRequest(ContextIdentifier contextIdentifier) throws IOException;
 
     /**
      * Get a new service identifier that will be used to request a service from the remote side.
      *
      * @return the new service identifier
-     * @throws IOException
+     * @throws IOException if an I/O error occurs
      */
     ServiceIdentifier openService() throws IOException;
 
@@ -96,14 +126,37 @@
      *
      * @param serviceIdentifier the service identifier
      * @param locator the locator for the new service
-     * @throws IOException if an error occurs
+     * @throws IOException if an I/O error occurs
      */
     void sendServiceRequest(ServiceIdentifier serviceIdentifier, ServiceLocator<?, ?> locator) throws IOException;
 
+    /**
+     * Send a notification that the client is no longer using the given service.
+     *
+     * @param serviceIdentifier the service identifier
+     * @throws IOException if an I/O error occurs
+     */
     void closeService(ServiceIdentifier serviceIdentifier) throws IOException;
 
+    /**
+     * Send a request to the remote side.
+     *
+     * @param contextIdentifier the context identifier
+     * @param requestIdentifier the request identifier
+     * @param request the request body
+     * @param streamExecutor the executor to use for stream callbacks
+     * @throws IOException if an I/O error occurs
+     */
     void sendRequest(ContextIdentifier contextIdentifier, RequestIdentifier requestIdentifier, Object request, Executor streamExecutor) throws IOException;
 
+    /**
+     * Send a request to cancel a previously sent request.
+     *
+     * @param contextIdentifier the context identifier
+     * @param requestIdentifier the request identifier to cancel
+     * @param mayInterrupt {@code true} if processing may be interrupted
+     * @throws IOException if an I/O error occurs
+     */
     void sendCancelRequest(ContextIdentifier contextIdentifier, RequestIdentifier requestIdentifier, boolean mayInterrupt) throws IOException;
 
     /* SESSION methods */
@@ -114,7 +167,7 @@
      * the same time.
      *
      * @return the identifier of a stream
-     * @throws IOException
+     * @throws IOException if an I/O error occurs
      */
     StreamIdentifier openStream() throws IOException;
 
@@ -124,7 +177,7 @@
      * be released and possibly reused.
      *
      * @param streamIdentifier
-     * @throws IOException
+     * @throws IOException if an I/O error occurs
      */
     void closeStream(StreamIdentifier streamIdentifier) throws IOException;
 
@@ -133,10 +186,17 @@
      *
      * @param input
      * @return the new stream identifier
-     * @throws IOException
+     * @throws IOException if an I/O error occurs
      */
     StreamIdentifier readStreamIdentifier(ObjectInput input) throws IOException;
 
+    /**
+     * Write a stream identifier to an object output stream.
+     *
+     * @param output the output to write to
+     * @param identifier the identifier to write
+     * @throws IOException if an I/O error occurs
+     */
     void writeStreamIdentifier(ObjectOutput output, StreamIdentifier identifier) throws IOException;
 
     /**
@@ -150,14 +210,14 @@
      * @param streamExecutor the executor that should be used to handle stream data
      * @return a message buffer into which the message can be written
      *
-     * @throws IOException if an error occurs
+     * @throws IOException if an I/O error occurs
      */
     MessageOutput sendStreamData(StreamIdentifier streamIdentifier, Executor streamExecutor) throws IOException;
 
     /**
      * Close the session.
      *
-     * @throws IOException
+     * @throws IOException if an I/O error occurs
      */
     void closeSession() throws IOException;