Author: mturk
Date: Tue Apr 14 17:53:43 2009
New Revision: 764903
URL: http://svn.apache.org/viewvc?rev=764903&view=rev
Log:
Add some more docs
Modified:
commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/DirectByteBuffer.java
Modified:
commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/DirectByteBuffer.java
URL:
http://svn.apache.org/viewvc/commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/DirectByteBuffer.java?rev=764903&r1=764902&r2=764903&view=diff
==============================================================================
---
commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/DirectByteBuffer.java
(original)
+++
commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/DirectByteBuffer.java
Tue Apr 14 17:53:43 2009
@@ -20,10 +20,14 @@
/** DirectByteBuffer
* <br/>
- * <b>Warning</b>: Using this class impropery may crash the running JVM.
+ * <b>Warning</b> Using this class impropery may crash the running JVM.
* Any method call after free method was called might write or read from
* the memory location that has been already allocated for
* something else.
+ * <br />
+ * Using this class methods on ByteBuffers that were not created by
+ * DirectByteBuffer.allocate methods will almost certainly crash the
+ * running JVM.
* @author Mladen Turk
*/
public final class DirectByteBuffer {
@@ -51,6 +55,9 @@
* Allocate a new ByteBuffer from memory
* @param size The amount of memory to allocate
* @return The ByteBuffer with allocated memory
+ *
+ * @throws OutOfMemoryError if memory cannot be allocated from the system.
+ * @throws IllegalArgumentException if <code>size</code> is invalid.
*/
public static ByteBuffer allocate(int size)
throws OutOfMemoryError, IllegalArgumentException
@@ -62,6 +69,9 @@
* Allocate a new ByteBuffer from memory and set all of the memory to 0
* @param size Length in bytes of each element.
* @return The ByteBuffer with allocated memory
+ *
+ * @throws OutOfMemoryError if memory cannot be allocated from the system.
+ * @throws IllegalArgumentException if <code>size</code> is invalid.
*/
public static ByteBuffer allocateAndInitToZero(int size)
throws OutOfMemoryError, IllegalArgumentException
@@ -77,6 +87,10 @@
* @param offset Offset from the memory to use
* @param size The amount of memory to use
* @return The ByteBuffer with attached memory
+ *
+ * @throws NullPointerException if <code>mem</code> is zero
+ * @throws IllegalArgumentException if <code>offest</code> or
+ * <code>size</code> are invalid.
*/
public static ByteBuffer allocate(long mem, int offset, int size)
throws NullPointerException, IllegalArgumentException
@@ -86,22 +100,28 @@
/**
* Allocate a new ByteBuffer from already allocated ByteBuffer.
- * @param b The ByteBuffer whos memory to use
+ * @param buf The ByteBuffer whos memory to use
* @param offset Offset from the memory to use
* @param size The amount of memory to use
* @return The ByteBuffer with attached memory
+ *
+ * @throws NullPointerException if <code>buf</code> is null
+ * @throws IllegalArgumentException if <code>offest</code> or
+ * <code>size</code> are invalid.
*/
- public static ByteBuffer allocate(ByteBuffer b, int offset, int size)
+ public static ByteBuffer allocate(ByteBuffer buf, int offset, int size)
throws NullPointerException, IllegalArgumentException
{
- return attach(address(b), offset, size);
+ return attach(address(buf), offset, size);
}
/**
* Deallocates or frees a memory block used by ByteBuffer
- * <br /><b>Warning :</b> Call this method only on ByteBuffers
- * that were created by calling allocate.
+ * <br /><b>Warning</b> Call this method only on ByteBuffers
+ * that were created by DirectByteBuffer.allocate methods.
* @param buf Previously allocated ByteBuffer to be freed.
+ *
+ * @throws NullPointerException if <code>buf</code> is null
*/
public static native void free(ByteBuffer buf)
throws NullPointerException;
@@ -123,6 +143,11 @@
* @param b The ByteBuffer to use
* @param c The character to set
* @param count Number of characters
+ *
+ * @throws NullPointerException if source is null
+ * @throws IllegalArgumentException if <code>count</code> is less then
<code>1</code>
+ * @throws IOIndexOutOfBoundsException if copying would cause access of
+ * data outside ByteBuffer bounds.
*/
public static native void set(ByteBuffer b, int c, int count)
throws NullPointerException, IllegalArgumentException,
@@ -133,6 +158,11 @@
* @param src The source ByteBuffer.
* @param dst The destination ByteBuffer.
* @param length The number of bytes to be copied.
+ *
+ * @throws NullPointerException if source or destination is null
+ * @throws IllegalArgumentException if length invalid
+ * @throws IOIndexOutOfBoundsException if copying would cause access of
+ * data outside ByteBuffer bounds.
*/
public static void copy(ByteBuffer src, ByteBuffer dst, int length)
throws NullPointerException, IllegalArgumentException,
@@ -148,6 +178,11 @@
* @param dst The destination ByteBuffer.
* @param dstPos Starting position in the source ByteBuffer.
* @param length The number of bytes to be copied.
+ *
+ * @throws NullPointerException if source or destination is null
+ * @throws IllegalArgumentException if length invalid
+ * @throws IOIndexOutOfBoundsException if copying would cause access of
+ * data outside ByteBuffer bounds.
*/
public static void copy(ByteBuffer src, int srcPos, ByteBuffer dst,
int dstPos, int length)
