harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r768919 [7/7] - in /harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio: ./ channels/ channels/spi/
Date Mon, 27 Apr 2009 10:23:38 GMT
Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/spi/AbstractSelectableChannel.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/spi/AbstractSelectableChannel.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/spi/AbstractSelectableChannel.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/spi/AbstractSelectableChannel.java
Mon Apr 27 10:23:36 2009
@@ -29,11 +29,9 @@
 import java.util.List;
 
 /**
- * Abstract class for selectable channels.
- * <p>
- * In this class, there are methods about registering/deregistering a channel,
- * about channel closing. It realize the multi-thread safe.
- * </p>
+ * {@code AbstractSelectableChannel} is the base implementation class for
+ * selectable channels. It declares methods for registering, unregistering and
+ * closing selectable channels. It is thread-safe.
  */
 public abstract class AbstractSelectableChannel extends SelectableChannel {
 
@@ -53,10 +51,10 @@
     boolean isBlocking = true;
 
     /**
-     * Constructor for this class.
+     * Constructs a new {@code AbstractSelectableChannel}.
      * 
      * @param selectorProvider
-     *            A instance of SelectorProvider
+     *            the selector provider that creates this channel.
      */
     protected AbstractSelectableChannel(SelectorProvider selectorProvider) {
         super();
@@ -64,10 +62,10 @@
     }
 
     /**
-     * Answer the SelectorProvider of this channel.
+     * Returns the selector provider that has created this channel.
      * 
      * @see java.nio.channels.SelectableChannel#provider()
-     * @return The provider of this channel.
+     * @return this channel's selector provider.
      */
     @Override
     public final SelectorProvider provider() {
@@ -75,7 +73,10 @@
     }
 
     /**
-     * @see java.nio.channels.SelectableChannel#isRegistered()
+     * Indicates whether this channel is registered with one or more selectors.
+     *
+     * @return {@code true} if this channel is registered with a selector,
+     *         {@code false} otherwise.
      */
     @Override
     synchronized public final boolean isRegistered() {
@@ -83,7 +84,12 @@
     }
 
     /**
-     * @see java.nio.channels.SelectableChannel#keyFor(java.nio.channels.Selector)
+     * Gets this channel's selection key for the specified selector.
+     *
+     * @param selector
+     *            the selector with which this channel has been registered.
+     * @return the selection key for the channel or {@code null} if this channel
+     *         has not been registered with {@code selector}.
      */
     @Override
     synchronized public final SelectionKey keyFor(Selector selector) {
@@ -97,18 +103,31 @@
     }
 
     /**
-     * Realize the register function.
-     * <p>
-     * It registers current channel to the selector, then answer the selection
-     * key. The channel must be open and the interest op set must be valid. If
-     * the current channel is already registered to the selector, the method
-     * only set the new interest op set; otherwise it will call the
-     * <code>register</code> in <code>selector</code>, and add the
relative
-     * key to the key set of the current channel.
-     * </p>
+     * Registers this channel with the specified selector for the specified
+     * interest set. If the channel is already registered with the selector, the
+     * {@link SelectionKey interest set} is updated to {@code interestSet} and
+     * the corresponding selection key is returned. If the channel is not yet
+     * registered, this method calls the {@code register} method of
+     * {@code selector} and adds the selection key to this channel's key set.
      * 
-     * @see java.nio.channels.SelectableChannel#register(java.nio.channels.Selector,
-     *      int, java.lang.Object)
+     * @param selector
+     *            the selector with which to register this channel.
+     * @param interestSet
+     *            this channel's {@link SelectionKey interest set}.
+     * @param attachment
+     *            the object to attach, can be {@code null}.
+     * @return the selection key for this registration.
+     * @throws CancelledKeyException
+     *             if this channel is registered but its key has been canceled.
+     * @throws ClosedChannelException
+     *             if this channel is closed.
+     * @throws IllegalArgumentException
+     *             if {@code interestSet} is not supported by this channel.
+     * @throws IllegalBlockingModeException
+     *             if this channel is in blocking mode.
+     * @throws IllegalSelectorException
+     *             if this channel does not have the same provider as the given
+     *             selector.
      */
     @Override
     public final SelectionKey register(Selector selector, int interestSet,
@@ -149,9 +168,13 @@
     }
 
     /**
-     * Implement the closing function.
+     * Implements the channel closing behavior. Calls
+     * {@code implCloseSelectableChannel()} first, then loops through the list
+     * of selection keys and cancels them, which unregisters this channel from
+     * all selectors it is registered with.
      * 
-     * @see java.nio.channels.spi.AbstractInterruptibleChannel#implCloseChannel()
+     * @throws IOException
+     *             if a problem occurs while closing the channel.
      */
     @Override
     synchronized protected final void implCloseChannel() throws IOException {
@@ -165,15 +188,19 @@
     }
 
     /**
-     * Implement the closing function of the SelectableChannel.
+     * Implements the closing function of the SelectableChannel. This method is
+     * called from {@code implCloseChannel()}.
      * 
      * @throws IOException
-     *             If some I/O exception occurred.
+     *             if an I/O exception occurs.
      */
     protected abstract void implCloseSelectableChannel() throws IOException;
 
     /**
-     * @see java.nio.channels.SelectableChannel#isBlocking()
+     * Indicates whether this channel is in blocking mode.
+     *
+     * @return {@code true} if this channel is blocking, {@code false}
+     *         otherwise.
      */
     @Override
     public final boolean isBlocking() {
@@ -183,7 +210,10 @@
     }
 
     /**
-     * @see java.nio.channels.SelectableChannel#blockingLock()
+     * Gets the object used for the synchronization of {@code register} and
+     * {@code configureBlocking}.
+     *
+     * @return the synchronization object.
      */
     @Override
     public final Object blockingLock() {
@@ -191,12 +221,23 @@
     }
 
     /**
-     * Set the blocking mode of this channel.
+     * Sets the blocking mode of this channel. A call to this method blocks if
+     * other calls to this method or to {@code register} are executing. The
+     * actual setting of the mode is done by calling
+     * {@code implConfigureBlocking(boolean)}.
      * 
      * @see java.nio.channels.SelectableChannel#configureBlocking(boolean)
      * @param blockingMode
-     *            <code>true</code> for blocking mode; <code>false</code>
-     *            for non-blocking mode.
+     *            {@code true} for setting this channel's mode to blocking,
+     *            {@code false} to set it to non-blocking.
+     * @return this channel.
+     * @throws ClosedChannelException
+     *             if this channel is closed.
+     * @throws IllegalBlockingModeException
+     *             if {@code block} is {@code true} and this channel has been
+     *             registered with at least one selector.
+     * @throws IOException
+     *             if an I/O error occurs.
      */
     @Override
     public final SelectableChannel configureBlocking(boolean blockingMode)
@@ -218,13 +259,13 @@
     }
 
     /**
-     * Implement the setting of blocking mode.
+     * Implements the setting of the blocking mode.
      * 
      * @param blockingMode
-     *            <code>true</code> for blocking mode; <code>false</code>
-     *            for non-blocking mode.
+     *            {@code true} for setting this channel's mode to blocking,
+     *            {@code false} to set it to non-blocking.
      * @throws IOException
-     *             If some I/O exception occurred.
+     *             if an I/O error occurs.
      */
     protected abstract void implConfigureBlocking(boolean blockingMode)
             throws IOException;

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/spi/AbstractSelectionKey.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/spi/AbstractSelectionKey.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/spi/AbstractSelectionKey.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/spi/AbstractSelectionKey.java
Mon Apr 27 10:23:36 2009
@@ -19,27 +19,29 @@
 import java.nio.channels.SelectionKey;
 
 /**
- * Abstract class for selection key.
- * <p>
- * The class takes charge of the validation and cancellation of key.
- * </p>
+ * {@code AbstractSelectionKey} is the base implementation class for selection keys.
+ * It implements validation and cancellation methods.
  */
 public abstract class AbstractSelectionKey extends SelectionKey {
 
     /*
-     * Package private for deregister method in AbstractSelector.
+     * package private for deregister method in AbstractSelector.
      */
     boolean isValid = true;
 
     /**
-     * Constructor for this class.
+     * Constructs a new {@code AbstractSelectionKey}.
      */
     protected AbstractSelectionKey() {
         super();
     }
 
     /**
-     * @see java.nio.channels.SelectionKey#isValid()
+     * Indicates whether this key is valid. A key is valid as long as it has not
+     * been canceled.
+     *
+     * @return {@code true} if this key has not been canceled, {@code false}
+     *         otherwise.
      */
     @Override
     public final boolean isValid() {
@@ -47,9 +49,10 @@
     }
 
     /**
-     * Cancels this key and adds it to the cancelled key set.
-     * 
-     * @see java.nio.channels.SelectionKey#cancel()
+     * Cancels this key.
+     * <p>
+     * A key that has been canceled is no longer valid. Calling this method on
+     * an already canceled key does nothing.
      */
     @Override
     public final void cancel() {

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/spi/SelectorProvider.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/spi/SelectorProvider.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/spi/SelectorProvider.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/spi/SelectorProvider.java
Mon Apr 27 10:23:36 2009
@@ -34,15 +34,14 @@
 import org.apache.harmony.nio.internal.SelectorProviderImpl;
 
 /**
- * Provider for nio selector and selectable channel.
+ * {@code SelectorProvider} is an abstract base class that declares methods for
+ * providing instances of {@link DatagramChannel}, {@link Pipe},
+ * {@link java.nio.channels.Selector} , {@link ServerSocketChannel}, and
+ * {@link SocketChannel}. All the methods of this class are thread-safe.
  * <p>
- * The provider can be got by system property or the configuration file in a jar
- * file, if not, the system default provider will return. The main function of
- * this class is to return the instance of implementation class of
- * <code>DatagramChannel</code>, <code>Pipe</code>, <code>Selector</code>
,
- * <code>ServerSocketChannel</code>, and <code>SocketChannel</code>.
All
- * the methods of this class are multi-thread safe.
- * </p>
+ * A provider instance can be retrieved through a system property or the
+ * configuration file in a jar file; if no provide is available that way then
+ * the system default provider is returned.
  */
 public abstract class SelectorProvider extends Object {
 
@@ -57,11 +56,11 @@
     private static Channel inheritedChannel;
 
     /**
-     * Constructor for this class.
+     * Constructs a new {@code SelectorProvider}.
      * 
      * @throws SecurityException
-     *             If there is a security manager, and it denies
-     *             RuntimePermission("selectorProvider").
+     *             if there is a security manager installed that does not permit
+     *             the runtime permission labeled "selectorProvider".
      */
     protected SelectorProvider() {
         super();
@@ -72,21 +71,20 @@
     }
 
     /**
-     * Get the provider by following steps in the first calling.
-     * <p>
+     * Gets a provider instance by executing the following steps when called for
+     * the first time:
      * <ul>
-     * <li> If the system property "java.nio.channels.spi.SelectorProvider" is
-     * set, the value of this property is the class name of the return provider.
-     * </li>
-     * <li>If there is a provider-configuration file named
-     * "java.nio.channels.spi.SelectorProvider" in META-INF/services of some jar
-     * file valid in the system class loader, the first class name is the return
-     * provider's class name. </li>
-     * <li> Otherwise, a system default provider will be returned. </li>
+     * <li> if the system property "java.nio.channels.spi.SelectorProvider" is
+     * set, the value of this property is the class name of the provider
+     * returned; </li>
+     * <li>if there is a provider-configuration file named
+     * "java.nio.channels.spi.SelectorProvider" in META-INF/services of a jar
+     * file valid in the system class loader, the first class name is the
+     * provider's class name; </li>
+     * <li> otherwise, a system default provider will be returned.</li>
      * </ul>
-     * </p>
-     * 
-     * @return The provider.
+     *
+     * @return the provider.
      */
     synchronized public static SelectorProvider provider() {
         if (null == provider) {
@@ -187,60 +185,61 @@
     }
 
     /**
-     * Create a new open <code>DatagramChannel</code>.
+     * Creates a new open {@code DatagramChannel}.
      * 
-     * @return The channel.
+     * @return the new channel.
      * @throws IOException
-     *             If some I/O exception occurred.
+     *             if an I/O error occurs.
      */
     public abstract DatagramChannel openDatagramChannel() throws IOException;
 
     /**
-     * Create a new <code>Pipe</code>.
+     * Creates a new {@code Pipe}.
      * 
-     * @return The pipe.
+     * @return the new pipe.
      * @throws IOException
-     *             If some I/O exception occurred.
+     *             if an I/O error occurs.
      */
     public abstract Pipe openPipe() throws IOException;
 
     /**
-     * Create a new selector.
+     * Creates a new selector.
      * 
-     * @return The selector.
+     * @return the new selector.
      * @throws IOException
-     *             If some I/O exception occurred.
+     *             if an I/O error occurs.
      */
     public abstract AbstractSelector openSelector() throws IOException;
 
     /**
-     * Create a new open <code>ServerSocketChannel</code>.
+     * Creates a new open {@code ServerSocketChannel}.
      * 
-     * @return The channel.
+     * @return the new channel.
      * @throws IOException
-     *             If some I/O exception occurred.
+     *             if an I/O error occurs.
      */
     public abstract ServerSocketChannel openServerSocketChannel()
             throws IOException;
 
     /**
-     * Create a new open <code>SocketChannel</code>.
+     * Create a new open {@code SocketChannel}.
      * 
-     * @return The channel.
+     * @return the new channel.
      * @throws IOException
-     *             If some I/O exception occurred.
+     *             if an I/O error occurs.
      */
     public abstract SocketChannel openSocketChannel() throws IOException;
 
     /**
-     * Answer the channel inherited from the instance which created this JVM.
+     * Returns the channel inherited from the instance that created this
+     * virtual machine.
      * 
-     * @return The channel.
+     * @return the channel.
      * @throws IOException
-     *             If some I/O exception occurred.
+     *             if an I/O error occurs.
      * @throws SecurityException
-     *             If there is a security manager, and it denies
-     *             RuntimePermission("selectorProvider").
+     *             if there is a security manager installed that does not permit
+     *             the runtime permission labeled "selectorProvider".
      */
     public Channel inheritedChannel() throws IOException {
         if (null == inheritedChannel) {



Mime
View raw message