Author: david.lloyd(a)jboss.com Date: 2008-02-22 11:50:40 -0500 (Fri, 22 Feb 2008) New Revision: 3482 Modified: remoting3/trunk/build.xml remoting3/trunk/util/src/main/java/org/jboss/cx/remoting/core/util/AttributeMap.java remoting3/trunk/util/src/main/java/org/jboss/cx/remoting/core/util/ByteInput.java remoting3/trunk/util/src/main/java/org/jboss/cx/remoting/core/util/ByteOutput.java remoting3/trunk/util/src/main/java/org/jboss/cx/remoting/core/util/MessageInput.java remoting3/trunk/util/src/main/java/org/jboss/cx/remoting/core/util/MessageOutput.java Log: Javadoc updates Modified: remoting3/trunk/build.xml =================================================================== --- remoting3/trunk/build.xml 2008-02-22 09:53:09 UTC (rev 3481) +++ remoting3/trunk/build.xml 2008-02-22 16:50:40 UTC (rev 3482) @@ -1197,16 +1197,20 @@ <!-- JAVADOCS --> <!-- ============================================== --> - <target name="api-javadoc" depends="api,util"> + <target name="api-javadoc" depends="api,core,log-jul,standalone,util"> <delete dir="api/target/main/docs"/> <mkdir dir="api/target/main/docs"/> <javadoc destdir="api/target/main/docs" author="false" version="false" use="false" windowtitle="JBoss Remoting API"> <packageset dir="api/src/main/java"/> <packageset dir="util/src/main/java"/> + <packageset dir="standalone/src/main/java"/> <doctitle><![CDATA[<h1>JBoss Remoting 3</h1>]]></doctitle> <bottom><![CDATA[<i>Copyright &#169; 2008 JBoss, a division of Red Hat, Inc.</i>]]></bottom> <link href="http://java.sun.com/j2se/1.5.0/docs/api/"/> - <classpath location="util/target/main/classes"/> + <classpath> + <path refid="log-jul.classpath"/> + <path refid="core.classpath"/> + </classpath> </javadoc> </target> Modified: remoting3/trunk/util/src/main/java/org/jboss/cx/remoting/core/util/AttributeMap.java =================================================================== --- remoting3/trunk/util/src/main/java/org/jboss/cx/remoting/core/util/AttributeMap.java 2008-02-22 09:53:09 UTC (rev 3481) +++ remoting3/trunk/util/src/main/java/org/jboss/cx/remoting/core/util/AttributeMap.java 2008-02-22 16:50:40 UTC (rev 3482) @@ -4,43 +4,142 @@ import java.util.Set; /** - * + * A map whose value types are determined by the key. */ public interface AttributeMap { + /** + * Get a value from the map. + * + * @param key the key + * @return the value + */ <T> T get(AttributeKey<T> key); + /** + * Store a value into the map. Any previous mapping for this value is overwritten. + * + * @param key the key + * @param value the new value + * @return the old value (may be {@code null}), or {@code null} if there was no mapping for this key + */ <T> T put(AttributeKey<T> key, T value); + /** + * Remove a mapping from the map. + * + * @param key the key + * @return the old value (may be {@code null}), or {@code null} if there was no mapping for this key + */ <T> T remove(AttributeKey<T> key); + /** + * Remove a mapping from the map. Both the key and value must match the values given. + * + * @param key the key + * @param value the value + * @return {@code true} if a matching mapping was located and removed + */ <T> boolean remove(AttributeKey<T> key, T value); + /** + * Store a value into the map if there is no value currently stored. + * + * @param key the key + * @param value the value + * @return the old value if there was a previous mapping + */ <T> T putIfAbsent(AttributeKey<T> key, T value); + /** + * Replace a mapping in the map. + * + * @param key the key + * @param oldValue the old value + * @param newValue the replacement value + * @return {@code true} if a matching mapping was located and replaced + */ <T> boolean replace(AttributeKey<T> key, T oldValue, T newValue); + /** + * Test the map for the presence of a key. + * + * @param key the key + * @return {@code true} if the key is present in the map + */ <T> boolean containsKey(AttributeKey<T> key); + /** + * Test the map for the presence of a value. + * + * @param value the value + * @return {@code true} if the value is present in the map + */ <T> boolean containsValue(T value); + /** + * Get all the map entries. + * + * @return the entries + */ Iterable<Entry<?>> entries(); + /** + * Get the key set for this map. The returned set supports all set operations except for {@code add} and {@code addAll}. + * + * @return the key set + */ Set<AttributeKey<?>> keySet(); + /** + * Get the collection of values for this map. + * + * @return the values + */ Collection<?> values(); + /** + * Determine whether this map is empty. + * + * @return {@code true} if the map has no mappings + */ boolean isEmpty(); + /** + * Determine the number of entries in the map. + * + * @return the number of entries + */ int size(); + /** + * Clear the map of all mappings. + */ void clear(); + /** + * An entry in the {@code AttributeMap}. + */ interface Entry<T> { + /** + * Get the entry key. + * + * @return the key + */ AttributeKey<T> getKey(); + /** + * Get the entry value. + * + * @return the value + */ T getValue(); + /** + * Change the entry value. + * + * @param newValue the new value + */ void setValue(T newValue); } } Modified: remoting3/trunk/util/src/main/java/org/jboss/cx/remoting/core/util/ByteInput.java =================================================================== --- remoting3/trunk/util/src/main/java/org/jboss/cx/remoting/core/util/ByteInput.java 2008-02-22 09:53:09 UTC (rev 3481) +++ remoting3/trunk/util/src/main/java/org/jboss/cx/remoting/core/util/ByteInput.java 2008-02-22 16:50:40 UTC (rev 3482) @@ -4,14 +4,41 @@ import java.io.IOException; /** - * + * A readable source of byte data. */ public interface ByteInput extends Closeable { + /** + * Read one byte. + * + * @return the byte, or -1 if the end of the stream has been reached. + * @throws IOException if an I/O error occurs + */ int read() throws IOException; + /** + * Read a series of bytes into an array. + * + * @param data the array into which data is to be read + * @return the total number of bytes read, or -1 if there are no bytes remaining to read + * @throws IOException if an I/O error occurs + */ int read(byte[] data) throws IOException; + /** + * Read a series of bytes into an array. + * + * @param data the array into which data is to be read + * @param offs the start offset in the {@code data} array at which the data is written + * @param len the maximum number of bytes to read + * @return the total number of bytes read, or -1 if there are no bytes remaining to read + * @throws IOException if an I/O error occurs + */ int read(byte[] data, int offs, int len) throws IOException; + /** + * Return the number of bytes remaining. + * + * @return the number of bytes, or -1 if the byte count cannot be determined + */ int remaining(); } Modified: remoting3/trunk/util/src/main/java/org/jboss/cx/remoting/core/util/ByteOutput.java =================================================================== --- remoting3/trunk/util/src/main/java/org/jboss/cx/remoting/core/util/ByteOutput.java 2008-02-22 09:53:09 UTC (rev 3481) +++ remoting3/trunk/util/src/main/java/org/jboss/cx/remoting/core/util/ByteOutput.java 2008-02-22 16:50:40 UTC (rev 3482) @@ -5,16 +5,48 @@ import java.io.IOException; /** - * + * A writable destination for byte data. */ public interface ByteOutput extends Closeable, Flushable { + /** + * Write a single byte of data. The input argument is truncated to 8 bits. + * + * @param b the byte to write + * @throws IOException if an I/O error occurs + */ void write(int b) throws IOException; + /** + * Write many bytes of data. + * + * @param b the bytes to write + * @throws IOException if an I/O error occurs + */ void write(byte[] b) throws IOException; + /** + * Write many bytes of data. + * + * @param b the bytes to write + * @param offs the offset in {@code b} to start reading bytes from + * @param len the number of bytes to write + * @throws IOException if an I/O error occurs + */ void write(byte[] b, int offs, int len) throws IOException; + /** + * Commit the written data. This causes the accumulated data to be sent as a message on the underlying + * channel. + * + * @throws IOException if an I/O error occurs + */ void commit() throws IOException; + /** + * Get a count of the number of bytes written to this message. + * + * @return the count + * @throws IOException if an I/O error occurs + */ int getBytesWritten() throws IOException; } Modified: remoting3/trunk/util/src/main/java/org/jboss/cx/remoting/core/util/MessageInput.java =================================================================== --- remoting3/trunk/util/src/main/java/org/jboss/cx/remoting/core/util/MessageInput.java 2008-02-22 09:53:09 UTC (rev 3481) +++ remoting3/trunk/util/src/main/java/org/jboss/cx/remoting/core/util/MessageInput.java 2008-02-22 16:50:40 UTC (rev 3482) @@ -4,10 +4,26 @@ import java.io.ObjectInput; /** - * + * A readable message. */ public interface MessageInput extends ByteInput, ObjectInput { + /** + * Read an object using the current context classloader, or, if there is no such classloader, the classloader + * which loaded this interface. + * + * @return the object from the message + * @throws ClassNotFoundException if the class of the object could not be resolved by the classloader + * @throws IOException if an I/O error occurs + */ Object readObject() throws ClassNotFoundException, IOException; + /** + * Read an object using the given classloader. + * + * @param loader the classloader to use + * @return the object from the message + * @throws ClassNotFoundException if the class of the object could not be resolved by the classloader + * @throws IOException if an I/O error occurs + */ Object readObject(ClassLoader loader) throws ClassNotFoundException, IOException; } Modified: remoting3/trunk/util/src/main/java/org/jboss/cx/remoting/core/util/MessageOutput.java =================================================================== --- remoting3/trunk/util/src/main/java/org/jboss/cx/remoting/core/util/MessageOutput.java 2008-02-22 09:53:09 UTC (rev 3481) +++ remoting3/trunk/util/src/main/java/org/jboss/cx/remoting/core/util/MessageOutput.java 2008-02-22 16:50:40 UTC (rev 3482) @@ -3,7 +3,7 @@ import java.io.ObjectOutput; /** - * + * A writable message. */ public interface MessageOutput extends ByteOutput, ObjectOutput { }