Author: mheath
Date: Sat Jan 20 13:52:41 2007
New Revision: 498184
URL: http://svn.apache.org/viewvc?view=rev&rev=498184
Log:
Updated JavaDocs. Added better ExecutorService support.
Modified:
mina/sandbox/mheath/aioj/trunk/src/main/java/org/apache/aio/AsynchronousFileChannel.java
mina/sandbox/mheath/aioj/trunk/src/main/java/org/apache/aio/AsynchronousFileChannelFactory.java
mina/sandbox/mheath/aioj/trunk/src/main/java/org/apache/aio/AsynchronousFileChannelProvider.java
Modified:
mina/sandbox/mheath/aioj/trunk/src/main/java/org/apache/aio/AsynchronousFileChannel.java
URL:
http://svn.apache.org/viewvc/mina/sandbox/mheath/aioj/trunk/src/main/java/org/apache/aio/AsynchronousFileChannel.java?view=diff&rev=498184&r1=498183&r2=498184
==============================================================================
---
mina/sandbox/mheath/aioj/trunk/src/main/java/org/apache/aio/AsynchronousFileChannel.java
(original)
+++
mina/sandbox/mheath/aioj/trunk/src/main/java/org/apache/aio/AsynchronousFileChannel.java
Sat Jan 20 13:52:41 2007
@@ -20,57 +20,101 @@
package org.apache.aio;
import java.nio.ByteBuffer;
+import java.nio.channels.Channel;
import java.nio.channels.FileLock;
import java.util.concurrent.ExecutionException;
-public abstract class AsynchronousFileChannel {
+/**
+ * A channel for reading, writing and manipulating a file in an asynchronous
manner.
+ *
+ * <p>All operations done using an asynchronous file channel are done in
non-blocking fashion. An asynchronous file
+ * channel may read, write, lock access by other programs and truncate the
length of a file. When bytes are written
+ * past the length of the file, the file size increases.
+ *
+ * <p>All asynchronous methods defined by this class return a [EMAIL
PROTECTED] AioFuture} representing the pending result of the
+ * operation. Unless otherwise stated, if an operation fails because of an
I/O error then the AioFuture's get method
+ * will throw an [EMAIL PROTECTED] AioCallbackException}. One or more [EMAIL
PROTECTED] AioCompletionHandler completion handlers} may be
+ * registered with the returned AioFuture. The completion handlers are called
when the opertion completes regardless
+ * if it completes successfully or not.
+ *
+ * <p>Multiple operations may be outstanding at any given time. When multiple
operations are outstanding, the
+ * completion order is not specified. Completion handlers are not guaranteed
to execute in the order that operations
+ * were initiated or order in which they were added to the AioFuture.
+ *
+ * <p>Asynchronous file channels may be used concurrently by multiple threads.
The [EMAIL PROTECTED] #close} method may be
+ * invoked at any time. This causes all outstanding operations to complete by
throwing an
+ * [EMAIL PROTECTED] AioCallbackException}.
+ *
+ * @author mheath
+ */
+public abstract class AsynchronousFileChannel implements Channel {
+
+ /**
+ * Indicates if the file was opened for reading.
+ *
+ * @return True if the file was opened for reading, false otherwise.
+ */
+ public abstract boolean isReadable() throws AioException;
+
+ /**
+ * Indicates if the file was opened for writing.
+ *
+ * @return True if the file was opened for writing, false otherwise.
+ */
+ public abstract boolean isWriteable() throws AioException;
+
+ /**
+ * Return's the current size of the channel's file.
+ *
+ * @return The current size of the channel's file mesuared in bytes.
+ */
+ public abstract long size() throws AioException;
+
+ /**
+ * Acquires an exclusive lock on this channel's file.
+ *
+ * <p>An invocation of this method of the form <tt>afc.lock()</tt> behaves
+ * in exactly the same way as the invocation
+ *
+ * <pre>
+ * [EMAIL PROTECTED] #lock(long,long,boolean) lock}(0L, Long.MAX_VALUE,
false)
+ * </pre>
+ *
+ * @return A <tt>AioLockFuture</tt> object representing the pending result.
+ */
+ public AioLockFuture lock() {
+ return lock(0L, Long.MAX_VALUE, false);
+ }
+
+ public abstract AioLockFuture lock(long position, long size, boolean
shared);
+
+ public abstract FileLock tryLock();
+
+ public abstract FileLock tryLock(long position, long size, boolean shared);
+
+ public abstract AioSyncFuture sync();
+
+ public abstract AioByteBufferFuture read(ByteBuffer buffer, long position);
+
+ public AioBatchFuture read(ByteBufferPosition... byteBufferPositions) {
+ return read(byteBufferPositions, 0, byteBufferPositions.length);
+ }
+
+ public abstract AioBatchFuture read(ByteBufferPosition[]
byteBufferPositions, int offset, int length);
+
+ public abstract AioByteBufferFuture write(ByteBuffer buffer, long
position);
+
+ public AioBatchFuture write(ByteBufferPosition... byteBufferPositions) {
+ return write(byteBufferPositions, 0, byteBufferPositions.length);
+ }
+
+ public abstract AioBatchFuture write(ByteBufferPosition[]
byteBufferPositions, int offset, int length);
+
+ public static void suspend(AioFuture... futures) throws
InterruptedException, ExecutionException {
+ for (AioFuture future : futures) {
+ future.get();
+ }
+ }
- private AioExceptionHandler exceptionHandler;
-
- public abstract boolean isReadable();
-
- public abstract boolean isWriteable();
-
- public abstract long size();
-
- public abstract AioLockFuture lock();
-
- public abstract AioLockFuture lock(long position, long size, boolean
shared);
-
- public abstract FileLock tryLock();
-
- public abstract FileLock tryLock(long position, long size, boolean
shared);
-
- public abstract AioSyncFuture sync();
-
- public abstract AioByteBufferFuture read(ByteBuffer buffer, long
position);
-
- public AioBatchFuture read(ByteBufferPosition... byteBufferPositions) {
- return read(byteBufferPositions, 0, byteBufferPositions.length);
- }
-
- public abstract AioBatchFuture read(ByteBufferPosition[]
byteBufferPositions, int offset, int length);
-
- public abstract AioByteBufferFuture write(ByteBuffer buffer, long
position);
-
- public AioBatchFuture write(ByteBufferPosition... byteBufferPositions) {
- return write(byteBufferPositions, 0,
byteBufferPositions.length);
- }
-
- public abstract AioBatchFuture write(ByteBufferPosition[]
byteBufferPositions, int offset, int length);
-
- public void suspend(AioFuture... futures) throws InterruptedException,
ExecutionException {
- for (AioFuture future : futures) {
- future.get();
- }
- }
-
- public AioExceptionHandler getExceptionHandler() {
- return exceptionHandler;
- }
-
- public void setExceptionHandler(AioExceptionHandler exceptionHandler) {
- this.exceptionHandler = exceptionHandler;
- }
-
+ public abstract TruncateFuture truncate(long size);
}
Modified:
mina/sandbox/mheath/aioj/trunk/src/main/java/org/apache/aio/AsynchronousFileChannelFactory.java
URL:
http://svn.apache.org/viewvc/mina/sandbox/mheath/aioj/trunk/src/main/java/org/apache/aio/AsynchronousFileChannelFactory.java?view=diff&rev=498184&r1=498183&r2=498184
==============================================================================
---
mina/sandbox/mheath/aioj/trunk/src/main/java/org/apache/aio/AsynchronousFileChannelFactory.java
(original)
+++
mina/sandbox/mheath/aioj/trunk/src/main/java/org/apache/aio/AsynchronousFileChannelFactory.java
Sat Jan 20 13:52:41 2007
@@ -21,6 +21,7 @@
import java.util.EnumSet;
import java.util.Properties;
+import java.util.concurrent.ExecutorService;
import org.apache.aio.concurrent.ConcurrentAsynchronousFileChannelProvider;
import org.apache.aio.posix.PosixAsynchronousFileChannelProvider;
@@ -43,11 +44,15 @@
}
public static AioOpenFuture open(String fileName, EnumSet<Flags> flags) {
- return open(fileName, flags, System.getProperties());
+ return open(fileName, flags, null);
+ }
+
+ public static AioOpenFuture open(String fileName, EnumSet<Flags> flags,
ExecutorService executorService) {
+ return open(fileName, flags, executorService, System.getProperties());
}
@SuppressWarnings("unchecked")
- public static AioOpenFuture open(final String fileName, final
EnumSet<Flags> flags, final Properties properties) {
+ public static AioOpenFuture open(final String fileName, final
EnumSet<Flags> flags, ExecutorService executorService, final Properties
properties) {
String systemProvider = System.getProperty(
PROPERTY_ASYNCHRONOUS_FILE_CHANNEL_PROVIDER,
asynchronousFileChannelProvider);
@@ -55,7 +60,7 @@
try {
Class<? extends AsynchronousFileChannelProvider> clazz = (Class<?
extends AsynchronousFileChannelProvider>)Class.forName(providerName);
AsynchronousFileChannelProvider provider = clazz.newInstance();
- return provider.open(fileName, flags, properties);
+ return provider.open(fileName, flags, executorService, properties);
} catch (ClassNotFoundException e) {
throw new AioException(e);
} catch (InstantiationException e) {
Modified:
mina/sandbox/mheath/aioj/trunk/src/main/java/org/apache/aio/AsynchronousFileChannelProvider.java
URL:
http://svn.apache.org/viewvc/mina/sandbox/mheath/aioj/trunk/src/main/java/org/apache/aio/AsynchronousFileChannelProvider.java?view=diff&rev=498184&r1=498183&r2=498184
==============================================================================
---
mina/sandbox/mheath/aioj/trunk/src/main/java/org/apache/aio/AsynchronousFileChannelProvider.java
(original)
+++
mina/sandbox/mheath/aioj/trunk/src/main/java/org/apache/aio/AsynchronousFileChannelProvider.java
Sat Jan 20 13:52:41 2007
@@ -21,6 +21,7 @@
import java.util.EnumSet;
import java.util.Properties;
+import java.util.concurrent.ExecutorService;
public interface AsynchronousFileChannelProvider {
@@ -32,6 +33,6 @@
* @param properties
* @return
*/
- public AioOpenFuture open(final String fileName, final EnumSet<Flags>
flags, final Properties properties);
+ public AioOpenFuture open(final String fileName, final EnumSet<Flags>
flags, ExecutorService executorService, final Properties properties);
}
