From e7b1a2b7102a0593754f5641cdbb76e9a810751b Mon Sep 17 00:00:00 2001 From: Vladimir Blagojevic Date: Thu, 20 Oct 2011 15:52:50 +0200 Subject: [PATCH] Javadoc cleanup --- src/org/jgroups/Address.java | 14 +- src/org/jgroups/Channel.java | 494 ++++++++++++-------- src/org/jgroups/ChannelListener.java | 44 +- src/org/jgroups/Event.java | 6 +- src/org/jgroups/Global.java | 5 +- src/org/jgroups/Header.java | 6 +- src/org/jgroups/JChannel.java | 19 +- src/org/jgroups/Membership.java | 185 ++++---- src/org/jgroups/MembershipListener.java | 87 ++-- src/org/jgroups/MergeView.java | 68 +-- src/org/jgroups/Message.java | 320 +++++++------ src/org/jgroups/MessageListener.java | 67 ++- src/org/jgroups/PhysicalAddress.java | 5 + src/org/jgroups/Receiver.java | 3 + src/org/jgroups/ReceiverAdapter.java | 28 +- src/org/jgroups/StateTransferException.java | 9 +- src/org/jgroups/SuspectedException.java | 3 + src/org/jgroups/TimeoutException.java | 3 + src/org/jgroups/UpHandler.java | 19 +- src/org/jgroups/View.java | 46 +- src/org/jgroups/util/UUID.java | 5 +- 21 files changed, 851 insertions(+), 585 deletions(-) diff --git a/src/org/jgroups/Address.java b/src/org/jgroups/Address.java index abcf16b9afa..65e5e250f54 100644 --- a/src/org/jgroups/Address.java +++ b/src/org/jgroups/Address.java @@ -2,13 +2,19 @@ package org.jgroups; import org.jgroups.util.Streamable; - - +import org.jgroups.util.UUID; /** - * Abstract address. Used to identify members on a group to send messages to. - * Addresses are mostly generated by the bottom-most (transport) layers (e.g. UDP, TCP, LOOPBACK). + * Address identifies cluster member. For example, whenever a unicast message is sent in a cluster + * an Address of a cluster member message recipient needs to be specified. Similarly a cluster + * member can use Address to check its own identity, request a state from a particular member and so + * on. Addresses are mostly generated by the bottom-most (transport) layers (e.g. UDP, TCP, + * LOOPBACK). + * * @author Bela Ban + * @since 2.0 + * @see PhysicalAddress + * @see UUID */ public interface Address extends Streamable, Comparable
, Cloneable { // flags used for marshalling diff --git a/src/org/jgroups/Channel.java b/src/org/jgroups/Channel.java index b04504d4045..9865ad5583f 100644 --- a/src/org/jgroups/Channel.java +++ b/src/org/jgroups/Channel.java @@ -11,40 +11,46 @@ import org.jgroups.util.DefaultSocketFactory; import org.jgroups.util.SocketFactory; + import java.util.List; import java.util.Map; import java.util.Set; import java.util.concurrent.CopyOnWriteArraySet; - /** - A channel represents a group communication endpoint (like BSD datagram sockets). A - client joins a group by connecting the channel to a group and leaves it by - disconnecting. Messages sent over the channel are received by all group members that - are connected to the same group (that is, all members that have the same group name).

- - The FSM for a channel is roughly as follows: a channel is created (unconnected). The channel is connected to - a group (connected). Messages can now be sent and received. The channel is disconnected from the group - (unconnected). The channel could now be connected to a different group again. - The channel is closed (closed).

- - Only a single sender is allowed to be connected to a channel at a time, but there can be - more than one channel in an application.

- - Messages can be sent to the group members using the send method and messages - can be received setting a {@link Receiver} in {@link #setReceiver(Receiver)} and implementing the - {@link Receiver#receive(Message)} callback.

- - A channel instance is created using the public constructor.

- Various degrees of sophistication in message exchange can be achieved using building - blocks on top of channels; e.g., light-weight groups, synchronous message invocation, - or remote method calls. Channels are on the same abstraction level as sockets, and - should really be simple to use. Higher-level abstractions are all built on top of channels. - - @author Bela Ban - @see java.net.DatagramPacket - @see java.net.MulticastSocket - @see JChannel + * A channel represents a group communication endpoint (like BSD datagram sockets). A client joins a + * group by connecting the channel to a group and leaves it by disconnecting. Messages sent over the + * channel are received by all group members that are connected to the same group (that is, all + * members that have the same group name). + *

+ * + * The FSM for a channel is roughly as follows: a channel is created (unconnected). The + * channel is connected to a group (connected). Messages can now be sent and received. The + * channel is disconnected from the group (unconnected). The channel could now be connected + * to a different group again. The channel is closed (closed). + *

+ * + * Only a single sender is allowed to be connected to a channel at a time, but there can be more + * than one channel in an application. + *

+ * + * Messages can be sent to the group members using the send method and messages can be + * received setting a {@link Receiver} in {@link #setReceiver(Receiver)} and implementing the + * {@link Receiver#receive(Message)} callback. + *

+ * + * A channel instance is created using the public constructor. + *

+ * Various degrees of sophistication in message exchange can be achieved using building blocks on + * top of channels; e.g., light-weight groups, synchronous message invocation, or remote method + * calls. Channels are on the same abstraction level as sockets, and should really be simple to use. + * Higher-level abstractions are all built on top of channels. + * + * @author Bela Ban + * @since 2.0 + * @see java.net.DatagramPacket + * @see java.net.MulticastSocket + * @see JChannel */ @MBean(description="Channel") public abstract class Channel /* implements Transport */ { @@ -73,18 +79,23 @@ public void setSocketFactory(SocketFactory factory) { prot.setSocketFactory(factory); } - /** - Connects the channel to a group. The client is now able to receive group - messages, views and to send messages to (all or single) group members. This is a null operation if - already connected.

- - All channels with the same name form a group, that means all messages - sent to the group will be received by all channels connected to the same cluster name.

- - @param cluster_name The name of the chanel to connect to. - @exception Exception The protocol stack cannot be started - @exception IllegalStateException The channel is closed - */ + /** + * Connects the channel to a group. The client is now able to receive group messages, views and + * to send messages to (all or single) group members. This is a null operation if already + * connected. + *

+ * + * All channels with the same name form a group, that means all messages sent to the group will + * be received by all channels connected to the same cluster name. + *

+ * + * @param cluster_name + * The name of the channel to connect to. + * @exception Exception + * The protocol stack cannot be started + * @exception IllegalStateException + * The channel is closed + */ abstract public void connect(String cluster_name) throws Exception; @@ -95,7 +106,7 @@ messages, views and to send messages to (all or single) group members. This is * This method essentially invokes * connect and getState methods successively. * If FLUSH protocol is in channel's stack definition only one flush is executed for both connecting and - * fetching state rather than two flushes if we invoke connect and getState in succesion. + * fetching state rather than two flushes if we invoke connect and getState in succession. * * If the channel is closed an exception will be thrown. * @@ -111,144 +122,184 @@ messages, views and to send messages to (all or single) group members. This is abstract public void connect(String cluster_name, Address target, long timeout) throws Exception; - /** - * Disconnects the channel if it is connected. If the channel is closed or disconnected, this operation is ignored
- * The channel can then be connected to the same or a different cluster again. - * @see #connect(String) */ + /** + * Disconnects the channel if it is connected. If the channel is closed or disconnected, this + * operation is ignored
+ * The channel can then be connected to the same or a different cluster again. + * + * @see #connect(String) + */ abstract public void disconnect(); - /** - Destroys the channel and its associated resources (e.g., the protocol stack). After a channel - has been closed, invoking methods on it throws the ChannelClosed exception - (or results in a null operation). It is a null operation if the channel is already closed.

- If the channel is connected to a group, disconnec()t will be called first. - */ + /** + * Destroys the channel and its associated resources (e.g., the protocol stack). After a channel + * has been closed, invoking methods on it throws the ChannelClosed exception (or + * results in a null operation). It is a null operation if the channel is already closed. + *

+ * If the channel is connected to a group, disconnect() will be called first. + */ abstract public void close(); - /** - Determines whether the channel is open; ie. the protocol stack has been created (may not be connected though). - */ + /** + * Determines whether the channel is open; ie. the protocol stack has been created (may not be + * connected though). + * + * @return true is channel is open, false otherwise + */ abstract public boolean isOpen(); - /** - Determines whether the channel is connected to a group. This implies it is open. If true is returned, - then the channel can be used to send and receive messages. - */ + /** + * Determines whether the channel is connected to a group. + * + * @return true if channel is connected to cluster (group) and can send/receive messages, false otherwise + */ abstract public boolean isConnected(); - /** - * Returns a map of statistics of the various protocols and of the channel itself. - * @return Map. A map where the keys are the protocols ("channel" pseudo key is - * used for the channel itself") and the values are property maps. - */ + /** + * Returns a map of statistics of the various protocols and of the channel itself. + * + * @return Map. A map where the keys are the protocols ("channel" pseudo key is used + * for the channel itself") and the values are property maps. + */ public abstract Map dumpStats(); - /** Sends a message. The message contains -

    -
  1. a destination address (Address). A null address sends the message - to all group members. -
  2. a source address. Can be left empty. Will be filled in by the protocol stack. -
  3. a byte buffer. The message contents. -
  4. several additional fields. They can be used by application programs (or patterns). E.g. - a message ID, flags etc -
- @param msg The message to be sent. Destination and buffer should be set. A null destination - means to send to all group members. - @exception IllegalStateException thrown if the channel is disconnected or closed - */ + /** + * Sends a message. The message contains + *
    + *
  1. a destination address (Address). A null address sends the message to all + * group members. + *
  2. a source address. Can be left empty as it will be assigned automatically + *
  3. a byte buffer. The message contents. + *
  4. several additional fields. They can be used by application programs (or patterns). E.g. a + * message ID, flags etc + *
+ * + * @param msg + * The message to be sent. Destination and buffer should be set. A null destination + * means to send to all group members. + * @exception IllegalStateException + * thrown if the channel is disconnected or closed + */ abstract public void send(Message msg) throws Exception; - /** - Helper method. Will create a Message(dst, src, obj) and use send(Message). - @param dst Destination address for message. If null, message will be sent to all current group members - @param obj A serializable object. Will be marshalled into the byte buffer of the Message. If it is - not serializable, an exception will be thrown - */ + /** + * Helper method to create a Message with given parameters and invoke {@link #send(Message)}. + * + * @param dst + * Destination address for message. If null, message will be sent to all current group + * members + * @param obj + * A serializable object. Will be marshalled into the byte buffer of the Message. If it + * is not serializable, an exception will be thrown + * @throws Exception + * exception thrown if message sending was not successful + */ abstract public void send(Address dst, Object obj) throws Exception; - /** - * Sends a message. See {@link #send(Address,byte[],int,int)} for details - * @param dst - * @param buf - * @throws Exception - */ + /** + * Sends a message. See {@link #send(Address,byte[],int,int)} for details + * + * @param dst + * destination address for message. If null, message will be sent to all current group + * members + * @param buf + * buffer message payload + * @throws Exception + * exception thrown if message sending was not successful + */ abstract public void send(Address dst, byte[] buf) throws Exception; - /** - * Sends a message to a destination. - * @param dst The destination address. If null, the message will be sent to all cluster nodes (= group members) - * @param buf The buffer to be sent - * @param offset The offset into the buffer - * @param length The length of the data to be sent. Has to be <= buf.length - offset. This will send - * length bytes starting at offset - * @throws Exception If send() failed - */ + /** + * Sends a message to a destination. + * + * @param dst + * The destination address. If null, the message will be sent to all cluster nodes (= + * group members) + * @param buf + * The buffer to be sent + * @param offset + * The offset into the buffer + * @param length + * The length of the data to be sent. Has to be <= buf.length - offset. This will send + * length bytes starting at offset + * @throws Exception + * If send() failed + */ abstract public void send(Address dst, byte[] buf, int offset, int length) throws Exception; - /** - Access to event mechanism of channels. Enables to send and receive events, used by building - blocks to communicate with (building block) specific protocol layers. Currently useful only - with JChannel. - */ + /** + * Enables access to event mechanism of a channel and is normally not used by clients directly. + * + * @param sends an Event to a specific protocol layer and receive a response. + * @return a response from a particular protocol layer targeted by Event parameter + */ public Object down(Event evt) { return null; } - /** - * Gets the current view. The view may only be available after a successful - * connect(). The result of calling this method on an unconnected channel - * is implementation defined (may return null). Calling this method on a closed channel returns a null view. - * @return The current view. - */ + /** + * Gets the current view. The view may only be available after a successful + * connect(). The result of calling this method on an unconnected channel is + * implementation defined (may return null). Calling this method on a closed channel returns a + * null view. + * + * @return The current view. + */ abstract public View getView(); - - /** - Returns the channel's own address. The result of calling this method on an unconnected - channel is implementation defined (may return null). Calling this method on a closed - channel returns null. Addresses can be used as destination in the send() operation. - @return The channel's address (opaque) - */ + /** + * Returns the channel's own address. The result of calling this method on an unconnected channel + * is implementation defined (may return null). Calling this method on a closed channel returns + * null. Addresses can be used as destination in the send() operation. + * + * @return The channel's address (opaque) + */ abstract public Address getAddress(); - /** - * Returns the logical name of this channel if set. - * @return The logical name or null (if not set) - */ + /** + * Returns the logical name of this channel if set. + * + * @return The logical name or null (if not set) + */ abstract public String getName(); - /** - * Returns the logical name of a given member. The lookup is from the local cache of logical address - * / logical name mappings and no remote communication is performed. - * @param member - * @return The logical name for member - */ + /** + * Returns the logical name of a given member. The lookup is from the local cache of logical + * address / logical name mappings and no remote communication is performed. + * + * @param member + * @return The logical name for member + */ abstract public String getName(Address member); - /** - * Sets the logical name for the channel. The name will stay associated with this channel for the channel's - * lifetime (until close() is called). This method should be called before calling connect(). - * @param name - */ + /** + * Sets the logical name for the channel. The name will stay associated with this channel for the + * channel's lifetime (until close() is called). This method should be called before + * calling connect(). + * + * @param name + */ abstract public void setName(String name); - /** - Returns the cluster name of the group of which the channel is a member. This is - the object that was the argument to connect(). Calling this method on a closed - channel returns null. - @return The cluster name */ + /** + * Returns the cluster name of the group of which the channel is a member. This is the object + * that was the argument to connect(). Calling this method on a closed channel + * returns null. + * + * @return The cluster name + */ abstract public String getClusterName(); @@ -256,28 +307,37 @@ public String getProperties() { return "n/a"; } - /** - When up_handler is set, all events will be passed to it directly. These will not be received - by the channel (except connect/disconnect, state retrieval and the like). This can be used by - building blocks on top of a channel; thus the channel is used as a pass-through medium, and - the building blocks take over some of the channel's tasks. However, tasks such as connection - management and state transfer is still handled by the channel. - */ + /** + * Sets this channel event handler to be a recipient off all events . These will not be received + * by the channel (except connect/disconnect, state retrieval and the like). This can be used by + * building blocks on top of a channel; thus the channel is used as a pass-through medium, and + * the building blocks take over some of the channel's tasks. However, tasks such as connection + * management and state transfer is still handled by the channel. + * + * @param the + * handler to handle channel events + */ public void setUpHandler(UpHandler up_handler) { this.up_handler=up_handler; } - public UpHandler getUpHandler() { + /** + * Returns UpHandler installed for this channel + * + * @return the installed UpHandler implementation + */ + public UpHandler getUpHandler() { return up_handler; } - - /** - Allows to be notified when a channel event such as connect, disconnect or close occurs. - E.g. a PullPushAdapter may choose to stop when the channel is closed, or to start when - it is opened. - */ - @ManagedOperation + /** + * Adds a ChannelListener instance that will be notified when a channel event such as connect, + * disconnect or close occurs. + * + * @param listener + * to be notified + */ + @ManagedOperation public synchronized void addChannelListener(ChannelListener listener) { if(listener == null) return; @@ -286,63 +346,91 @@ public synchronized void addChannelListener(ChannelListener listener) { channel_listeners.add(listener); } - @ManagedOperation + /** + * Removes a ChannelListener previously installed + * + * @param listener to be removed + */ + @ManagedOperation public synchronized void removeChannelListener(ChannelListener listener) { if(channel_listeners != null && listener != null) channel_listeners.remove(listener); } - public synchronized void clearChannelListeners() { + /** + * Clears all installed ChannelListener instances + * + */ + public synchronized void clearChannelListeners() { if(channel_listeners != null) channel_listeners.clear(); } - /** Sets the receiver, which will handle all messages, view changes etc */ + /** + * Sets the receiver for this channel. Receiver will in turn handle all messages, view changes, + * implement state transfer logic and so on. + * + * @param r the receiver instance for this channel + * @see Receiver + * + * */ public void setReceiver(Receiver r) { receiver=r; } - public Receiver getReceiver() { + /** + * Returns a receiver for this channel if it has been installed using + * {@link Channel#setReceiver(Receiver)} , null otherwise + * + * @return a receiver installed on this channel + */ + public Receiver getReceiver() { return receiver; } - /** - * When set to true, all messages sent a member A will be discarded by A. - * @param flag - */ + /** + * When set to true, all messages sent by a member A will be discarded by A. + * + * @param flag + */ public void setDiscardOwnMessages(boolean flag) {discard_own_messages=flag;} - public boolean getDiscardOwnMessages() {return discard_own_messages;} + /** + * Returns true if this channel will discard its own messages, false otherwise + * + * @return + */ + public boolean getDiscardOwnMessages() {return discard_own_messages;} abstract public boolean flushSupported(); - /** - * Performs a partial flush in a cluster for flush participants. - *

- * All pending messages are flushed out only for the flush participants. The remaining members - * in a cluster are not included in the flush. The flush participants should be a proper subset - * of a current view. - *

- * - * @param automatic_resume - * Call {@link #stopFlush()} after the flush - * @see #startFlush(boolean) - */ + /** + * Performs a partial flush in a cluster for flush participants. + *

+ * All pending messages are flushed out only for the flush participants. The remaining members in + * a cluster are not included in the flush. The flush participants should be a proper subset of a + * current view. + *

+ * + * @param automatic_resume + * if true call {@link #stopFlush()} after the flush + * @see #startFlush(boolean) + */ abstract public void startFlush(List

flushParticipants, boolean automatic_resume) throws Exception; - /** - * Will perform a flush of the system, ie. all pending messages are flushed out of the system - * and all members ack their reception. After this call returns, no member will be sending any - * messages until {@link #stopFlush()} is called. - *

- * In case of flush collisions, a random sleep time backoff algorithm is employed and the flush - * is reattempted for numberOfAttempts. Therefore this method is guaranteed to return after - * timeout x numberOfAttempts miliseconds. - * - * @param automatic_resume - * Call {@link #stopFlush()} after the flush - */ + /** + * Will perform a flush of the system, ie. all pending messages are flushed out of the system and + * all members ack their reception. After this call returns, no member will be sending any + * messages until {@link #stopFlush()} is called. + *

+ * In case of flush collisions, a random sleep time backoff algorithm is employed and the flush + * is reattempted for numberOfAttempts. Therefore this method is guaranteed to return after + * timeout x numberOfAttempts milliseconds. + * + * @param automatic_resume + * if true call {@link #stopFlush()} after the flush + */ abstract public void startFlush(boolean automatic_resume) throws Exception; abstract public void stopFlush(); @@ -350,23 +438,29 @@ abstract public void startFlush(List

flushParticipants, boolean automat abstract public void stopFlush(List
flushParticipants); - /** - * Retrieves the full state from the target member. - *

- * State transfer is initiated by invoking getState on this channel, the state requester, and sending a GET_STATE - * message to a target member - the state provider. The state provider passes a GET_STATE message to the application - * that is using the the state provider channel which in turn provides an application state to the state requester. - * - * @param target State provider. If null the coordinator is used by default - * @param timeout The number of milliseconds to wait for the operation to complete successfully. - * 0 waits until the state has been received - * - * @see MessageListener#getState(java.io.OutputStream) - * @see MessageListener#setState(java.io.InputStream) - * - * @exception IllegalStateException The channel was closed or disconnected, or the flush (if present) failed - * @exception StateTransferException When there was a problem during the state transfer - */ + /** + * Retrieves the full state from the target member. + *

+ * State transfer is initiated by invoking getState on this channel. The state provider in turn + * invokes {@link MessageListener#getState(java.io.OutputStream)} callback and sends a state to + * this node, the state receiver. After the state arrives to the state receiver + * {@link MessageListener#setState(java.io.InputStream)} callback is invoked to install the + * state. + * + * @param target + * The state provider. If null the coordinator is used by default + * @param timeout + * The number of milliseconds to wait for the operation to complete successfully. 0 + * waits until the state has been received + * + * @see MessageListener#getState(java.io.OutputStream) + * @see MessageListener#setState(java.io.InputStream) + * + * @exception IllegalStateException + * The channel was closed or disconnected, or the flush (if present) failed + * @exception StateTransferException + * raised if there was a problem during the state transfer + */ abstract public void getState(Address target, long timeout) throws Exception; diff --git a/src/org/jgroups/ChannelListener.java b/src/org/jgroups/ChannelListener.java index 2a3247197de..6252d325168 100644 --- a/src/org/jgroups/ChannelListener.java +++ b/src/org/jgroups/ChannelListener.java @@ -1,13 +1,43 @@ - package org.jgroups; - /** - * Allows a listener to be notified when important channel events occur. For example, when - * a channel is closed, a PullPushAdapter can be notified, and stop accordingly. + * Allows a listener to be notified when an important channel lifecycle event occurs. + *

+ * + * Usually clients do not need to implement ChannelListener interface. However, this interface can + * useful in scenarios when an application opens multiple channels and needs to tracks major + * lifecycle events on those channels from a single location or in scenarios when channel is wrapped + * by JGroups building block installed on top of a channel (RpcDispatcher etc) while a client needs + * to be notified about major channel lifecycle events. + * + * @see Channel#addChannelListener(ChannelListener) + * @see Channel#removeChannelListener(ChannelListener) + * @see Channel#clearChannelListeners() + * + * @author Bela Ban + * @since 2.0 + * */ public interface ChannelListener { - void channelConnected(Channel channel); - void channelDisconnected(Channel channel); - void channelClosed(Channel channel); + + /** + * Channel has been connected notification callback + * + * @param channel the channel that has been connected + */ + void channelConnected(Channel channel); + + /** + * Channel has been disconnected notification callback + * + * @param channel the disconnected channel + */ + void channelDisconnected(Channel channel); + + /** + * Channel has been closed notification callback + * + * @param channel the closed channel + */ + void channelClosed(Channel channel); } diff --git a/src/org/jgroups/Event.java b/src/org/jgroups/Event.java index 6705a01a465..bfcf6b83a24 100644 --- a/src/org/jgroups/Event.java +++ b/src/org/jgroups/Event.java @@ -1,9 +1,9 @@ package org.jgroups; - - /** - * Used for inter-stack and intra-stack communication. + * Event is a JGroups internal class used for inter-stack and intra-stack communication. + * + * @since 2.0 * @author Bela Ban */ public class Event { diff --git a/src/org/jgroups/Global.java b/src/org/jgroups/Global.java index 7884cab9c41..89c6e876efc 100644 --- a/src/org/jgroups/Global.java +++ b/src/org/jgroups/Global.java @@ -4,9 +4,10 @@ import org.jgroups.protocols.SCOPE; /** - * Globals used by JGroups packages. + * Global is a JGroups internal class defining global variables. * - * @author Bela Ban Mar 29, 2004 + * @since 2.0 + * @author Bela Ban */ public class Global { public static final int BYTE_SIZE = Byte.SIZE / 8; // 1 diff --git a/src/org/jgroups/Header.java b/src/org/jgroups/Header.java index d0c3f83cf4b..730022522dc 100644 --- a/src/org/jgroups/Header.java +++ b/src/org/jgroups/Header.java @@ -3,10 +3,12 @@ import org.jgroups.util.Streamable; - /** - * Abstract base class for all headers to be added to a Message. + * Header is a JGroups internal base class for all JGroups headers. Client normally do not need to + * interact with headers unless they are developing their custom protocols. + * * @author Bela Ban + * @since 2.0 */ public abstract class Header implements Streamable { diff --git a/src/org/jgroups/JChannel.java b/src/org/jgroups/JChannel.java index 15bca287458..04da627501e 100644 --- a/src/org/jgroups/JChannel.java +++ b/src/org/jgroups/JChannel.java @@ -24,14 +24,15 @@ import java.util.concurrent.Callable; import java.util.concurrent.ConcurrentMap; - /** - * JChannel is a pure Java implementation of Channel.

- * When a JChannel object is instantiated it automatically builds the associated protocol stack.

- * The configuration of a JChannel is done via XML, e.g. udp.xml inside the JGroups JAR. This file lists all the - * protocols to be used, and for each protocol, its properties (e.g. fragmentation size for the fragmentation - * protocol). + * JChannel is a default implementation of a Channel abstraction. + *

+ * + * JChannel is instantiated using an appropriate form of a protocol stack description. Protocol + * stack can be described using a file, URL or a stream containing XML stack description. + * * @author Bela Ban + * @since 2.0 */ @MBean(description="JGroups channel") public class JChannel extends Channel { @@ -148,8 +149,8 @@ public JChannel(String props) throws Exception { } /** - * Creates a channel with a configurtation based on an input stream. - * @param input An input stream, pointing to a streamed configurtaion + * Creates a channel with a configuration based on an input stream. + * @param input An input stream, pointing to a streamed configuration * @throws Exception */ public JChannel(InputStream input) throws Exception { @@ -171,7 +172,7 @@ public JChannel(ProtocolStackConfigurator configurator) throws Exception { /** * Creates a channel with the same configuration as the channel passed to this constructor. This is used by - * testing code, and should not be used by any other code ! + * testing code, and should not be used by clients ! * @param ch * @throws Exception */ diff --git a/src/org/jgroups/Membership.java b/src/org/jgroups/Membership.java index e7a40e8ad04..eaef0fae858 100644 --- a/src/org/jgroups/Membership.java +++ b/src/org/jgroups/Membership.java @@ -7,34 +7,35 @@ import java.util.*; - /** - * Class to keep track of Addresses. - * The membership object holds a vector of Address objects that are in the same membership. - * Each unique address can only exist once; i.e., doing Membership.add(existing_address) - * will be ignored. + * Represents a membership of a cluster group. Class Membership is not exposed to clients and is + * used by JGroups internally. The membership object holds a list of Address objects that are in the + * same membership. Each unique address can only exist once. + * + * @since 2.0 + * @author Bela Ban */ public class Membership implements Cloneable { /* private vector to hold all the addresses */ private final List

members=new LinkedList
(); protected static final Log log=LogFactory.getLog(Membership.class); - /** - * Public constructor - * Creates a member ship object with zero members - */ + /** + * + * Creates a member ship object with zero members + */ public Membership() { } - /** - * Creates a member ship object with the initial members. - * The Address references are copied out of the vector, so that the - * vector passed in as parameters is not the same reference as the vector - * that the membership class is using - * - * @param initial_members - a list of members that belong to this membership - */ + /** + * Creates a Membership with a given initial members. The Address references are copied out of + * the vector, so that the vector passed in as parameters is not the same reference as the vector + * that the membership class is using + * + * @param initial_members + * - a list of members that belong to this membership + */ public Membership(Collection
initial_members) { if(initial_members != null) add(initial_members); @@ -42,14 +43,13 @@ public Membership(Collection
initial_members) { - /** - * returns a copy (clone) of the members in this membership. - * the vector returned is immutable in reference to this object. - * ie, modifying the vector that is being returned in this method - * will not modify this membership object. - * - * @return a list of members - */ + /** + * Returns a copy (clone) of the members in this membership. The vector returned is immutable in + * reference to this object. ie, modifying the vector that is being returned in this method will + * not modify this membership object. + * + * @return a list of members + */ public List
getMembers() { /*clone so that this objects members can not be manipulated from the outside*/ synchronized(members) { @@ -57,12 +57,10 @@ public List
getMembers() { } } - - /** - * Adds a new member to this membership. - * If the member already exist (Address.equals(Object) returns true then the member will - * not be added to the membership - */ + /** + * Adds a new member to this membership. If the member already exist (Address.equals(Object) + * returns true then the member will not be added to the membership + */ public void add(Address new_member) { synchronized(members) { if(new_member != null && !members.contains(new_member)) { @@ -76,13 +74,15 @@ public void add(Address ... mbrs) { add(mbr); } - /** - * Adds a list of members to this membership - * - * @param v - a vector containing Address objects - * @throws ClassCastException if v contains objects that don't implement the Address interface - * @see #add - */ + /** + * Adds a list of members to this membership + * + * @param v + * - a vector containing Address objects + * @throws ClassCastException + * if v contains objects that don't implement the Address interface + * + */ public final void add(Collection
v) { if(v != null) { for(Iterator
it=v.iterator(); it.hasNext();) { @@ -93,12 +93,13 @@ public final void add(Collection
v) { } - /** - * removes an member from the membership. - * If this member doesn't exist, no action will be performed on the existing membership - * - * @param old_member - the member to be removed - */ + /** + * Removes an member from the membership. If this member doesn't exist, no action will be + * performed on the existing membership + * + * @param old_member + * - the member to be removed + */ public void remove(Address old_member) { if(old_member != null) { synchronized(members) { @@ -108,11 +109,12 @@ public void remove(Address old_member) { } - /** - * removes all the members contained in v from this membership - * - * @param v - a vector containing all the members to be removed - */ + /** + * Removes all the members contained in v from this membership + * + * @param v + * - a vector containing all the members to be removed + */ public void remove(Collection
v) { if(v != null) { synchronized(members) { @@ -123,7 +125,7 @@ public void remove(Collection
v) { /** - * removes all the members from this membership + * Removes all the members from this membership */ public void clear() { synchronized(members) { @@ -131,14 +133,14 @@ public void clear() { } } - /** - * Clear the membership and adds all members of v - * This method will clear out all the old members of this membership by - * invoking the Clear method. - * Then it will add all the all members provided in the vector v - * - * @param v - a vector containing all the members this membership will contain - */ + /** + * Clears the membership and adds all members of v This method will clear out all the old members + * of this membership by invoking the Clear method. Then it will add all the all + * members provided in the vector v + * + * @param v + * - a vector containing all the members this membership will contain + */ public void set(Collection
v) { clear(); if(v != null) { @@ -147,14 +149,14 @@ public void set(Collection
v) { } - /** - * Clear the membership and adds all members of v - * This method will clear out all the old members of this membership by - * invoking the Clear method. - * Then it will add all the all members provided in the vector v - * - * @param m - a membership containing all the members this membership will contain - */ + /** + * Clears the membership and adds all members of a given membership parameter. Prior to setting + * membership this method will clear out all the old members of this membership by invoking the + * clear method. + * + * @param m + * - a membership containing all the members this membership will contain + */ public void set(Membership m) { clear(); if(m != null) { @@ -164,7 +166,7 @@ public void set(Membership m) { /** - * merges membership with the new members and removes suspects + * Merges membership with the new members and removes suspects. * The Merge method will remove all the suspects and add in the new members. * It will do it in the order * 1. Remove suspects @@ -180,12 +182,12 @@ public void merge(Collection
new_mems, Collection
suspects) { } - /** - * Returns true if the provided member belongs to this membership - * - * @param member - * @return true if the member belongs to this membership - */ + /** + * Returns true if the provided member belongs to this membership + * + * @param member + * @return true if the member belongs to this membership + */ public boolean contains(Address member) { if(member == null) return false; synchronized(members) { @@ -205,7 +207,7 @@ public void sort() { /** - * returns a copy of this membership + * Returns a copy of this membership * * @return an exact copy of this membership */ @@ -214,34 +216,33 @@ public Membership copy() { } - /** - * @return a clone of this object. The list of members is copied to a new - * container - */ + /** + * Returns a clone of this object. The list of members is copied to a new container + */ public Object clone() { return new Membership(this.members); } - - /** - * Returns the number of addresses in this membership - * - * @return the number of addresses in this membership - */ + /** + * Returns the number of addresses in this membership + * + * @return the number of addresses in this membership + */ public int size() { synchronized(members) { return members.size(); } } - /** - * Returns the component at the specified index - * - * @param index - 0..size()-1 - * @throws ArrayIndexOutOfBoundsException - if the index is negative or not less than the current size of this Membership object. - * @see java.util.Vector#elementAt - */ - + /** + * Returns the component at the specified index + * + * @param index + * - 0..size()-1 + * @throws ArrayIndexOutOfBoundsException + * - if the index is negative or not less than the current size of this Membership + * object. + */ public Address elementAt(int index) { synchronized(members) { return members.get(index); diff --git a/src/org/jgroups/MembershipListener.java b/src/org/jgroups/MembershipListener.java index c9af87a7fe9..2817296a93c 100644 --- a/src/org/jgroups/MembershipListener.java +++ b/src/org/jgroups/MembershipListener.java @@ -1,59 +1,62 @@ package org.jgroups; - - /** * Allows a listener to be notified when group membership changes. *

- * The MembershipListener interface is similar to the {@link MessageListener} - * interface: every time a new view, a suspicion message, or a - * block event is received, the corresponding method of the class implementing - * MembershipListener will be called. - * Oftentimes the only method containing any functionality will be viewAccepted() - * which notifies the receiver that a new member has joined the group or that an - * existing member has left or crashed. - */ + * The MembershipListener interface is similar to the {@link MessageListener} interface: every time + * a new view, a suspicion message, or a block event is received, the corresponding method of the + * class implementing MembershipListener will be called. MembershipListener is often used in JGroups + * building blocks installed on top of a channel i.e RpcDispatcher and MessageDispatcher. Oftentimes + * the only method containing any functionality will be viewAccepted() which notifies the receiver + * that a new member has joined the group or that an existing member has left or crashed. + * + * @see org.jgroups.blocks.RpcDispatcher + * + * @since 2.0 + * @author Bela Ban + * @author Vladimir Blagojevic + */ public interface MembershipListener { - /** - * Called when a change in membership has occurred. - * No long running actions, sending of messages or anything that could block should be done in this callback. - * If some long running action needs to be performed, it should be done in a separate thread.

- * Note that on reception of the first view (a new member just joined), the channel will not yet be - * in the connected state. This only happens when {@link Channel#connect(String)} returns. - */ + /** + * Called when a change in membership has occurred. No long running actions, sending of messages + * or anything that could block should be done in this callback. If some long running action + * needs to be performed, it should be done in a separate thread. + *

+ * Note that on reception of the first view (a new member just joined), the channel will not yet + * be in the connected state. This only happens when {@link Channel#connect(String)} returns. + */ void viewAccepted(View new_view); - /** - * Called whenever a member is suspected of having crashed, - * but has not yet been excluded. - */ + /** + * Called whenever a member is suspected of having crashed, but has not yet been excluded. + */ void suspect(Address suspected_mbr); - /** - * Called (usually by the FLUSH protocol), as an indication that the member should stop sending messages. - * Any messages sent after returning from this callback might get blocked by the FLUSH protocol. When the FLUSH - * protocol is done, and messages can be sent again, the FLUSH protocol will simply unblock all pending messages. - * If a callback for unblocking is desired, implement {@link org.jgroups.ExtendedMembershipListener#unblock()}. - * Note that block() is the equivalent of reception of a BlockEvent in the pull mode. - */ + /** + * Called (usually by the FLUSH protocol), as an indication that the member should stop sending + * messages. Any messages sent after returning from this callback might get blocked by the FLUSH + * protocol. When the FLUSH protocol is done, and messages can be sent again, the FLUSH protocol + * will simply unblock all pending messages. If a callback for unblocking is desired, implement + * {@link org.jgroups.ExtendedMembershipListener#unblock()}. Note that block() is the equivalent + * of reception of a BlockEvent in the pull mode. + */ void block(); - - /** - * Called after the FLUSH protocol has unblocked previously blocked senders, and - * messages can be sent again. This callback only needs to be implemented if we require a - * notification of that. - * - *

- * Note that during new view installation we provide guarantee that unblock invocation strictly - * follows view installation at some node A belonging to that view . However, some other message - * M may squeeze in between view and unblock callbacks. - * - * For more details see https://jira.jboss.org/jira/browse/JGRP-986 - * - */ + /** + * Called after the FLUSH protocol has unblocked previously blocked senders, and + * messages can be sent again. This callback only needs to be implemented if we require a + * notification of that. + * + *

+ * Note that during new view installation we provide guarantee that unblock invocation strictly + * follows view installation at some node A belonging to that view . However, some other message + * M may squeeze in between view and unblock callbacks. + * + * For more details see https://jira.jboss.org/jira/browse/JGRP-986 + * + */ void unblock(); } diff --git a/src/org/jgroups/MergeView.java b/src/org/jgroups/MergeView.java index 7d3836c4f22..084a6362467 100644 --- a/src/org/jgroups/MergeView.java +++ b/src/org/jgroups/MergeView.java @@ -6,17 +6,17 @@ import java.util.ArrayList; import java.util.List; - /** - * A view that is sent as a result of a merge. - * Whenever a group splits into subgroups, e.g., due to a network partition, - * and later the subgroups merge back together, a MergeView instead of a View - * will be received by the application. The MergeView class is a subclass of - * View and contains as additional instance variable: the list of views that - * were merged. For example, if the group denoted by view V1:(p,q,r,s,t) - * splits into subgroups V2:(p,q,r) and V2:(s,t), the merged view might be - * V3:(p,q,r,s,t). In this case the MergeView would contain a list of 2 views: - * V2:(p,q,r) and V2:(s,t). + * A view that is sent as a result of a cluster merge. Whenever a group splits into subgroups, e.g., due to + * a network partition, and later the subgroups merge back together, a MergeView instead of a View + * will be received by the application. The MergeView class is a subclass of View and contains as + * additional instance variable: the list of views that were merged. For example, if the group + * denoted by view V1:(p,q,r,s,t) splits into subgroups V2:(p,q,r) and V2:(s,t), the merged view + * might be V3:(p,q,r,s,t). In this case the MergeView would contain a list of 2 views: V2:(p,q,r) + * and V2:(s,t). + * + * @since 2.0 + * @author Bela Ban */ public class MergeView extends View { protected List subgroups=null; // subgroups that merged into this single view (a list of Views) @@ -29,27 +29,34 @@ public MergeView() { } - /** - * Creates a new view - * - * @param vid The view id of this view (can not be null) - * @param members Contains a list of all the members in the view, can be empty but not null. - * @param subgroups A list of Views representing the former subgroups - */ + /** + * Creates a new view + * + * @param vid + * The view id of this view (can not be null) + * @param members + * Contains a list of all the members in the view, can be empty but not null. + * @param subgroups + * A list of Views representing the former subgroups + */ public MergeView(ViewId vid, List

members, List subgroups) { super(vid, members); this.subgroups=subgroups; } - /** - * Creates a new view - * - * @param creator The creator of this view (can not be null) - * @param id The lamport timestamp of this view - * @param members Contains a list of all the members in the view, can be empty but not null. - * @param subgroups A list of Views representing the former subgroups - */ + /** + * Creates a new view + * + * @param creator + * The creator of this view (can not be null) + * @param id + * The lamport timestamp of this view + * @param members + * Contains a list of all the members in the view, can be empty but not null. + * @param subgroups + * A list of Views representing the former subgroups + */ public MergeView(Address creator, long id, List
members, List subgroups) { super(creator, id, members); this.subgroups=subgroups; @@ -60,12 +67,11 @@ public List getSubgroups() { return subgroups; } - - /** - * creates a copy of this view - * - * @return a copy of this view - */ + /** + * Creates a copy of this view + * + * @return a copy of this view + */ public Object clone() { ViewId vid2=vid != null ? (ViewId)vid.clone() : null; List
members2=members != null ? new ArrayList
(members) : null; diff --git a/src/org/jgroups/Message.java b/src/org/jgroups/Message.java index 2bc5754cab8..3ee20cda2c3 100644 --- a/src/org/jgroups/Message.java +++ b/src/org/jgroups/Message.java @@ -13,15 +13,16 @@ import java.io.*; import java.util.Map; - /** * A Message encapsulates data sent to members of a group. It contains among other things the - * address of the sender, the destination address, a payload (byte buffer) and a list of - * headers. Headers are added by protocols on the sender side and removed by protocols - * on the receiver's side. + * address of the sender, the destination address, a payload (byte buffer) and a list of headers. + * Headers are added by protocols on the sender side and removed by protocols on the receiver's + * side. *

* The byte buffer can point to a reference, and we can subset it using index and length. However, * when the message is serialized, we only write the bytes between index and length. + * + * @since 2.0 * @author Bela Ban */ public class Message implements Streamable { @@ -71,22 +72,32 @@ public class Message implements Streamable { - /** Public constructor - * @param dest Address of receiver. If it is null then the message sent to the group. - * Otherwise, it contains a single destination and is sent to that member.

- */ + /** + * Constructs a Message given a destination Address + * + * @param dest + * Address of receiver. If it is null then the message sent to the group. + * Otherwise, it contains a single destination and is sent to that member. + *

+ */ public Message(Address dest) { setDest(dest); headers=createHeaders(3); } - /** Public constructor - * @param dest Address of receiver. If it is null then the message sent to the group. - * Otherwise, it contains a single destination and is sent to that member.

- * @param src Address of sender - * @param buf Message to be sent. Note that this buffer must not be modified (e.g. buf[0]=0 is - * not allowed), since we don't copy the contents on clopy() or clone(). - */ + /** + * Constructs a Message given a destination Address, a source Address and the payload byte buffer + * + * @param dest + * Address of receiver. If it is null then the message sent to the group. + * Otherwise, it contains a single destination and is sent to that member. + *

+ * @param src + * Address of sender + * @param buf + * Message to be sent. Note that this buffer must not be modified (e.g. buf[0]=0 is not + * allowed), since we don't copy the contents on clopy() or clone(). + */ public Message(Address dest, Address src, byte[] buf) { this(dest); setSrc(src); @@ -94,23 +105,31 @@ public Message(Address dest, Address src, byte[] buf) { } - /** - * Constructs a message. The index and length parameters allow to provide a reference to - * a byte buffer, rather than a copy, and refer to a subset of the buffer. This is important when - * we want to avoid copying. When the message is serialized, only the subset is serialized.
- * - * Note that the byte[] buffer passed as argument must not be modified. Reason: if we retransmit the - * message, it would still have a ref to the original byte[] buffer passed in as argument, and so we would - * retransmit a changed byte[] buffer ! - * - * @param dest Address of receiver. If it is null then the message sent to the group. - * Otherwise, it contains a single destination and is sent to that member.

- * @param src Address of sender - * @param buf A reference to a byte buffer - * @param offset The index into the byte buffer - * @param length The number of bytes to be used from buf. Both index and length are checked for - * array index violations and an ArrayIndexOutOfBoundsException will be thrown if invalid - */ + /** + * Constructs a message. The index and length parameters allow to provide a reference to + * a byte buffer, rather than a copy, and refer to a subset of the buffer. This is important when + * we want to avoid copying. When the message is serialized, only the subset is serialized.
+ * + * Note that the byte[] buffer passed as argument must not be modified. Reason: if we retransmit the + * message, it would still have a ref to the original byte[] buffer passed in as argument, and so we would + * retransmit a changed byte[] buffer ! + * + * + * @param dest + * Address of receiver. If it is null then the message sent to the group. + * Otherwise, it contains a single destination and is sent to that member. + *

+ * @param src + * Address of sender + * @param buf + * A reference to a byte buffer + * @param offset + * The index into the byte buffer + * @param length + * The number of bytes to be used from buf. Both index and length are checked + * for array index violations and an ArrayIndexOutOfBoundsException will be thrown if + * invalid + */ public Message(Address dest, Address src, byte[] buf, int offset, int length) { this(dest); setSrc(src); @@ -118,15 +137,23 @@ public Message(Address dest, Address src, byte[] buf, int offset, int length) { } - /** Public constructor - * @param dest Address of receiver. If it is null then the message sent to the group. - * Otherwise, it contains a single destination and is sent to that member.

- * @param src Address of sender - * @param obj The object will be marshalled into the byte buffer. Obj has to be serializable (e.g. implementing - * Serializable, Externalizable or Streamable, or be a basic type (e.g. Integer, Short etc)).! - * The resulting buffer must not be modified - * (e.g. buf[0]=0 is not allowed), since we don't copy the contents on clopy() or clone().

- */ + /** + * Constructs a Message given a destination Address, a source Address and the payload Object + * + * @param dest + * Address of receiver. If it is null then the message sent to the group. + * Otherwise, it contains a single destination and is sent to that member. + *

+ * @param src + * Address of sender + * @param obj + * The object will be marshalled into the byte buffer. + * Obj has to be serializable (e.g. implementing + * Serializable, Externalizable or Streamable, or be a basic type (e.g. Integer, Short etc)). + * ! The resulting buffer must not be modified (e.g. buf[0]=0 is not allowed), since we + * don't copy the contents on clopy() or clone(). + *

+ */ public Message(Address dest, Address src, Object obj) { this(dest); setSrc(src); @@ -160,20 +187,21 @@ public void setSrc(Address new_src) { src_addr=new_src; } - /** - * Returns a reference to the payload (byte buffer). Note that this buffer should not be modified as - * we do not copy the buffer on copy() or clone(): the buffer of the copied message is simply a reference to - * the old buffer.
- * Even if offset and length are used: we return the entire buffer, not a subset. - */ + /** + * Returns a reference to the payload (byte buffer). Note that this buffer should not be + * modified as we do not copy the buffer on copy() or clone(): the buffer of the copied message + * is simply a reference to the old buffer.
+ * Even if offset and length are used: we return the entire buffer, not a subset. + */ public byte[] getRawBuffer() { return buf; } - /** - * Returns a copy of the buffer if offset and length are used, otherwise a reference. - * @return byte array with a copy of the buffer. - */ + /** + * Returns a copy of the buffer if offset and length are used, otherwise a reference. + * + * @return byte array with a copy of the buffer. + */ final public byte[] getBuffer() { if(buf == null) return null; @@ -197,12 +225,16 @@ final public void setBuffer(byte[] b) { } } - /** - * Set the internal buffer to point to a subset of a given buffer - * @param b The reference to a given buffer. If null, we'll reset the buffer to null - * @param offset The initial position - * @param length The number of bytes - */ + /** + * Set the internal buffer to point to a subset of a given buffer + * + * @param b + * The reference to a given buffer. If null, we'll reset the buffer to null + * @param offset + * The initial position + * @param length + * The number of bytes + */ final public void setBuffer(byte[] b, int offset, int length) { buf=b; if(buf != null) { @@ -218,13 +250,13 @@ final public void setBuffer(byte[] b, int offset, int length) { } } - /** - - * Note that the byte[] buffer passed as argument must not be modified. Reason: if we retransmit the - * message, it would still have a ref to the original byte[] buffer passed in as argument, and so we would - * retransmit a changed byte[] buffer ! - * - */ + /** + * + * Note that the byte[] buffer passed as argument must not be modified. Reason: if we retransmit the + * message, it would still have a ref to the original byte[] buffer passed in as argument, and so we would + * retransmit a changed byte[] buffer ! + * + */ public final void setBuffer(Buffer buf) { if(buf != null) { this.buf=buf.getBuf(); @@ -233,18 +265,28 @@ public final void setBuffer(Buffer buf) { } } - /** Returns the offset into the buffer at which the data starts */ + /** + * + * Returns the offset into the buffer at which the data starts + * + */ public int getOffset() { return offset; } - /** Returns the number of bytes in the buffer */ + /** + * + * Returns the number of bytes in the buffer + * + */ public int getLength() { return length; } - /** Returns a reference to the headers hashmap, which is immutable. Any attempt to - * modify the returned map will cause a runtime exception */ + /** + * Returns a reference to the headers hashmap, which is immutable. Any attempt to modify + * the returned map will cause a runtime exception + */ public Map getHeaders() { return headers.getHeaders(); } @@ -257,11 +299,11 @@ public int getNumHeaders() { return headers.size(); } - /** - * Takes an object and uses Java serialization to generate the byte[] buffer which is set in the message. Parameter - * 'obj' has to be serializable (e.g. implementing Serializable, Externalizable or Streamable, or be a basic - * type (e.g. Integer, Short etc)). - */ + /** + * Takes an object and uses Java serialization to generate the byte[] buffer which is set in the + * message. Parameter 'obj' has to be serializable (e.g. implementing Serializable, + * Externalizable or Streamable, or be a basic type (e.g. Integer, Short etc)). + */ final public void setObject(Object obj) { if(obj == null) return; if(obj instanceof Buffer) { @@ -278,14 +320,16 @@ final public void setObject(Object obj) { } } - /** - * Uses custom serialization to create an object from the buffer of the message. Note that this is dangerous when - * using your own classloader, e.g. inside of an application server ! Most likely, JGroups will use the system - * classloader to deserialize the buffer into an object, whereas (for example) a web application will want to - * use the webapp's classloader, resulting in a ClassCastException. The recommended way is for the application to - * use their own serialization and only pass byte[] buffer to JGroups. - * @return - */ + /** + * Uses custom serialization to create an object from the buffer of the message. Note that this + * is dangerous when using your own classloader, e.g. inside of an application server ! Most + * likely, JGroups will use the system classloader to deserialize the buffer into an object, + * whereas (for example) a web application will want to use the webapp's classloader, resulting + * in a ClassCastException. The recommended way is for the application to use their own + * serialization and only pass byte[] buffer to JGroups. + * + * @return + */ final public Object getObject() { try { return Util.objectFromByteBuffer(buf, offset, length); @@ -312,22 +356,25 @@ public boolean isFlagSet(byte flag) { return isFlagSet(flags, flag); } - /** - * Same as {@link #setFlag(byte)} but transient flags are never marshalled - * @param flag - */ + /** + * Same as {@link #setFlag(byte)} but transient flags are never marshalled + * + * @param flag + */ public void setTransientFlag(byte flag) { if(flag > Byte.MAX_VALUE || flag < 0) throw new IllegalArgumentException("flag has to be >= 0 and <= " + Byte.MAX_VALUE); transient_flags |= flag; } - /** - * Atomically checks if a given flag is set and - if not - sets it. When multiple threads concurrently call this - * method with the same flag, only one of them will be able to set the flag - * @param flag - * @return True if the flag could be set, false if not (was already set) - */ + /** + * Atomically checks if a given flag is set and - if not - sets it. When multiple threads + * concurrently call this method with the same flag, only one of them will be able to set the + * flag + * + * @param flag + * @return True if the flag could be set, false if not (was already set) + */ public boolean setTransientFlagIfAbsent(byte flag) { if(flag > Byte.MAX_VALUE || flag < 0) throw new IllegalArgumentException("flag has to be >= 0 and <= " + Byte.MAX_VALUE); @@ -381,14 +428,15 @@ public void putHeader(short id, Header hdr) { headers.putHeader(id, hdr); } - /** - * Puts a header given a key into the map, only if the key doesn't exist yet - * @param id - * @param hdr - * @return the previous value associated with the specified key, or null if there was no mapping for the key. - * (A null return can also indicate that the map previously associated null with the key, - * if the implementation supports null values.) - */ + /** + * Puts a header given a key into the map, only if the key doesn't exist yet + * + * @param id + * @param hdr + * @return the previous value associated with the specified key, or null if there was no + * mapping for the key. (A null return can also indicate that the map previously + * associated null with the key, if the implementation supports null values.) + */ public Header putHeaderIfAbsent(short id, Header hdr) { if(id <= 0) throw new IllegalArgumentException("An ID of " + id + " is invalid"); @@ -409,23 +457,28 @@ public Message copy() { return copy(true); } - /** - * Create a copy of the message. If offset and length are used (to refer to another buffer), the copy will - * contain only the subset offset and length point to, copying the subset into the new copy. - * @param copy_buffer - * @return Message with specified data - */ + /** + * Create a copy of the message. If offset and length are used (to refer to another buffer), the + * copy will contain only the subset offset and length point to, copying the subset into the new + * copy. + * + * @param copy_buffer + * @return Message with specified data + */ public Message copy(boolean copy_buffer) { return copy(copy_buffer, true); } - /** - * Create a copy of the message. If offset and length are used (to refer to another buffer), the copy will - * contain only the subset offset and length point to, copying the subset into the new copy. - * @param copy_buffer - * @param copy_headers Copy the headers - * @return Message with specified data - */ + /** + * Create a copy of the message. If offset and length are used (to refer to another buffer), the + * copy will contain only the subset offset and length point to, copying the subset into the new + * copy. + * + * @param copy_buffer + * @param copy_headers + * Copy the headers + * @return Message with specified data + */ public Message copy(boolean copy_buffer, boolean copy_headers) { Message retval=new Message(false); retval.dest_addr=dest_addr; @@ -442,12 +495,13 @@ public Message copy(boolean copy_buffer, boolean copy_headers) { return retval; } - /** - * Doesn't copy any headers except for those with ID >= copy_headers_above - * @param copy_buffer - * @param starting_id - * @return A message with headers whose ID are >= starting_id - */ + /** + * Doesn't copy any headers except for those with ID >= copy_headers_above + * + * @param copy_buffer + * @param starting_id + * @return A message with headers whose ID are >= starting_id + */ public Message copy(boolean copy_buffer, short starting_id) { Message retval=copy(copy_buffer, false); if(starting_id > 0) { @@ -580,13 +634,14 @@ public void writeTo(DataOutput out) throws Exception { } } - /** - * Writes the message to the output stream, but excludes the dest and src addresses unless the src address given - * as argument is different from the message's src address - * @param src - * @param out - * @throws Exception - */ + /** + * Writes the message to the output stream, but excludes the dest and src addresses unless the + * src address given as argument is different from the message's src address + * + * @param src + * @param out + * @throws Exception + */ public void writeToNoAddrs(Address src, DataOutputStream out) throws Exception { byte leading=0; @@ -669,13 +724,14 @@ public void readFrom(DataInput in) throws Exception { /* --------------------------------- End of Interface Streamable ----------------------------- */ - - /** - * Returns the exact size of the marshalled message. Uses method size() of each header to compute the size, so if - * a Header subclass doesn't implement size() we will use an approximation. However, most relevant header subclasses - * have size() implemented correctly. (See org.jgroups.tests.SizeTest). - * @return The number of bytes for the marshalled message - */ + /** + * Returns the exact size of the marshalled message. Uses method size() of each header to compute + * the size, so if a Header subclass doesn't implement size() we will use an approximation. + * However, most relevant header subclasses have size() implemented correctly. (See + * org.jgroups.tests.SizeTest). + * + * @return The number of bytes for the marshalled message + */ public long size() { long retval=Global.BYTE_SIZE // leading byte + Global.BYTE_SIZE; // flags diff --git a/src/org/jgroups/MessageListener.java b/src/org/jgroups/MessageListener.java index c7fdeb3a707..3485c69d93d 100644 --- a/src/org/jgroups/MessageListener.java +++ b/src/org/jgroups/MessageListener.java @@ -5,36 +5,55 @@ import java.io.OutputStream; /** - * Allows a listener to be notified when message or state transfer events arrive. + * MessageListener allows a listener to be notified when a {@link Message} or a state transfer + * events arrives to a node. + *

+ * MessageListener is often used by JGroups building blocks installed on top of a channel i.e + * RpcDispatcher and MessageDispatcher. + * + * + * @see org.jgroups.blocks.RpcDispatcher + * @see org.jgroups.blocks.MessageDispatcher + * + * @since 2.0 + * @author Bela Ban + * @author Vladimir Blagojevic */ public interface MessageListener { - /** - * Called when a message is received. - * @param msg - */ + + /** + * Called when a message is received. + * + * @param msg + */ void receive(Message msg); - /** - * Allows an application to write a state through a provided OutputStream. When done, the OutputStream doesn't need - * to be closed; this is done automatically when returning from the callback - * - * @param output the OutputStream - * @throws Exception if the streaming fails, any exceptions should be thrown so that the state requester can - * re-throw them and let the caller know what happened - * @see java.io.OutputStream#close() - */ + /** + * Allows an application to write a state through a provided OutputStream. After the state has + * been written the OutputStream doesn't need to be closed as stream closing is automatically + * done when a calling thread returns from this callback. + * + * @param output + * the OutputStream + * @throws Exception + * if the streaming fails, any exceptions should be thrown so that the state requester + * can re-throw them and let the caller know what happened + * @see java.io.OutputStream#close() + */ void getState(OutputStream output) throws Exception; - - /** - * Allows an application to read a state through a provided InputStream. When done, the InputStream doesn't need - * to be closed; this is done automatically when returning from the callback - * - * @param input the InputStream - * @throws Exception if the streaming fails, any exceptions should be thrown so that the state requester can - * catch them and thus know what happened - * @see java.io.InputStream#close() - */ + /** + * Allows an application to read a state through a provided InputStream. After the state has been + * read the InputStream doesn't need to be closed as stream closing is automatically done when a + * calling thread returns from this callback. + * + * @param input + * the InputStream + * @throws Exception + * if the streaming fails, any exceptions should be thrown so that the state requester + * can catch them and thus know what happened + * @see java.io.InputStream#close() + */ void setState(InputStream input) throws Exception; } diff --git a/src/org/jgroups/PhysicalAddress.java b/src/org/jgroups/PhysicalAddress.java index 52aa83b62ba..0d75a77fa17 100644 --- a/src/org/jgroups/PhysicalAddress.java +++ b/src/org/jgroups/PhysicalAddress.java @@ -1,7 +1,12 @@ package org.jgroups; +import org.jgroups.util.UUID; + /** * Represents a physical (as opposed to logical) address + * + * @see UUID + * @since 2.6 * @author Bela Ban */ public interface PhysicalAddress extends Address { diff --git a/src/org/jgroups/Receiver.java b/src/org/jgroups/Receiver.java index 7f3cf97f5f0..daa106ac5c1 100644 --- a/src/org/jgroups/Receiver.java +++ b/src/org/jgroups/Receiver.java @@ -2,6 +2,9 @@ /** * Defines the callbacks that are invoked when messages, views etc are received on a channel + * + * @see Channel#setReceiver(Receiver) + * @since 2.0 * @author Bela Ban */ public interface Receiver extends MessageListener, MembershipListener { diff --git a/src/org/jgroups/ReceiverAdapter.java b/src/org/jgroups/ReceiverAdapter.java index a6490dec34a..140fcc6a6ba 100644 --- a/src/org/jgroups/ReceiverAdapter.java +++ b/src/org/jgroups/ReceiverAdapter.java @@ -4,28 +4,54 @@ import java.io.OutputStream; /** + * An adapter implementing the Receiver interface with no-op implementations. When implementing a + * callback, we can simply extend ReceiverAdapter and overwrite receive() in order to not having to + * implement all callbacks of the interface. + * + * @since 2.0 * @author Bela Ban */ public class ReceiverAdapter implements Receiver { - public void receive(Message msg) { + /** + * {@inheritDoc} + */ + public void receive(Message msg) { } + /** + * {@inheritDoc} + */ public void getState(OutputStream output) throws Exception { } + /** + * {@inheritDoc} + */ public void setState(InputStream input) throws Exception { } + /** + * {@inheritDoc} + */ public void viewAccepted(View view) { } + /** + * {@inheritDoc} + */ public void suspect(Address mbr) { } + /** + * {@inheritDoc} + */ public void block() { } + /** + * {@inheritDoc} + */ public void unblock() { } } diff --git a/src/org/jgroups/StateTransferException.java b/src/org/jgroups/StateTransferException.java index d1116f562cf..e4ee54b7ab7 100644 --- a/src/org/jgroups/StateTransferException.java +++ b/src/org/jgroups/StateTransferException.java @@ -1,13 +1,12 @@ package org.jgroups; - /** - * StateTransferException is thrown to indicate failure of - * state transfer between cluster members. + * StateTransferException is thrown to indicate a failure of a state transfer between + * cluster members. *

* - * @author Vladimir Blagojevic - * @since 2.6 + * @author Vladimir Blagojevic + * @since 2.6 * */ public class StateTransferException extends Exception { diff --git a/src/org/jgroups/SuspectedException.java b/src/org/jgroups/SuspectedException.java index 10ad72821fa..fa488be0b2a 100644 --- a/src/org/jgroups/SuspectedException.java +++ b/src/org/jgroups/SuspectedException.java @@ -3,6 +3,9 @@ /** * Thrown if a message is sent to a suspected member. + * + * @since 2.0 + * @author Bela Ban */ public class SuspectedException extends Exception { final Object suspect; diff --git a/src/org/jgroups/TimeoutException.java b/src/org/jgroups/TimeoutException.java index 402f2e3ab96..d3199e5525e 100644 --- a/src/org/jgroups/TimeoutException.java +++ b/src/org/jgroups/TimeoutException.java @@ -3,6 +3,9 @@ /** * Thrown if members fail to respond in time. + * + * @since 2.0 + * @author Bela Ban */ public class TimeoutException extends RuntimeException { diff --git a/src/org/jgroups/UpHandler.java b/src/org/jgroups/UpHandler.java index 39f47dc9acc..a2ef2faab1d 100644 --- a/src/org/jgroups/UpHandler.java +++ b/src/org/jgroups/UpHandler.java @@ -2,12 +2,21 @@ package org.jgroups; /** - * Provides a way of taking over a channel's tasks. + * Provides a hook to hijack over all events received by a certain channel which has installed this + * UpHandler. + *

+ * Client usually never need to implement this interface and it is mostly used by JGroups building + * blocks. + * + * @since 2.0 + * @author Bela Ban */ public interface UpHandler { - /** - * Invoked for all channel events except connection management and state transfer. - * @param evt - */ + + /** + * Invoked for all channel events except connection management and state transfer. + * + * @param evt + */ Object up(Event evt); } diff --git a/src/org/jgroups/View.java b/src/org/jgroups/View.java index b72165680f6..fbaeabd0c6d 100644 --- a/src/org/jgroups/View.java +++ b/src/org/jgroups/View.java @@ -8,38 +8,36 @@ import java.io.*; import java.util.*; - /** - * A view is a local representation of the current membership of a group. - * Only one view is installed in a channel at a time. - * Views contain the address of its creator, an ID and a list of member addresses. - * These addresses are ordered, and the first address is always the coordinator of the view. - * This way, each member of the group knows who the new coordinator will be if the current one - * crashes or leaves the group. - * The views are sent between members using the VIEW_CHANGE event + * A view is a local representation of the current membership of a group. Only one view is installed + * in a channel at a time. Views contain the address of its creator, an ID and a list of member + * addresses. These addresses are ordered, and the first address is always the coordinator of the + * view. This way, each member of the group knows who the new coordinator will be if the current one + * crashes or leaves the group. The views are sent between members using the VIEW_CHANGE event + * + * @since 2.0 * @author Bela Ban */ public class View implements Cloneable, Streamable, Iterable

{ - /* A view is uniquely identified by its ViewID - * The view id contains the creator address and a Lamport time. - * The Lamport time is the highest timestamp seen or sent from a view. - * if a view change comes in with a lower Lamport time, the event is discarded. + /** + * A view is uniquely identified by its ViewID. The view id contains the creator address and a + * Lamport time. The Lamport time is the highest timestamp seen or sent from a view. if a view + * change comes in with a lower Lamport time, the event is discarded. */ protected ViewId vid=null; - /** - * A list containing all the members of the view - * This list is always ordered, with the coordinator being the first member. - * the second member will be the new coordinator if the current one disappears - * or leaves the group. - */ + /** + * A list containing all the members of the view.This list is always ordered, with the + * coordinator being the first member. the second member will be the new coordinator if the + * current one disappears or leaves the group. + */ protected List
members=null; /** - * creates an empty view, should not be used + * Creates an empty view, should not be used */ public View() { } @@ -69,7 +67,7 @@ public View(Address creator, long id, List
members) { /** - * returns the view ID of this view + * Returns the view ID of this view * if this view was created with the empty constructur, null will be returned * * @return the view ID of this view @@ -81,7 +79,7 @@ public ViewId getVid() { public ViewId getViewId() {return vid;} /** - * returns the creator of this view + * Returns the creator of this view * if this view was created with the empty constructur, null will be returned * * @return the creator of this view in form of an Address object @@ -102,7 +100,7 @@ public List
getMembers() { } /** - * returns true, if this view contains a certain member + * Returns true, if this view contains a certain member * * @param mbr - the address of the member, * @return true if this view contains the member, false if it doesn't @@ -137,7 +135,7 @@ public int hashCode() { } /** - * returns the number of members in this view + * Returns the number of members in this view * * @return the number of members in this view 0..n */ @@ -153,7 +151,7 @@ public View copy() { /** - * creates a copy of this view + * Creates a copy of this view * @return a copy of this view */ public Object clone() { diff --git a/src/org/jgroups/util/UUID.java b/src/org/jgroups/util/UUID.java index ff29f11ee97..bf251c3a220 100644 --- a/src/org/jgroups/util/UUID.java +++ b/src/org/jgroups/util/UUID.java @@ -9,10 +9,11 @@ import java.util.Collection; import java.util.Map; -/** Logical address which is unique over space and time. - *
+/** + * Logical address which is unique over space and time.
* Copied from java.util.UUID, but unneeded fields from the latter have been removed. UUIDs needs to * have a small memory footprint. + * * @author Bela Ban */ public class UUID implements Address, Streamable, Comparable
{