commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mt...@apache.org
Subject svn commit: r1130090 - in /commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime: Exec.java net/Endpoint.java net/SelectionKey.java net/SelectionKeyImpl.java net/Selector.java
Date Wed, 01 Jun 2011 10:37:50 GMT
Author: mturk
Date: Wed Jun  1 10:37:49 2011
New Revision: 1130090

URL: http://svn.apache.org/viewvc?rev=1130090&view=rev
Log:
Start fixing javadoc

Modified:
    commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Exec.java
    commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/net/Endpoint.java
    commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/net/SelectionKey.java
    commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/net/SelectionKeyImpl.java
    commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/net/Selector.java

Modified: commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Exec.java
URL: http://svn.apache.org/viewvc/commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Exec.java?rev=1130090&r1=1130089&r2=1130090&view=diff
==============================================================================
--- commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Exec.java (original)
+++ commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Exec.java Wed Jun
 1 10:37:49 2011
@@ -132,7 +132,7 @@ public abstract class Exec
 
     /**
      * Indicates whether the standard output should be redirected.
-     * If not redirected, the {@link Exec#getStdout()} will always
+     * If not redirected, the {@link #getStdout()} will always
      * return {@code empty} byte array and standard output is written to
      * {@code /dev/null}.
      *
@@ -147,9 +147,9 @@ public abstract class Exec
     /**
      * Indicates whether the standard error should be redirected.
      * 
-     * If not redirected, the {@link Exec#getStderr()} will always
+     * If not redirected, the {@link #getStderr()} will always
      * return {@code empty} byte array and standard error is written to
-     * {@link Exec#getOutputStream()}.
+     * {@link #getStdout() stdout}.
      *
      * @return {@code true} if the standard error is redirected; {@code false}
      *         otherwise.

Modified: commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/net/Endpoint.java
URL: http://svn.apache.org/viewvc/commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/net/Endpoint.java?rev=1130090&r1=1130089&r2=1130090&view=diff
==============================================================================
--- commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/net/Endpoint.java
(original)
+++ commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/net/Endpoint.java
Wed Jun  1 10:37:49 2011
@@ -56,29 +56,44 @@ public abstract class Endpoint implement
     }
 
     /**
-     * Gets the endpoint's  descriptor object.
+     * Gets the endpoint's descriptor object.
      */
     public abstract Descriptor descriptor();
 
     /**
-     * Sets the blocking mode of this descriptor.
-     *
+     * Sets the blocking mode of this endpoint.
+     * <p>
+     * This method is not thread safe. Calling this method and
+     * {@link #register(Selector, int) register} should not be done from
+     * multiple concurrent threads. If this endpoint's key is currently
+     * inside selector's select operation the {@code IllegalBlockingModeException }
+     * will be thrown. User should call this method either before registering
+     * this endpoint or after it was selected.
+     * </p>
      * @param block
-     *          {@code true} for setting this descriptor's mode to blocking,
+     *          {@code true} for setting this endpoints's mode to blocking,
      *          {@code false} to set it to non-blocking.
      * @return this descriptor.
-     * @throws ClosedChannelException
-     *          if this descriptr is closed.
+     * @throws ClosedDescriptorException
+     *          if this endpoint's descriptor is closed.
+     * @throws IllegalBlockingModeException
+     *          if this endpoint's key is currently selecting.
      * @throws IOException
      *         if an I/O error occurs.
      */
     public abstract Descriptor configureBlocking(boolean block)
         throws ClosedDescriptorException,
+               IllegalBlockingModeException,
                IOException;
 
     /**
-     * Test wather or not every I/O operation on {@code this} descriptor will
+     * Test wather or not every I/O operation on {@code this} endpoint will
      * block until it completes.
+     * <p>
+     * This method is not thread safe. Calling this method and
+     * {@link #configureBlocking(boolean) configureBlocking} should not be
+     * done from multiple concurrent threads.
+     * </p>
      *
      * @return {@code true} if, and only if, this device
      *         is in blocking mode.
@@ -91,6 +106,11 @@ public abstract class Endpoint implement
 
     /**
      * Indicates whether this channel is registered with at least one selector.
+     * <p>
+     * This method is not thread safe. Calling this method and
+     * {@link #register(Selector, int) register} should not be done from
+     * multiple concurrent threads or the faulty results might be returned.
+     * </p>
      *
      * @return {@code true} if this channel is registered, {@code false}
      *         otherwise.
@@ -113,6 +133,11 @@ public abstract class Endpoint implement
     /**
      * Returns the key representing the endpoint's registration with
      * the given selector.
+     * <p>
+     * Note that both endpoint's key and key's selector are immutable.
+     * This means that once the endpoint is registered with the given
+     * selector its registration cannot change for the endpoit's life time.
+     * </p>
      *
      * @param selector the selector.
      *
@@ -124,20 +149,15 @@ public abstract class Endpoint implement
 
     /**
      * Registers this endpoint with the specified selector for the specified
-     * selection ops and an object to attach. If the channel is already
+     * selection ops and an object to attach. If the endpoint is already
      * registered with the selector, the corresponding selection key is returned
-     * but its {@link SelectionOps interest set} is updated to {@code ops} and
-     * the attached object is updated to {@code att}. The returned key is
-     * canceled if the channel is closed while registering is in progress.
-     * <p>
-     * Calling this method is valid at any time. If another thread executes this
-     * method or the {@code configureBlocking(boolean)} method then this call is
-     * blocked until the other call finishes. After that, it will synchronize on
-     * the key set of the selector and thus may again block if other threads
-     * also hold locks on the key set of the same selector.
+     * but its {@link SelectionKey interest set} is updated to {@code ops} and
+     * the attached object is updated to {@code att} unless the {@code att} is
+     * {@code null}. The returned key is canceled if the channel is closed
+     * while registering is in progress.
      *
      * @param selector the selector with which to register this endpoint.
-     * @param ops this endpoints's {@link SelectionOps interest set}.
+     * @param ops this endpoints's {@link SelectionKey interest set}.
      * @param att the object to attach, can be {@code null} in which case the
      *            previous attachment is not modified.
      *
@@ -160,15 +180,9 @@ public abstract class Endpoint implement
      * Registers this endpoint with the specified selector for the specified
      * selection ops. If the channel is already
      * registered with the selector, the corresponding selection key is returned
-     * but its {@link SelectionOps interest set} is updated to {@code ops}.
+     * but its {@link SelectionKey interest set} is updated to {@code ops}.
      * The returned key is canceled if the channel is closed while registering
      * is in progress.
-     * <p>
-     * Calling this method is valid at any time. If another thread executes this
-     * method or the {@code configureBlocking(boolean)} method then this call is
-     * blocked until the other call finishes. After that, it will synchronize on
-     * the key set of the selector and thus may again block if other threads
-     * also hold locks on the key set of the same selector.
      *
      * @param selector the selector with which to register this endpoint.
      * @param ops this endpoints's {@link SelectionOps interest set}.

Modified: commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/net/SelectionKey.java
URL: http://svn.apache.org/viewvc/commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/net/SelectionKey.java?rev=1130090&r1=1130089&r2=1130090&view=diff
==============================================================================
--- commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/net/SelectionKey.java
(original)
+++ commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/net/SelectionKey.java
Wed Jun  1 10:37:49 2011
@@ -126,7 +126,7 @@ public abstract class SelectionKey
      * Indicates whether this key's endpoint is interested in the read operation
      * and is ready to read. A call to this method is equal to executing
      * {@code (events() & OP_READ) == OP_READ} or by executing
-     * {@code (isSignaled(OP_READ).
+     * {@code (isSignaled(OP_READ)}.
      *
      * @return {@code true} if the endpoint is interested in the read operation
      *         and is ready to read, {@code false} otherwise.
@@ -140,7 +140,7 @@ public abstract class SelectionKey
      * Indicates whether this key's endpoint is interested in the read operation
      * and is ready to read. A call to this method is equal to executing
      * {@code (events() & OP_WRITE) == OP_WRITE} or by executing
-     * {@code (isSignaled(OP_WRITE).
+     * {@code (isSignaled(OP_WRITE)}.
      *
      * @return {@code true} if the endpoint is interested in the write operation
      *         and is ready to write, {@code false} otherwise.
@@ -155,7 +155,7 @@ public abstract class SelectionKey
      * operation and is ready to accept new connections.
      * A call to this method is equal to executing
      * {@code (events() & OP_ACCEPT) == OP_ACCEPT} or by executing
-     * {@code (isSignaled(OP_ACCEPT).
+     * {@code (isSignaled(OP_ACCEPT)}.
      * 
      * @return {@code true} if the endpoint is interested in the accept operation
      *         and is ready to accept new connections, {@code false} otherwise.
@@ -170,7 +170,7 @@ public abstract class SelectionKey
      * operation and is ready to connect.
      * A call to this method is equal to executing
      * {@code (events() & OP_CONNECT) == OP_CONNECT} or by executing
-     * {@code (isSignaled(OP_CONNECT).
+     * {@code (isSignaled(OP_CONNECT)}.
      *
      * @return {@code true} if the endpoint is interested in the connect operation
      *         and is ready to connect, {@code false} otherwise.

Modified: commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/net/SelectionKeyImpl.java
URL: http://svn.apache.org/viewvc/commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/net/SelectionKeyImpl.java?rev=1130090&r1=1130089&r2=1130090&view=diff
==============================================================================
--- commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/net/SelectionKeyImpl.java
(original)
+++ commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/net/SelectionKeyImpl.java
Wed Jun  1 10:37:49 2011
@@ -34,11 +34,11 @@ import org.apache.commons.runtime.Errno;
 final class SelectionKeyImpl extends SelectionKey
 {
 
-    public  int              ievents;
-    public  int              revents;
-    public  AbstractSelector selector;
-    public  Endpoint         endpoint;
-    public  volatile boolean selected;
+    public  int                         ievents;
+    public  int                         revents;
+    public  final AbstractSelector      selector;
+    public  Endpoint                    endpoint;
+    public  volatile boolean            selected;
 
     // Output selector events.
     //
@@ -123,7 +123,6 @@ final class SelectionKeyImpl extends Sel
     {
         revents  = 0;
         selected = false;
-        selector = null;
         endpoint = null;
     }
 }

Modified: commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/net/Selector.java
URL: http://svn.apache.org/viewvc/commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/net/Selector.java?rev=1130090&r1=1130089&r2=1130090&view=diff
==============================================================================
--- commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/net/Selector.java
(original)
+++ commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/net/Selector.java
Wed Jun  1 10:37:49 2011
@@ -51,7 +51,7 @@ public abstract class Selector implement
     /**
      * Creates a new {@code Selector} instance with the given size.
      *
-     * @param  selector size
+     * @param  size selector capacity.
      * @return the new socket selector.
      *
      * @throws InvalidRangeException if {@code size} is outside the



Mime
View raw message