Merge pull request belaban#256 from bjc-world/master

Fixed various Javadoc warnings

src/org/jgroups/JChannel.java

@@ -78,9 +78,9 @@ public class JChannel extends Channel {
 
     /**
      * Creates a JChannel without a protocol stack; used for programmatic creation of channel and protocol stack
+     *
      * @param create_protocol_stack If true, the default configuration will be used. If false, no protocol stack
      *        will be created
-     * @param create_protocol_stack Creates the default stack if true, or no stack if false
      */
     public JChannel(boolean create_protocol_stack) {
         if(create_protocol_stack) {

src/org/jgroups/auth/X509Token.java

@@ -169,9 +169,6 @@ public int size() {
     /**
      * Used during setup to get the certification from the keystore and encrypt the auth_value with
      * the private key
-     * 
-     * @return true if the certificate was found and the string encypted correctly otherwise returns
-     *         false
      */
     public void setCertificate() throws KeyStoreException, IOException, NoSuchAlgorithmException,
                     CertificateException, NoSuchPaddingException, InvalidKeyException,

src/org/jgroups/blocks/ReplicatedHashMap.java

@@ -538,7 +538,7 @@ public void unblock() {}
     /**
      * Creates a synchronized facade for a ReplicatedMap. All methods which
      * change state are invoked through a monitor. This is similar to
-     * {@Collections.synchronizedMap()}, but also includes the replication
+     * {@link java.util.Collections.SynchronizedMap#synchronizedMap(Map)}, but also includes the replication
      * methods (starting with an underscore).
      * 
      * @param map

src/org/jgroups/blocks/cs/NioClient.java

@@ -27,7 +27,6 @@ public class NioClient extends NioBaseServer implements Client {
      * the client and server.
      * @param bind_addr The address to which the local channel should bind to. Can be null, then the OS picks the address
      * @param server_addr The address of the server to connect to
-     * @return An instance of {@link NioClient}
      * @throws Exception If the creation failed
     */
     public NioClient(IpAddress bind_addr, IpAddress server_addr) {
@@ -46,7 +45,6 @@ public NioClient(IpAddress bind_addr, IpAddress server_addr) {
      * @param bind_port The local port. Can be 0, then the OS picks the port.
      * @param server_addr The address of the server to connect to
      * @param server_port The port of the server to connect to.
-     * @return An instance of {@link NioClient}
      * @throws Exception If the creation failed
     */
     public NioClient(InetAddress bind_addr, int bind_port, InetAddress server_addr, int server_port) {

src/org/jgroups/blocks/cs/NioServer.java

@@ -40,9 +40,9 @@ public NioServer(IpAddress bind_addr) throws Exception {
 
     /**
      * Creates an instance of {@link NioServer} that opens a server channel and listens for connections.
+     * Needs to be started next.
      * @param bind_addr The local address to bind to. If null, the address will be picked by the OS
      * @param port The local port to bind to
-     * @return An instance of {@link NioServer}. Needs to be started next.
      * @throws Exception Thrown if the creation failed
      */
     public NioServer(InetAddress bind_addr, int port) throws Exception {
@@ -53,13 +53,12 @@ public NioServer(InetAddress bind_addr, int port) throws Exception {
 
     /**
      * Creates an instance of {@link NioServer} that opens a server channel and listens for connections.
+     * Needs to be started next.
      * @param thread_factory The thread factory used to create new threads
      * @param bind_addr The local address to bind to. If null, the address will be picked by the OS
      * @param end_port If srv_port is taken, the next port is tried, until end_port has been reached, in which case an
      *                 exception will be thrown. If srv_port == end_port, only 1 port will be tried.
      * @param external_addr The external address in case of NAT. Ignored if null.
-     * @param external_port The external port on the NA. If 0, srv_port is used.
-     * @return An instance of {@link NioServer}. Needs to be started next.
      * @throws Exception Thrown if the creation failed
      */
     public NioServer(ThreadFactory thread_factory, IpAddress bind_addr, int end_port, IpAddress external_addr) throws Exception {
@@ -71,14 +70,14 @@ public NioServer(ThreadFactory thread_factory, IpAddress bind_addr, int end_port
 
     /**
      * Creates an instance of {@link NioServer} that opens a server channel and listens for connections.
+     * Needs to be started next.
      * @param thread_factory The thread factory used to create new threads
      * @param bind_addr The local address to bind to. If null, the address will be picked by the OS
      * @param srv_port The local port to bind to If 0, the port will be picked by the OS.
      * @param end_port If srv_port is taken, the next port is tried, until end_port has been reached, in which case an
      *                 exception will be thrown. If srv_port == end_port, only 1 port will be tried.
      * @param external_addr The external address in case of NAT. Ignored if null.
      * @param external_port The external port on the NA. If 0, srv_port is used.
-     * @return An instance of {@link NioServer}. Needs to be started next.
      * @throws Exception Thrown if the creation failed
      */
     public NioServer(ThreadFactory thread_factory, InetAddress bind_addr, int srv_port, int end_port,

src/org/jgroups/blocks/cs/TcpClient.java

@@ -24,7 +24,6 @@ public class TcpClient extends TcpBaseServer implements Client, ConnectionListen
      * the client and server.
      * @param bind_addr The address to which the local socket should bind to. Can be null, then the OS picks the address
      * @param server_addr The address of the server to connect to
-     * @return An instance of {@link TcpClient}
      * @throws Exception If the creation failed
      */
     public TcpClient(IpAddress bind_addr, IpAddress server_addr) {
@@ -43,7 +42,6 @@ public TcpClient(IpAddress bind_addr, IpAddress server_addr) {
      * @param bind_port The local port. Can be 0, then the OS picks the port.
      * @param server_addr The address of the server to connect to
      * @param server_port The port of the server to connect to.
-     * @return An instance of {@link TcpClient}
      * @throws Exception If the creation failed
      */
     public TcpClient(InetAddress bind_addr, int bind_port, InetAddress server_addr, int server_port) {

src/org/jgroups/blocks/cs/TcpServer.java

@@ -21,12 +21,10 @@ public class TcpServer extends TcpBaseServer {
 
 
     /**
-     * Creates an instance of {@link TcpServer} that creates a server socket and listens for connections
+     * Creates an instance of {@link TcpServer} that creates a server socket and listens for connections.
+     * The end port defaults to (port + 50).  Needs to be started next.
      * @param bind_addr The local address to bind to. If null, the address will be picked by the OS
      * @param port The local port to bind to. If 0, the port will be picked by the OS.
-     * @param port If srv_port is taken, the next port is tried, until end_port has been reached, in which case an
-     *             exception will be thrown. If srv_port == end_port, only 1 port will be tried.
-     * @return An instance of {@link TcpServer}. Needs to be started next.
      * @throws Exception Thrown if the creation failed
      */
     public TcpServer(InetAddress bind_addr, int port) throws Exception {
@@ -60,6 +58,7 @@ public TcpServer(ThreadFactory thread_factory, SocketFactory socket_factory,
 
     /**
      * Creates an instance of {@link TcpServer} that creates a server socket and listens for connections
+     * Needs to be started next.
      * @param thread_factory The thread factory used to create new threads
      * @param socket_factory The socket factory used to create sockets
      * @param bind_addr The local address to bind to. If null, the address will be picked by the OS
@@ -68,7 +67,6 @@ public TcpServer(ThreadFactory thread_factory, SocketFactory socket_factory,
      *                 exception will be thrown. If srv_port == end_port, only 1 port will be tried.
      * @param external_addr The external address in case of NAT. Ignored if null.
      * @param external_port The external port on the NA. If 0, srv_port is used.
-     * @return An instance of {@link TcpServer}. Needs to be started next.
      * @throws Exception Thrown if the creation failed
      */
     public TcpServer(ThreadFactory thread_factory, SocketFactory socket_factory,

src/org/jgroups/blocks/executor/ExecutionService.java

@@ -710,7 +710,7 @@ public void execute(Runnable command) {
     }
 
     /**
-     * This is copied from {@see java.util.concurrent.Executors} class which
+     * This is copied from {@link java.util.concurrent.Executors} class which
      * contains RunnableAdapter.  However that adapter isn't serializable, and
      * is final and package level so we can' reference.
      */

src/org/jgroups/fork/UnknownForkHandler.java

@@ -19,7 +19,7 @@ public interface UnknownForkHandler {
     /**
      * Handle a message that refers to an unknown fork channel
      * @param message an incoming message
-     * @param forkStackId the identifier of a fork channel
+     * @param forkChannelId the identifier of a fork channel
      * @return the result of the up handler
      */
     Object handleUnknownForkChannel(Message message, String forkChannelId);

src/org/jgroups/protocols/Executing.java

@@ -86,9 +86,9 @@ abstract public class Executing extends Protocol {
     /**
      * This is a server side store of all the barriers for respective tasks 
      * requests.  When a consumer is starting up they should create a latch
-     * place in map with it's id and wait on it until a request comes in to
-     * wake it up it would only then touch the {@link _tasks} map.  A requestor
-     * should first place in the {@link _tasks} map and then create a latch
+     * place in map with its id and wait on it until a request comes in to
+     * wake it up it would only then touch the {@link Executing#_tasks} map.  A requestor
+     * should first place in the {@link Executing#_tasks} map and then create a latch
      * and notify the consumer
      */
     protected ConcurrentMap<Long, CyclicBarrier> _taskBarriers = 

src/org/jgroups/protocols/TP.java

@@ -1990,7 +1990,6 @@ protected void setPingData(PingData data) {
     /**
      * This method needs to be synchronized on out_stream when it is called
      * @param msg
-     * @return
      * @throws java.io.IOException
      */
     protected static void writeMessage(Message msg, DataOutput dos, boolean multicast) throws Exception {
@@ -2252,7 +2251,6 @@ protected Object handleDownEvent(Event evt) {
     /**
      * Associates the address with the physical address fetched from the cache
      * @param addr
-     * @return true if registered successfully, otherwise false (e.g. physical addr could not be fetched)
      */
     protected void registerLocalAddress(Address addr) {
         PhysicalAddress physical_addr=getPhysicalAddress();

src/org/jgroups/stack/DefaultRetransmitter.java

@@ -82,7 +82,6 @@ public void remove(long seqno) {
      * Removes the given seqno and all seqnos lower than it
      * @param seqno
      * @param remove_all_below If true, all seqnos below seqno are removed, too
-     * @return
      */
     public void remove(long seqno, boolean remove_all_below) {
         if(!remove_all_below) {

src/org/jgroups/util/HashedTimingWheel.java

@@ -201,7 +201,7 @@ public Future<?> scheduleAtFixedRate(Runnable task, long initial_delay, long del
 
     /**
      * Schedule a task for execution at varying intervals. After execution, the task will get rescheduled after
-     * {@link org.jgroups.util.HashedTimingWheel.Task#nextInterval()} milliseconds. The task is neve done until nextInterval()
+     * {@link org.jgroups.util.HashedTimingWheel.RecurringTask#nextInterval()} milliseconds. The task is never done until nextInterval()
      * return a value <= 0 or the task is cancelled.
      * @param task the task to execute
      * Task is rescheduled relative to the last time it <i>actually</i> started execution<p/>

src/org/jgroups/util/SocketFactory.java

@@ -11,7 +11,7 @@
  * Ephemeral ports can be created by passing 0 as port, or (if the port is ignored), an implementation could pass in
  * a special service name (e.g. "EPHEMERAL"), this is implementation dependent.<p/>
  * The socket creation methods have the same parameter lists as the socket constructors, e.g.
- * {@link #createServerSocket(String, int, int)} is the same as {@link java.net.ServerSocket(int,int)}. 
+ * {@link #createServerSocket(String, int, int)} is the same as {@link java.net.ServerSocket#ServerSocket(int, int)}.
  * @author Bela Ban
  */
 public interface SocketFactory {

src/org/jgroups/util/TimeScheduler2.java

@@ -166,7 +166,7 @@ public Future<?> scheduleAtFixedRate(Runnable task, long initial_delay, long del
 
     /**
      * Schedule a task for execution at varying intervals. After execution, the task will get rescheduled after
-     * {@link org.jgroups.util.TimeScheduler2.Task#nextInterval()} milliseconds. The task is neve done until nextInterval()
+     * {@link org.jgroups.util.TimeScheduler2.RecurringTask#nextInterval()} milliseconds. The task is never done until nextInterval()
      * return a value <= 0 or the task is cancelled.
      * @param task the task to execute
      * Task is rescheduled relative to the last time it <i>actually</i> started execution<p/>