Author: mturk Date: Thu Apr 16 14:32:06 2009 New Revision: 765652 URL: http://svn.apache.org/viewvc?rev=765652&view=rev Log: Use Java5 javadocs format
Modified: commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/CommandType.java commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/DirectByteBuffer.java commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/JavaVersion.java commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Pointer.java commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Pointer32.java commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Pointer64.java commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Properties.java commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/io/FileLockType.java commons/sandbox/runtime/trunk/src/main/native/test/testcase.c commons/sandbox/runtime/trunk/src/test/org/apache/commons/runtime/TestPrivate.java Modified: commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/CommandType.java URL: http://svn.apache.org/viewvc/commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/CommandType.java?rev=765652&r1=765651&r2=765652&view=diff ============================================================================== --- commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/CommandType.java (original) +++ commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/CommandType.java Thu Apr 16 14:32:06 2009 @@ -29,24 +29,24 @@ public enum CommandType { /** Use the shell to invoke the program. - * <br/>Defined integer value is: <code>0</code> + * <br/>Defined integer value is: {...@code 0} */ SHELLCMD( 0), /** Invoke the program directly, no copied env. - * <br/>Defined integer value is: <code>1</code> + * <br/>Defined integer value is: {...@code 1} */ PROGRAM( 1), /** Invoke the program, replicating our environment. - * <br/>Defined integer value is: <code>2</code> + * <br/>Defined integer value is: {...@code 2} */ PROGRAM_ENV( 2), /** Find program on PATH, use our environment. - * <br/>Defined integer value is: <code>3</code> + * <br/>Defined integer value is: {...@code 3} */ PROGRAM_PATH( 3), /** Use the shell to invoke the program, * replicating our environment. - * <br/>Defined integer value is: <code>4</code> + * <br/>Defined integer value is: {...@code 4} */ SHELLCMD_ENV( 4); @@ -64,11 +64,11 @@ return value; } - /** Return the <code>CommandType</code> matching the specified <code>value</code>. + /** Return the {...@code CommandType} matching the specified {...@code value}. * @param value Integer value matching one of the - * <code>CommandType</code> enums. - * @throws IllegalArgumentException if <code>value</code> does not match - * to and of the <code>CommandType</code> enums. + * {...@code CommandType} enums. + * @throws IllegalArgumentException if {...@code value} does not match + * to and of the {...@code CommandType} enums. */ public static CommandType valueOf(int value) throws IllegalArgumentException 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=765652&r1=765651&r2=765652&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 Thu Apr 16 14:32:06 2009 @@ -19,14 +19,17 @@ import java.nio.ByteBuffer; /** Manages direct ByteBuffers - * <br/><br/> + * <p> * <b>Warning:</b><br/>Using this class improperly 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. + * </p> + * <p> * Using this class methods on ByteBuffers that were not created by * DirectByteBuffer.allocate methods will almost certainly crash the * running JVM. + * </p> * @since Runtime 1.0 */ public final class DirectByteBuffer { @@ -64,7 +67,7 @@ * @return The ByteBuffer with allocated memory * * @throws OutOfMemoryError if memory cannot be allocated from the system. - * @throws IllegalArgumentException if <code>size</code> is invalid. + * @throws IllegalArgumentException if {...@code size} is invalid. */ public static ByteBuffer allocate(int size) throws OutOfMemoryError, IllegalArgumentException @@ -79,7 +82,7 @@ * @return The ByteBuffer with allocated memory * * @throws OutOfMemoryError if memory cannot be allocated from the system. - * @throws IllegalArgumentException if <code>size</code> is invalid. + * @throws IllegalArgumentException if {...@code size} is invalid. */ public static ByteBuffer allocateAndClear(int size) throws OutOfMemoryError, IllegalArgumentException @@ -89,27 +92,32 @@ /** * Allocate a new ByteBuffer array from memory. - * <br/><br/><b>Warning:</b><br/> + * <p> + * <b>Warning:</b><br/> * Allocated array elements share the same memory segment - * so the <code>free()</code> must be called only for a + * so the {...@code free()} must be called only for a * <b>first</b> returned array element since it contains the * start of the allocated memory pointer. - * <br/><br/>Memory is internally aligned to 8 byte boundary + * </p> + * <p> + * Memory is internally aligned to 8 byte boundary * meaning that there might be unused chunks of memory if * the requested sizes are not aligned to a specified boundary. - * <br/><br/> + * </p> + * <p> * For example if two ByteBuffers are allocated with sizes - * <code>2</code> and <code>3</code> the overall allocated - * memory will be <code>16</code> bytes because each requested + * {...@code 2} and {...@code 3} the overall allocated + * memory will be {...@code 16} bytes because each requested * size is aligned to 8 byte boundary. + * </p> * * @param sizes Array of lengths for each ByteBuffer. - * @param off Start offset of the <code>sizes</code> array. - * @param len The length of the <code>sizes</code> array to use. + * @param off Start offset of the {...@code sizes} array. + * @param len The length of the {...@code sizes} array to use. * @return The ByteBuffer array with allocated memory * * @throws OutOfMemoryError if memory cannot be allocated from the system. - * @throws IllegalArgumentException if <code>off</code> or <code>len</code> + * @throws IllegalArgumentException if {...@code off} or {...@code len} * is invalid. * @throws IndexOutOfBoundsException if copying would cause access of * data outside array bounds. @@ -123,22 +131,26 @@ /** * Allocate a new ByteBuffer array from memory. - * <br/><br/><b>Warning:</b><br/> + * </p> + * <b>Warning:</b><br/> * Allocated array elements share the same memory segment - * so the <code>free()</code> must be called only for a + * so the {...@code free()} must be called only for a * <b>first</b> returned array element since it contains the * start of the allocated memory pointer. - * <br/><br/>This method does the same as calling the: + * </p> + * <p> + * This method does the same as calling the: * <pre> * * DirectByteBuffer.allocate(sizes, 0, sizes.length); * * </pre> + * </p> * @param sizes Array of lengths for each ByteBuffer. * @return The ByteBuffer array with allocated memory * * @throws OutOfMemoryError if memory cannot be allocated from the system. - * @throws IllegalArgumentException if <code>off</code> or <code>len</code> + * @throws IllegalArgumentException if {...@code off} or {...@code len} * is invalid. */ public static ByteBuffer[] allocate(int sizes[]) @@ -150,18 +162,20 @@ /** * Allocate a new ByteBuffer array and set all of the memory * bytes to zero. - * <br/><br/><b>Warning:</b><br/> + * <p> + * <b>Warning:</b><br/> * Allocated array elements share the same memory segment - * so the <code>free()</code> must be called only for a + * so the {...@code free()} must be called only for a * <b>first</b> returned array element since it contains the * start of the allocated memory pointer. + * </p> * @param sizes Array of lengths for each ByteBuffer. - * @param off Start offset of the <code>sizes</code> array. - * @param len The length of the <code>sizes</code> array to use. + * @param off Start offset of the {...@code sizes} array. + * @param len The length of the {...@code sizes} array to use. * @return The ByteBuffer array with allocated memory * * @throws OutOfMemoryError if memory cannot be allocated from the system. - * @throws IllegalArgumentException if <code>off</code> or <code>len</code> + * @throws IllegalArgumentException if {...@code off} or {...@code len} * is invalid. * @throws IndexOutOfBoundsException if copying would cause access of * data outside array bounds. @@ -176,22 +190,26 @@ /** * Allocate a new ByteBuffer array and set all of the memory * bytes to zero. - * <br/><br/><b>Warning:</b><br/> + * <p> + * <b>Warning:</b><br/> * Allocated array elements share the same memory segment - * so the <code>free()</code> must be called only for a + * so the {...@code free()} must be called only for a * <b>first</b> returned array element since it contains the * start of the allocated memory pointer. - * <br/><br/>This method does the same as calling the: + * </p> + * <p> + * This method does the same as calling the: * <pre> * * DirectByteBuffer.allocateAndClear(sizes, 0, sizes.length); * * </pre> + * </p> * @param sizes Array of lengths for each ByteBuffer. * @return The ByteBuffer array with allocated memory * * @throws OutOfMemoryError if memory cannot be allocated from the system. - * @throws IllegalArgumentException if <code>off</code> or <code>len</code> + * @throws IllegalArgumentException if {...@code off} or {...@code len} * is invalid. */ public static ByteBuffer[] allocateAndClear(int sizes[]) @@ -202,22 +220,24 @@ /** * Allocate a new ByteBuffer from already allocated memory. - * <br/><br/><b>Warning:</b><br/> + * <p> + * <b>Warning:</b><br/> * Allocated memory must be provided from call to the - * <code>address</code> method or by some other valid method that returns - * the valid memory address. + * {...@code address} method or by some other valid method that returns + * the valid memory address.<br/> * Providing invalid value to this call will almost certainly crash the * running JVM because it represents the real memory address location and - * any operation on <code>ByteBuffer</code> will use it for internal storage + * any operation on {...@code ByteBuffer} will use it for internal storage * location. + * </p> * @param mem The 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>mem</code> is zero - * @throws IllegalArgumentException if <code>offset</code> or - * <code>size</code> are invalid. + * @throws NullPointerException if {...@code mem} is zero + * @throws IllegalArgumentException if {...@code offset} or + * {...@code size} are invalid. */ public static ByteBuffer allocate(long mem, int offset, int size) throws NullPointerException, IllegalArgumentException @@ -232,9 +252,9 @@ * @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>offset</code> or - * <code>size</code> are invalid. + * @throws NullPointerException if {...@code buf} is null + * @throws IllegalArgumentException if {...@code offset} or + * {...@code size} are invalid. */ public static ByteBuffer allocate(ByteBuffer buf, int offset, int size) throws NullPointerException, IllegalArgumentException @@ -244,12 +264,14 @@ /** * Deallocates or frees a memory block used by ByteBuffer. - * <br/><br/><b>Warning:</b><br/> + * <p> + * <b>Warning:</b><br/> * Invoke this method only on ByteBuffers - * that were created by <code>DirectByteBuffer.allocate</code> methods. + * that were created by {...@code DirectByteBuffer.allocate} methods. + * </p> * @param buf Previously allocated ByteBuffer to be deallocated. * - * @throws NullPointerException if <code>buf</code> is null + * @throws NullPointerException if {...@code buf} is null */ public static native void free(ByteBuffer buf) throws NullPointerException; @@ -272,8 +294,8 @@ * @param c The character to set * @param count Number of characters * - * @throws NullPointerException if <code>buf</code> is null - * @throws IllegalArgumentException if <code>count</code> is less then <code>1</code> + * @throws NullPointerException if {...@code buf} is null. + * @throws IllegalArgumentException if {...@code count} is less then {...@code 1}. * @throws IndexOutOfBoundsException if copying would cause access of * data outside ByteBuffer bounds. */ @@ -287,8 +309,8 @@ * @param dst The destination ByteBuffer. * @param length The number of bytes to be copied. * - * @throws NullPointerException if <code>src/code> or <code>dst/code> is null - * @throws IllegalArgumentException if <code>length</code> invalid + * @throws NullPointerException if {...@code src} or {...@code dst} is null + * @throws IllegalArgumentException if {...@code length} invalid * @throws IndexOutOfBoundsException if copying would cause access of * data outside ByteBuffer bounds. */ @@ -307,8 +329,8 @@ * @param dstPos Starting position in the source ByteBuffer. * @param length The number of bytes to be copied. * - * @throws NullPointerException if <code>src/code> or <code>dst/code> is null - * @throws IllegalArgumentException if <code>length</code> invalid + * @throws NullPointerException if {...@code src} or {...@code dst} is null + * @throws IllegalArgumentException if {...@code length} invalid * @throws IndexOutOfBoundsException if copying would cause access of * data outside ByteBuffer bounds. */ Modified: commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/JavaVersion.java URL: http://svn.apache.org/viewvc/commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/JavaVersion.java?rev=765652&r1=765651&r2=765652&view=diff ============================================================================== --- commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/JavaVersion.java (original) +++ commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/JavaVersion.java Thu Apr 16 14:32:06 2009 @@ -19,8 +19,9 @@ import java.util.Properties; /** - * Class that uses system properties to match <code>OS</code> class + * Class that uses system properties to match {...@link OS} class * for system name and processor. + * <p> * Used when extracting the native libraries from the .jar to find * the correct path of dynamic shared library * <pre> @@ -33,6 +34,7 @@ * /META-LIB/linux/x86_64/libacr.so * * </pre> + * </p> * * @see OS * @since Runtime 1.0 Modified: commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Pointer.java URL: http://svn.apache.org/viewvc/commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Pointer.java?rev=765652&r1=765651&r2=765652&view=diff ============================================================================== --- commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Pointer.java (original) +++ commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Pointer.java Thu Apr 16 14:32:06 2009 @@ -17,8 +17,9 @@ package org.apache.commons.runtime; /** Represents the Operating System C/C++ pointer. - * <br/><br/> + * <p> * <b>Warning:</b><br/>Using this class improperly may crash the running JVM. + * </p> * @since Runtime 1.0 */ public abstract class Pointer { @@ -35,18 +36,17 @@ private native void cleanup0() throws Throwable; - /** True if the Pointer is 64-bit. */ public static final boolean IS_64_BIT = OS.getDataModel() == 64 ? true : false; /** Long value of the internal pointer - * @return Internal pointer address casted to the <code>long</code>. + * @return Internal pointer address casted to the {...@code long}. */ public abstract long longValue(); /** Integer value of the internal pointer - * @return Internal pointer address casted to the <code>int</code>. + * @return Internal pointer address casted to the {...@code int}. * @throws ClassCastException if the running JVM is 64 bit. */ public abstract int intValue() @@ -55,8 +55,8 @@ /** * Called by the garbage collector when the object is destroyed. * The class will free internal resources allocated by the Operating system. - * @see java.lang.Object for datailed explanation. - * @throws Throwable the <code>Exception</code> raised by this method. + * @see Object#finalize() + * @throws Throwable the {...@code Exception} raised by this method. */ protected final void finalize() throws Throwable @@ -64,9 +64,20 @@ cleanup0(); } - public void testCleanup() + /** + * Free the allocated resource by the Operating system. + * <p> + * Note that {...@code Object.finalize()} method will call + * this function. However if the native code can block for + * long time explicit {...@code free()} should be called. + * </p> + * @see #finalize() + * @throws Throwable the {...@code Exception} raised by this method. + */ + public void free() throws Throwable { cleanup0(); } + } Modified: commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Pointer32.java URL: http://svn.apache.org/viewvc/commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Pointer32.java?rev=765652&r1=765651&r2=765652&view=diff ============================================================================== --- commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Pointer32.java (original) +++ commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Pointer32.java Thu Apr 16 14:32:06 2009 @@ -17,8 +17,9 @@ package org.apache.commons.runtime; /** Represents the Operating System 32-bit pointer C/C++ pointer. - * <br/><br/> + * <p> * <b>Warning:</b><br/>Using this class improperly may crash the running JVM. + * </p> * @since Runtime 1.0 */ class Pointer32 extends Pointer { Modified: commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Pointer64.java URL: http://svn.apache.org/viewvc/commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Pointer64.java?rev=765652&r1=765651&r2=765652&view=diff ============================================================================== --- commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Pointer64.java (original) +++ commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Pointer64.java Thu Apr 16 14:32:06 2009 @@ -17,8 +17,9 @@ package org.apache.commons.runtime; /** Represents the Operating System 32-bit pointer C/C++ pointer. - * <br/><br/> + * <p> * <b>Warning:</b><br/>Using this class improperly may crash the running JVM. + * </p> * @since Runtime 1.0 */ class Pointer64 extends Pointer { Modified: commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Properties.java URL: http://svn.apache.org/viewvc/commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Properties.java?rev=765652&r1=765651&r2=765652&view=diff ============================================================================== --- commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Properties.java (original) +++ commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Properties.java Thu Apr 16 14:32:06 2009 @@ -21,7 +21,7 @@ /** The Properties class is used to obtain the various * Apache Commons Runtime settings. Their default values are - * specified inside DefaultProperties.properties file. + * specified inside {...@code DefaultProperties.properties} file. * @since Runtime 1.0 * */ @@ -53,7 +53,7 @@ /** Get resource property value. * @param key Resource name to get. - * @param def Default value in case <code>key</code> was not found. + * @param def Default value in case {...@code key} was not found. */ public static String get(String key, String def) { @@ -72,7 +72,7 @@ /** Get resource property value. * @param key Resource name to get. In case the propery is not present - * this method returns <code>null</null>. + * this method returns {...@code null}. */ public static String get(String key) { Modified: commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/io/FileLockType.java URL: http://svn.apache.org/viewvc/commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/io/FileLockType.java?rev=765652&r1=765651&r2=765652&view=diff ============================================================================== --- commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/io/FileLockType.java (original) +++ commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/io/FileLockType.java Thu Apr 16 14:32:06 2009 @@ -26,18 +26,18 @@ /** Shared lock. More than one process or thread can hold a shared lock * at any given time. Essentially, this is a "read lock", preventing * writers from establishing an exclusive lock. - * <br/>Defined integer value is: <code>1</code> + * <br/>Defined integer value is: {...@code 1} */ SHARED( 1), /** Exclusive lock. Only one process may hold an exclusive lock at any * given time. This is analogous to a "write lock". - * <br/>Defined integer value is: <code>2</code> + * <br/>Defined integer value is: {...@code 2} */ EXCLUSIVE(2), - /** Do not block while acquiring the file lock - * <br/>Defined integer value is: <code>0x0010</code> + /** Do not block while acquiring the file lock. + * <br/>Defined integer value is: {...@code 0x0010} */ NONBLOCK( 0x0010); @@ -55,8 +55,8 @@ } /** Integer representing the sum of the integer values - * of the <code>FileLockType</code> enums. - * @param set The <code>EnumSet</code> which values to get. + * of the {...@code FileLockType} enums. + * @param set The {...@code EnumSet} which values to get. */ public static int bitmapOf(EnumSet<FileLockType> set) { @@ -68,10 +68,10 @@ return bitmap; } - /** Returns <code>EnumSet</code> of <code>FileLockType</code> enums + /** Returns {...@code EnumSet} of {...@code FileLockType} enums * from the integer bitmap value. - * @param value Integer used to construct the <code>EnumSet</code> - * with <code>FileLockType</code> values mathching the value flags. + * @param value Integer used to construct the {...@code EnumSet} + * with {...@code FileLockType} values mathching the value flags. */ public static EnumSet<FileLockType> valueOf(int value) { Modified: commons/sandbox/runtime/trunk/src/main/native/test/testcase.c URL: http://svn.apache.org/viewvc/commons/sandbox/runtime/trunk/src/main/native/test/testcase.c?rev=765652&r1=765651&r2=765652&view=diff ============================================================================== --- commons/sandbox/runtime/trunk/src/main/native/test/testcase.c (original) +++ commons/sandbox/runtime/trunk/src/main/native/test/testcase.c Thu Apr 16 14:32:06 2009 @@ -213,7 +213,7 @@ static void callback(void *p) { - fprintf(stderr, "Pointer callback called: %p\n", p); + fprintf(stderr, "[native] Pointer callback called: %p\n", p); fflush(stderr); } Modified: commons/sandbox/runtime/trunk/src/test/org/apache/commons/runtime/TestPrivate.java URL: http://svn.apache.org/viewvc/commons/sandbox/runtime/trunk/src/test/org/apache/commons/runtime/TestPrivate.java?rev=765652&r1=765651&r2=765652&view=diff ============================================================================== --- commons/sandbox/runtime/trunk/src/test/org/apache/commons/runtime/TestPrivate.java (original) +++ commons/sandbox/runtime/trunk/src/test/org/apache/commons/runtime/TestPrivate.java Thu Apr 16 14:32:06 2009 @@ -238,7 +238,7 @@ System.gc(); // This should be enough for a gc // from Pointer.finalize() - Thread.sleep(1000); + Thread.sleep(200); } public void testPointerGc() @@ -250,7 +250,7 @@ System.gc(); // This should be enough for a first invocation // from Pointer.finalize() - Thread.sleep(1000); + Thread.sleep(200); } }