You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by te...@apache.org on 2009/04/27 12:23:38 UTC
svn commit: r768919 [7/7] - in
/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio:
./ channels/ channels/spi/
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) {