4:23 a.m.
Author: jmesnil
Date: 2009-12-08 05:23:43 -0500 (Tue, 08 Dec 2009)
New Revision: 8617
Added:
trunk/src/main/org/hornetq/core/buffers/package-info.java
Removed:
trunk/src/main/org/hornetq/core/buffers/package.html
Modified:
trunk/src/main/org/hornetq/core/buffers/HornetQBuffer.java
trunk/src/main/org/hornetq/core/buffers/HornetQBuffers.java
Log:
HORNETQ-186: fill in Javadocs for core API
* documented buffers API
Modified: trunk/src/main/org/hornetq/core/buffers/HornetQBuffer.java
===================================================================
--- trunk/src/main/org/hornetq/core/buffers/HornetQBuffer.java 2009-12-08 10:23:19 UTC
(rev 8616)
+++ trunk/src/main/org/hornetq/core/buffers/HornetQBuffer.java 2009-12-08 10:23:43 UTC
(rev 8617)
@@ -20,15 +20,22 @@
/**
*
- * A HornetQBuffer
+ * A HornetQBuffer wraps a Netty's ChannelBuffer and is used throughout HornetQ code
base.
*
* Much of it derived from Netty ChannelBuffer by Trustin Lee
*
* @author <a href="mailto:tim.fox@jboss.com">Tim Fox</a>
+ *
+ * @see HornetQBuffers
*
*/
public interface HornetQBuffer
{
+ /**
+ * Return the underlying Netty's ChannelBuffer
+ *
+ * @return the underlying Netty's ChannelBuffer
+ */
ChannelBuffer channelBuffer();
int capacity();
Modified: trunk/src/main/org/hornetq/core/buffers/HornetQBuffers.java
===================================================================
--- trunk/src/main/org/hornetq/core/buffers/HornetQBuffers.java 2009-12-08 10:23:19 UTC
(rev 8616)
+++ trunk/src/main/org/hornetq/core/buffers/HornetQBuffers.java 2009-12-08 10:23:43 UTC
(rev 8617)
@@ -20,20 +20,29 @@
import org.jboss.netty.buffer.ChannelBuffers;
/**
- *
- * A HornetQChannelBuffers
+ * Factory class to create HornetQBuffers
*
- * @author tim
- *
- *
+ * @author <a href="mailto:tim.fox@jboss.com">Tim Fox</a>
*/
public class HornetQBuffers
-{
- public static HornetQBuffer dynamicBuffer(final int estimatedLength)
+{
+ /**
+ * Create a <em>self-expanding</em> HornetQBuffer with the given initial
size
+ *
+ * @param size the initial size of the created HornetQBuffer
+ * @return a self-expanding HornetQBuffer starting with the given size
+ */
+ public static HornetQBuffer dynamicBuffer(final int size)
{
- return new ChannelBufferWrapper(ChannelBuffers.dynamicBuffer(estimatedLength));
+ return new ChannelBufferWrapper(ChannelBuffers.dynamicBuffer(size));
}
+ /**
+ * Create a <em>self-expanding</em> HornetQBuffer filled with the given
byte array
+ *
+ * @param bytes the created buffer will be initially filled with this byte array
+ * @return a self-expanding HornetQBuffer filled with the given byte array
+ */
public static HornetQBuffer dynamicBuffer(final byte[] bytes)
{
ChannelBuffer buff = ChannelBuffers.dynamicBuffer(bytes.length);
@@ -43,6 +52,14 @@
return new ChannelBufferWrapper(buff);
}
+ /**
+ * Create a HornetQBuffer wrapping the underlying NIO ByteBuffer
+ *
+ * The position on this buffer won't affect the position on the inner buffer
+ *
+ * @param underlying the underlying NIO ByteBuffer
+ * @return a HornetQBuffer wrapping the underlying NIO ByteBuffer
+ */
public static HornetQBuffer wrappedBuffer(final ByteBuffer underlying)
{
HornetQBuffer buff = new
ChannelBufferWrapper(ChannelBuffers.wrappedBuffer(underlying));
@@ -52,11 +69,23 @@
return buff;
}
+ /**
+ * Create a HornetQBuffer wrapping the underlying byte array
+ *
+ * @param underlying the underlying byte array
+ * @return a HornetQBuffer wrapping the underlying byte array
+ */
public static HornetQBuffer wrappedBuffer(final byte[] underlying)
{
return new ChannelBufferWrapper(ChannelBuffers.wrappedBuffer(underlying));
}
+ /**
+ * Create a <em>fixed</em> HornetQBuffer of the given size
+ *
+ * @param size the size of the created HornetQBuffer
+ * @return a fixed HornetQBuffer with the given size
+ */
public static HornetQBuffer fixedBuffer(final int size)
{
return new ChannelBufferWrapper(ChannelBuffers.buffer(size));
Copied: trunk/src/main/org/hornetq/core/buffers/package-info.java (from rev 8601,
trunk/src/main/org/hornetq/core/buffers/package.html)
===================================================================
--- trunk/src/main/org/hornetq/core/buffers/package-info.java (rev
0)
+++ trunk/src/main/org/hornetq/core/buffers/package-info.java 2009-12-08 10:23:43 UTC (rev
8617)
@@ -0,0 +1,32 @@
+/*
+ * Copyright 2009 Red Hat, Inc.
+ * Red Hat licenses this file to you under the Apache License, version
+ * 2.0 (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ * implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+/**
+ * HornetQ Buffering.
+ *
+ * This package defines the buffers used by HornetQ. The underlying implementations uses
+ * Netty's ChannelBuffer and wraps it with methods required by HornetQ usage.
+ *
+ * ChannelBuffer differs from {@link java.nio.ByteBuffer} in two ways:
+ * <ol>
+ * <li>it is possible to interface almost directly with byte arrays, what is
faster</li>
+ * <li>there are two positions, one for reading, and one for writing. Hence you
will find methods to read from the buffer
+ * and methods to write to the buffer</li>
+ * </ol>
+ *
+ * <h2>Usage</h2>
+ *
+ * Always use the static methods declared at {@link
org.hornetq.core.buffers.HornetQBuffers} to create the buffers.
+*/
+package org.hornetq.core.buffers;
+
Deleted: trunk/src/main/org/hornetq/core/buffers/package.html
===================================================================
--- trunk/src/main/org/hornetq/core/buffers/package.html 2009-12-08 10:23:19 UTC (rev
8616)
+++ trunk/src/main/org/hornetq/core/buffers/package.html 2009-12-08 10:23:43 UTC (rev
8617)
@@ -1,46 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-<html>
- <head>
- <!--
-
- JBoss: The OpenSource J2EE WebOS
-
- Distributable under LGPL license.
- See terms of license at gnu.org.
-
- -->
- </head>
- <body>
-
-<h2>HornetQ Buffering</h2>
-
-
-<p>This package is a stripped down version of org.jboss.netty.buffer, and we kept
only what we needed for HornetQ buffers.</p>
-
-<p>ChannelBuffer differs from java.nio.ByteBuffer in two ways:</p>
-
-<p>- It's possible to interface almost directly with byte arrays, what is
faster</p>
-
-<p>- There are two positions, one for reading, and one for writing. Hence you will
find methods for read, and methods for writing</p>
-
-<h2>Usage</h2>
-
-<p> Always use the static methods declared at
org.hornetq.core.buffers.ChannelBuffers to create the buffers you need: </p>
-
-
-<p> buffer(int capacity) - This method will create a fixed size MessagingBuffer
</p>
-
-<p> dynamicBuffer(final int estimatedLength) - This method will create a
SelfExpandable MessagingBuffer </p>
-
-<p> dynamicBuffer(final byte[] initialBuffer) - This method will create a
SelfExpandable MessagingBuffer, but reusing the initialBuffer. Be careful though, the
reference will be directly used on the createdBuffer. If your buffer will be used by other
operations, you should instead create a new buffer and perform a write. </p>
-
-<p> buffer(final int capacity) - This method will create a fixed size
MessagingBuffer </p>
-
-<p> wrappedBuffer(final byte[] array) - It will wrap a byte[] on a Buffer, with
writePosition at the end, and readPosition at 0 </p>
-
-<p> wrappedBuffer(final ByteBuffer buffer) - It will wrap a Bytebuffer on a
MessagingBuffer. The position on this buffer won't affect the position on the inner
buffer </p>
-
-
-
- </body>
-</html>
\ No newline at end of file