You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mina.apache.org by el...@apache.org on 2015/12/17 20:46:56 UTC
mina git commit: Some more Javadoc fixes
Repository: mina
Updated Branches:
refs/heads/2.0 b0958bd5b -> 970c4a76f
Some more Javadoc fixes
Project: http://git-wip-us.apache.org/repos/asf/mina/repo
Commit: http://git-wip-us.apache.org/repos/asf/mina/commit/970c4a76
Tree: http://git-wip-us.apache.org/repos/asf/mina/tree/970c4a76
Diff: http://git-wip-us.apache.org/repos/asf/mina/diff/970c4a76
Branch: refs/heads/2.0
Commit: 970c4a76fc4c4bb3414f23b28dd06f67cd6290f9
Parents: b0958bd
Author: Emmanuel Lécharny <el...@symas.com>
Authored: Thu Dec 17 20:11:27 2015 +0100
Committer: Emmanuel Lécharny <el...@symas.com>
Committed: Thu Dec 17 20:11:27 2015 +0100
----------------------------------------------------------------------
.../main/java/org/apache/mina/core/IoUtil.java | 8 +++
.../mina/core/buffer/CachedBufferAllocator.java | 4 +-
.../mina/core/buffer/IoBufferAllocator.java | 5 ++
.../apache/mina/core/filterchain/IoFilter.java | 60 +++++++++++---------
.../mina/core/filterchain/IoFilterChain.java | 3 +
.../apache/mina/core/service/IoAcceptor.java | 39 +++++++++++--
6 files changed, 83 insertions(+), 36 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/mina/blob/970c4a76/mina-core/src/main/java/org/apache/mina/core/IoUtil.java
----------------------------------------------------------------------
diff --git a/mina-core/src/main/java/org/apache/mina/core/IoUtil.java b/mina-core/src/main/java/org/apache/mina/core/IoUtil.java
index f745557..6a70ad7 100644
--- a/mina-core/src/main/java/org/apache/mina/core/IoUtil.java
+++ b/mina-core/src/main/java/org/apache/mina/core/IoUtil.java
@@ -66,6 +66,10 @@ public class IoUtil {
* Writes the specified {@code message} to the specified {@code sessions}.
* If the specified {@code message} is an {@link IoBuffer}, the buffer is
* automatically duplicated using {@link IoBuffer#duplicate()}.
+ *
+ * @param message The message to write
+ * @param sessions The sessions the message has to be written to
+ * @return The list of {@link WriteFuture} for the written messages
*/
public static List<WriteFuture> broadcast(Object message, Iterator<IoSession> sessions) {
List<WriteFuture> answer = new ArrayList<WriteFuture>();
@@ -77,6 +81,10 @@ public class IoUtil {
* Writes the specified {@code message} to the specified {@code sessions}.
* If the specified {@code message} is an {@link IoBuffer}, the buffer is
* automatically duplicated using {@link IoBuffer#duplicate()}.
+ *
+ * @param message The message to write
+ * @param sessions The sessions the message has to be written to
+ * @return The list of {@link WriteFuture} for the written messages
*/
public static List<WriteFuture> broadcast(Object message, IoSession... sessions) {
if (sessions == null) {
http://git-wip-us.apache.org/repos/asf/mina/blob/970c4a76/mina-core/src/main/java/org/apache/mina/core/buffer/CachedBufferAllocator.java
----------------------------------------------------------------------
diff --git a/mina-core/src/main/java/org/apache/mina/core/buffer/CachedBufferAllocator.java b/mina-core/src/main/java/org/apache/mina/core/buffer/CachedBufferAllocator.java
index 68ad19e..30b47aa 100644
--- a/mina-core/src/main/java/org/apache/mina/core/buffer/CachedBufferAllocator.java
+++ b/mina-core/src/main/java/org/apache/mina/core/buffer/CachedBufferAllocator.java
@@ -116,7 +116,7 @@ public class CachedBufferAllocator implements IoBufferAllocator {
}
/**
- * Returns the maximum number of buffers with the same capacity per thread.
+ * @return the maximum number of buffers with the same capacity per thread.
* <tt>0</tt> means 'no limitation'.
*/
public int getMaxPoolSize() {
@@ -124,7 +124,7 @@ public class CachedBufferAllocator implements IoBufferAllocator {
}
/**
- * Returns the maximum capacity of a cached buffer. A buffer whose
+ * @return the maximum capacity of a cached buffer. A buffer whose
* capacity is bigger than this value is not pooled. <tt>0</tt> means
* 'no limitation'.
*/
http://git-wip-us.apache.org/repos/asf/mina/blob/970c4a76/mina-core/src/main/java/org/apache/mina/core/buffer/IoBufferAllocator.java
----------------------------------------------------------------------
diff --git a/mina-core/src/main/java/org/apache/mina/core/buffer/IoBufferAllocator.java b/mina-core/src/main/java/org/apache/mina/core/buffer/IoBufferAllocator.java
index 229cf1e..727285d 100644
--- a/mina-core/src/main/java/org/apache/mina/core/buffer/IoBufferAllocator.java
+++ b/mina-core/src/main/java/org/apache/mina/core/buffer/IoBufferAllocator.java
@@ -34,6 +34,7 @@ public interface IoBufferAllocator {
* @param capacity the capacity of the buffer
* @param direct <tt>true</tt> to get a direct buffer,
* <tt>false</tt> to get a heap buffer.
+ * @return The allocated {@link IoBuffer}
*/
IoBuffer allocate(int capacity, boolean direct);
@@ -43,11 +44,15 @@ public interface IoBufferAllocator {
* @param capacity the capacity of the buffer
* @param direct <tt>true</tt> to get a direct buffer,
* <tt>false</tt> to get a heap buffer.
+ * @return The allocated {@link ByteBuffer}
*/
ByteBuffer allocateNioBuffer(int capacity, boolean direct);
/**
* Wraps the specified NIO {@link ByteBuffer} into MINA buffer.
+ *
+ * @param The {@link ByteBuffer} to wrap
+ * @return The {@link IoBuffer} wrapping the {@link ByteBuffer}
*/
IoBuffer wrap(ByteBuffer nioBuffer);
http://git-wip-us.apache.org/repos/asf/mina/blob/970c4a76/mina-core/src/main/java/org/apache/mina/core/filterchain/IoFilter.java
----------------------------------------------------------------------
diff --git a/mina-core/src/main/java/org/apache/mina/core/filterchain/IoFilter.java b/mina-core/src/main/java/org/apache/mina/core/filterchain/IoFilter.java
index f7deaa0..c88c1cd 100644
--- a/mina-core/src/main/java/org/apache/mina/core/filterchain/IoFilter.java
+++ b/mina-core/src/main/java/org/apache/mina/core/filterchain/IoFilter.java
@@ -82,6 +82,8 @@ public interface IoFilter {
* is added to a {@link IoFilterChain} at the first time, so you can
* initialize shared resources. Please note that this method is never
* called if you don't wrap a filter with {@link ReferenceCountingFilter}.
+ *
+ * @throws Exception If an error occurred while processing the event
*/
void init() throws Exception;
@@ -90,6 +92,8 @@ public interface IoFilter {
* is not used by any {@link IoFilterChain} anymore, so you can destroy
* shared resources. Please note that this method is never called if
* you don't wrap a filter with {@link ReferenceCountingFilter}.
+ *
+ * @throws Exception If an error occurred while processing the event
*/
void destroy() throws Exception;
@@ -103,6 +107,7 @@ public interface IoFilter {
* @param name the name assigned to this filter
* @param nextFilter the {@link NextFilter} for this filter. You can reuse
* this object until this filter is removed from the chain.
+ * @throws Exception If an error occurred while processing the event
*/
void onPreAdd(IoFilterChain parent, String name, NextFilter nextFilter) throws Exception;
@@ -116,6 +121,7 @@ public interface IoFilter {
* @param name the name assigned to this filter
* @param nextFilter the {@link NextFilter} for this filter. You can reuse
* this object until this filter is removed from the chain.
+ * @throws Exception If an error occurred while processing the event
*/
void onPostAdd(IoFilterChain parent, String name, NextFilter nextFilter) throws Exception;
@@ -129,6 +135,7 @@ public interface IoFilter {
* @param name the name assigned to this filter
* @param nextFilter the {@link NextFilter} for this filter. You can reuse
* this object until this filter is removed from the chain.
+ * @throws Exception If an error occurred while processing the event
*/
void onPreRemove(IoFilterChain parent, String name, NextFilter nextFilter) throws Exception;
@@ -142,6 +149,7 @@ public interface IoFilter {
* @param name the name assigned to this filter
* @param nextFilter the {@link NextFilter} for this filter. You can reuse
* this object until this filter is removed from the chain.
+ * @throws Exception If an error occurred while processing the event
*/
void onPostRemove(IoFilterChain parent, String name, NextFilter nextFilter) throws Exception;
@@ -151,8 +159,8 @@ public interface IoFilter {
* @param nextFilter
* the {@link NextFilter} for this filter. You can reuse this
* object until this filter is removed from the chain.
- * @param session
- * The {@link IoSession} which has received this event
+ * @param session The {@link IoSession} which has received this event
+ * @throws Exception If an error occurred while processing the event
*/
void sessionCreated(NextFilter nextFilter, IoSession session) throws Exception;
@@ -162,8 +170,8 @@ public interface IoFilter {
* @param nextFilter
* the {@link NextFilter} for this filter. You can reuse this
* object until this filter is removed from the chain.
- * @param session
- * The {@link IoSession} which has received this event
+ * @param session The {@link IoSession} which has received this event
+ * @throws Exception If an error occurred while processing the event
*/
void sessionOpened(NextFilter nextFilter, IoSession session) throws Exception;
@@ -173,8 +181,8 @@ public interface IoFilter {
* @param nextFilter
* the {@link NextFilter} for this filter. You can reuse this
* object until this filter is removed from the chain.
- * @param session
- * The {@link IoSession} which has received this event
+ * @param session The {@link IoSession} which has received this event
+ * @throws Exception If an error occurred while processing the event
*/
void sessionClosed(NextFilter nextFilter, IoSession session) throws Exception;
@@ -184,10 +192,9 @@ public interface IoFilter {
* @param nextFilter
* the {@link NextFilter} for this filter. You can reuse this
* object until this filter is removed from the chain.
- * @param session
- * The {@link IoSession} which has received this event
- * @param status
- * The {@link IdleStatus} type
+ * @param session The {@link IoSession} which has received this event
+ * @param status The {@link IdleStatus} type
+ * @throws Exception If an error occurred while processing the event
*/
void sessionIdle(NextFilter nextFilter, IoSession session, IdleStatus status) throws Exception;
@@ -197,10 +204,9 @@ public interface IoFilter {
* @param nextFilter
* the {@link NextFilter} for this filter. You can reuse this
* object until this filter is removed from the chain.
- * @param session
- * The {@link IoSession} which has received this event
- * @param cause
- * The exception that cause this event to be received
+ * @param session The {@link IoSession} which has received this event
+ * @param cause The exception that cause this event to be received
+ * @throws Exception If an error occurred while processing the event
*/
void exceptionCaught(NextFilter nextFilter, IoSession session, Throwable cause) throws Exception;
@@ -210,8 +216,8 @@ public interface IoFilter {
* @param nextFilter
* the {@link NextFilter} for this filter. You can reuse this
* object until this filter is removed from the chain.
- * @param session
- * The {@link IoSession} which has received this event
+ * @param session The {@link IoSession} which has received this event
+ * @throws Exception If an error occurred while processing the event
*/
void inputClosed(NextFilter nextFilter, IoSession session) throws Exception;
@@ -221,10 +227,9 @@ public interface IoFilter {
* @param nextFilter
* the {@link NextFilter} for this filter. You can reuse this
* object until this filter is removed from the chain.
- * @param session
- * The {@link IoSession} which has received this event
- * @param message
- * The received message
+ * @param session The {@link IoSession} which has received this event
+ * @param message The received message
+ * @throws Exception If an error occurred while processing the event
*/
void messageReceived(NextFilter nextFilter, IoSession session, Object message) throws Exception;
@@ -234,10 +239,9 @@ public interface IoFilter {
* @param nextFilter
* the {@link NextFilter} for this filter. You can reuse this
* object until this filter is removed from the chain.
- * @param session
- * The {@link IoSession} which has received this event
- * @param writeRequest
- * The {@link WriteRequest} that contains the sent message
+ * @param session The {@link IoSession} which has received this event
+ * @param writeRequest The {@link WriteRequest} that contains the sent message
+ * @throws Exception If an error occurred while processing the event
*/
void messageSent(NextFilter nextFilter, IoSession session, WriteRequest writeRequest) throws Exception;
@@ -250,6 +254,7 @@ public interface IoFilter {
* @param session
* The {@link IoSession} which has to process this method
* invocation
+ * @throws Exception If an error occurred while processing the event
*/
void filterClose(NextFilter nextFilter, IoSession session) throws Exception;
@@ -259,10 +264,9 @@ public interface IoFilter {
* @param nextFilter
* the {@link NextFilter} for this filter. You can reuse this
* object until this filter is removed from the chain.
- * @param session
- * The {@link IoSession} which has to process this invocation
- * @param writeRequest
- * The {@link WriteRequest} to process
+ * @param session The {@link IoSession} which has to process this invocation
+ * @param writeRequest The {@link WriteRequest} to process
+ * @throws Exception If an error occurred while processing the event
*/
void filterWrite(NextFilter nextFilter, IoSession session, WriteRequest writeRequest) throws Exception;
http://git-wip-us.apache.org/repos/asf/mina/blob/970c4a76/mina-core/src/main/java/org/apache/mina/core/filterchain/IoFilterChain.java
----------------------------------------------------------------------
diff --git a/mina-core/src/main/java/org/apache/mina/core/filterchain/IoFilterChain.java b/mina-core/src/main/java/org/apache/mina/core/filterchain/IoFilterChain.java
index 9b3df99..8e6c9c5 100644
--- a/mina-core/src/main/java/org/apache/mina/core/filterchain/IoFilterChain.java
+++ b/mina-core/src/main/java/org/apache/mina/core/filterchain/IoFilterChain.java
@@ -209,6 +209,7 @@ public interface IoFilterChain {
*
* @param oldFilterType The filter class we want to replace
* @param newFilter The new filter
+ * @return The replaced IoFilter
*/
IoFilter replace(Class<? extends IoFilter> oldFilterType, IoFilter newFilter);
@@ -241,6 +242,8 @@ public interface IoFilterChain {
/**
* Removes all filters added to this chain.
+ *
+ * @throws Exception If we weren't able to clear the filters
*/
void clear() throws Exception;
http://git-wip-us.apache.org/repos/asf/mina/blob/970c4a76/mina-core/src/main/java/org/apache/mina/core/service/IoAcceptor.java
----------------------------------------------------------------------
diff --git a/mina-core/src/main/java/org/apache/mina/core/service/IoAcceptor.java b/mina-core/src/main/java/org/apache/mina/core/service/IoAcceptor.java
index a8d9c22..b40a5e7 100644
--- a/mina-core/src/main/java/org/apache/mina/core/service/IoAcceptor.java
+++ b/mina-core/src/main/java/org/apache/mina/core/service/IoAcceptor.java
@@ -48,11 +48,15 @@ public interface IoAcceptor extends IoService {
* Returns the local address which is bound currently. If more than one
* address are bound, only one of them will be returned, but it's not
* necessarily the firstly bound address.
+ *
+ * @return The bound LocalAddress
*/
SocketAddress getLocalAddress();
/**
* Returns a {@link Set} of the local addresses which are bound currently.
+ *
+ * @return The Set of bound LocalAddresses
*/
Set<SocketAddress> getLocalAddresses();
@@ -63,6 +67,7 @@ public interface IoAcceptor extends IoService {
* set, only one of them will be returned, but it's not necessarily the
* firstly specified address in {@link #setDefaultLocalAddresses(List)}.
*
+ * @return The default bound LocalAddress
*/
SocketAddress getDefaultLocalAddress();
@@ -70,6 +75,8 @@ public interface IoAcceptor extends IoService {
* Returns a {@link List} of the default local addresses to bind when no
* argument is specified in {@link #bind()} method. Please note that the
* default will not be used if any local address is specified.
+ *
+ * @return The list of default bound LocalAddresses
*/
List<SocketAddress> getDefaultLocalAddresses();
@@ -77,6 +84,8 @@ public interface IoAcceptor extends IoService {
* Sets the default local address to bind when no argument is specified in
* {@link #bind()} method. Please note that the default will not be used
* if any local address is specified.
+ *
+ * @param localAddress The local addresses to bind the acceptor on
*/
void setDefaultLocalAddress(SocketAddress localAddress);
@@ -84,6 +93,8 @@ public interface IoAcceptor extends IoService {
* Sets the default local addresses to bind when no argument is specified
* in {@link #bind()} method. Please note that the default will not be
* used if any local address is specified.
+ * @param firstLocalAddress The first local address to bind the acceptor on
+ * @param otherLocalAddresses The other local addresses to bind the acceptor on
*/
void setDefaultLocalAddresses(SocketAddress firstLocalAddress, SocketAddress... otherLocalAddresses);
@@ -91,6 +102,8 @@ public interface IoAcceptor extends IoService {
* Sets the default local addresses to bind when no argument is specified
* in {@link #bind()} method. Please note that the default will not be
* used if any local address is specified.
+ *
+ * @param localAddresses The local addresses to bind the acceptor on
*/
void setDefaultLocalAddresses(Iterable<? extends SocketAddress> localAddresses);
@@ -98,6 +111,8 @@ public interface IoAcceptor extends IoService {
* Sets the default local addresses to bind when no argument is specified
* in {@link #bind()} method. Please note that the default will not be
* used if any local address is specified.
+ *
+ * @param localAddresses The local addresses to bind the acceptor on
*/
void setDefaultLocalAddresses(List<? extends SocketAddress> localAddresses);
@@ -105,6 +120,8 @@ public interface IoAcceptor extends IoService {
* Returns <tt>true</tt> if and only if all clients are closed when this
* acceptor unbinds from all the related local address (i.e. when the
* service is deactivated).
+ *
+ * @return <tt>true</tt> if the service sets the closeOnDeactivation flag
*/
boolean isCloseOnDeactivation();
@@ -112,6 +129,8 @@ public interface IoAcceptor extends IoService {
* Sets whether all client sessions are closed when this acceptor unbinds
* from all the related local addresses (i.e. when the service is
* deactivated). The default value is <tt>true</tt>.
+ *
+ * @param closeOnDeactivation <tt>true</tt> if we should close on deactivation
*/
void setCloseOnDeactivation(boolean closeOnDeactivation);
@@ -137,13 +156,10 @@ public interface IoAcceptor extends IoService {
* Binds to the specified local addresses and start to accept incoming
* connections. If no address is given, bind on the default local address.
*
- * @param firstLocalAddress
- * The first address to bind to
- * @param addresses
- * The SocketAddresses to bind to
+ * @param firstLocalAddress The first address to bind to
+ * @param addresses The SocketAddresses to bind to
*
- * @throws IOException
- * if failed to bind
+ * @throws IOException if failed to bind
*/
void bind(SocketAddress firstLocalAddress, SocketAddress... addresses) throws IOException;
@@ -161,6 +177,7 @@ public interface IoAcceptor extends IoService {
* Binds to the specified local addresses and start to accept incoming
* connections.
*
+ * @param localAddresses The local address we will be bound to
* @throws IOException if failed to bind
*/
void bind(Iterable<? extends SocketAddress> localAddresses) throws IOException;
@@ -180,6 +197,8 @@ public interface IoAcceptor extends IoService {
* {@link #setCloseOnDeactivation(boolean) disconnectOnUnbind} property is
* <tt>true</tt>. This method returns silently if the default local
* address is not bound yet.
+ *
+ * @param localAddress The local address we will be unbound from
*/
void unbind(SocketAddress localAddress);
@@ -189,6 +208,9 @@ public interface IoAcceptor extends IoService {
* {@link #setCloseOnDeactivation(boolean) disconnectOnUnbind} property is
* <tt>true</tt>. This method returns silently if the default local
* addresses are not bound yet.
+ *
+ * @param firstLocalAddress The first local address to be unbound from
+ * @param otherLocalAddresses The other local address to be unbound from
*/
void unbind(SocketAddress firstLocalAddress, SocketAddress... otherLocalAddresses);
@@ -198,6 +220,8 @@ public interface IoAcceptor extends IoService {
* {@link #setCloseOnDeactivation(boolean) disconnectOnUnbind} property is
* <tt>true</tt>. This method returns silently if the default local
* addresses are not bound yet.
+ *
+ * @param localAddresses The local address we will be unbound from
*/
void unbind(Iterable<? extends SocketAddress> localAddresses);
@@ -210,10 +234,13 @@ public interface IoAcceptor extends IoService {
* if the transport type doesn't support this operation. This operation is
* usually implemented for connectionless transport types.
*
+ * @param remoteAddress The remote address bound to the service
+ * @param localAddress The local address the session will be bound to
* @throws UnsupportedOperationException if this operation is not supported
* @throws IllegalStateException if this service is not running.
* @throws IllegalArgumentException if this service is not bound to the
* specified <tt>localAddress</tt>.
+ * @return The session bound to the the given localAddress and remote address
*/
IoSession newSession(SocketAddress remoteAddress, SocketAddress localAddress);
}
\ No newline at end of file