Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Javadoc cleanup

  • Loading branch information...
commit e7b1a2b7102a0593754f5641cdbb76e9a810751b 1 parent 225b2c0
@vblagoje vblagoje authored
View
14 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<Address>, Cloneable {
// flags used for marshalling
View
494 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).<p/>
-
- The FSM for a channel is roughly as follows: a channel is created (<em>unconnected</em>). The channel is connected to
- a group (<em>connected</em>). Messages can now be sent and received. The channel is disconnected from the group
- (<em>unconnected</em>). The channel could now be connected to a different group again.
- The channel is closed (<em>closed</em>).<p/>
-
- 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.<p/>
-
- Messages can be sent to the group members using the <em>send</em> method and messages
- can be received setting a {@link Receiver} in {@link #setReceiver(Receiver)} and implementing the
- {@link Receiver#receive(Message)} callback.<p>
-
- A channel instance is created using the public constructor.<p/>
- 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).
+ * <p/>
+ *
+ * The FSM for a channel is roughly as follows: a channel is created (<em>unconnected</em>). The
+ * channel is connected to a group (<em>connected</em>). Messages can now be sent and received. The
+ * channel is disconnected from the group (<em>unconnected</em>). The channel could now be connected
+ * to a different group again. The channel is closed (<em>closed</em>).
+ * <p/>
+ *
+ * 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.
+ * <p/>
+ *
+ * Messages can be sent to the group members using the <em>send</em> method and messages can be
+ * received setting a {@link Receiver} in {@link #setReceiver(Receiver)} and implementing the
+ * {@link Receiver#receive(Message)} callback.
+ * <p>
+ *
+ * A channel instance is created using the public constructor.
+ * <p/>
+ * 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.<p>
-
- 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.<p>
-
- @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.
+ * <p>
+ *
+ * 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.
+ * <p>
+ *
+ * @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 @@ public void setSocketFactory(SocketFactory factory) {
* This method essentially invokes
* <code>connect<code> and <code>getState<code> 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 <code>connect<code> and <code>getState<code> in succesion.
+ * fetching state rather than two flushes if we invoke <code>connect<code> and <code>getState<code> in succession.
*
* If the channel is closed an exception will be thrown.
*
@@ -111,144 +122,184 @@ public void setSocketFactory(SocketFactory factory) {
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<br/>
- * 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<br/>
+ * 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 <code>ChannelClosed</code> exception
- (or results in a null operation). It is a null operation if the channel is already closed.<p>
- If the channel is connected to a group, <code>disconnec()t</code> 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 <code>ChannelClosed</code> exception (or
+ * results in a null operation). It is a null operation if the channel is already closed.
+ * <p>
+ * If the channel is connected to a group, <code>disconnect()</code> 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<String,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<String,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<String,Object> dumpStats();
- /** Sends a message. The message contains
- <ol>
- <li>a destination address (Address). A <code>null</code> address sends the message
- to all group members.
- <li>a source address. Can be left empty. Will be filled in by the protocol stack.
- <li>a byte buffer. The message contents.
- <li>several additional fields. They can be used by application programs (or patterns). E.g.
- a message ID, flags etc
- </ol>
- @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
+ * <ol>
+ * <li>a destination address (Address). A <code>null</code> address sends the message to all
+ * group members.
+ * <li>a source address. Can be left empty as it will be assigned automatically
+ * <li>a byte buffer. The message contents.
+ * <li>several additional fields. They can be used by application programs (or patterns). E.g. a
+ * message ID, flags etc
+ * </ol>
+ *
+ * @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 <em>
- not</em> 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 <em>not</em> 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
- * <code>length</code> bytes starting at <code>offset</code>
- * @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
+ * <code>length</code> bytes starting at <code>offset</code>
+ * @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
- * <code>connect()</code>. 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
+ * <code>connect()</code>. 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 <code>send()</code> 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 <code>send()</code> 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 <code>member</code>
- */
+ /**
+ * 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 <code>member</code>
+ */
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 <em>before</em> 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 <em>before</em>
+ * 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 <code>connect()</code>. Calling this method on a closed
- channel returns <code>null</code>.
- @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 <code>connect()</code>. Calling this method on a closed channel
+ * returns <code>null</code>.
+ *
+ * @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.
- * <p/>
- * 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.
- * <p/>
- *
- * @param automatic_resume
- * Call {@link #stopFlush()} after the flush
- * @see #startFlush(boolean)
- */
+ /**
+ * Performs a partial flush in a cluster for flush participants.
+ * <p/>
+ * 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.
+ * <p/>
+ *
+ * @param automatic_resume
+ * if true call {@link #stopFlush()} after the flush
+ * @see #startFlush(boolean)
+ */
abstract public void startFlush(List<Address> 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.
- * <p/>
- * 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.
+ * <p/>
+ * 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<Address> flushParticipants, boolean automat
abstract public void stopFlush(List<Address> flushParticipants);
- /**
- * Retrieves the full state from the target member.
- * <p>
- * 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.
+ * <p>
+ * 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;
View
44 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.
+ * <p>
+ *
+ * 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);
}
View
6 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 {
View
5 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
View
6 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 {
View
19 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.<p/>
- * When a JChannel object is instantiated it automatically builds the associated protocol stack.<p/>
- * 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.
+ * <p/>
+ *
+ * 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
*/
View
185 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<Address> members=new LinkedList<Address>();
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<Address> initial_members) {
if(initial_members != null)
add(initial_members);
@@ -42,14 +43,13 @@ public Membership(Collection<Address> 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<Address> getMembers() {
/*clone so that this objects members can not be manipulated from the outside*/
synchronized(members) {
@@ -57,12 +57,10 @@ public Membership(Collection<Address> initial_members) {
}
}
-
- /**
- * 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<Address> v) {
if(v != null) {
for(Iterator<Address> it=v.iterator(); it.hasNext();) {
@@ -93,12 +93,13 @@ public final void add(Collection<Address> 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<Address> v) {
if(v != null) {
synchronized(members) {
@@ -123,7 +125,7 @@ public void remove(Collection<Address> 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 <code>Clear</code> 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 <code>Clear</code> 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<Address> v) {
clear();
if(v != null) {
@@ -147,14 +149,14 @@ public void set(Collection<Address> 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 <code>Clear</code> 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
+ * <code>clear</code> 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<Address> new_mems, Collection<Address> 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);
View
87 src/org/jgroups/MembershipListener.java
@@ -1,59 +1,62 @@
package org.jgroups;
-
-
/**
* Allows a listener to be notified when group membership changes.
* <p>
- * 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.
- * <b>No long running actions, sending of messages or anything that could block should be done in this callback.</b>
- * If some long running action needs to be performed, it should be done in a separate thread.<p/>
- * 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.
+ * <p/>
+ * 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 <em>after</em> 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.
- *
- * <p>
- * 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 <em>after</em> 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.
+ *
+ * <p>
+ * 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();
}
View
68 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<View> 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<Address> members, List<View> 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<Address> members, List<View> subgroups) {
super(creator, id, members);
this.subgroups=subgroups;
@@ -60,12 +67,11 @@ public MergeView(Address creator, long id, List<Address> members, List<View> sub
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<Address> members2=members != null ? new ArrayList<Address>(members) : null;
View
320 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.
* <p>
* 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 constructor
- * @param dest Address of receiver. If it is <em>null</em> then the message sent to the group.
- * Otherwise, it contains a single destination and is sent to that member.<p>
- */
+ /**
+ * Constructs a Message given a destination Address
+ *
+ * @param dest
+ * Address of receiver. If it is <em>null</em> then the message sent to the group.
+ * Otherwise, it contains a single destination and is sent to that member.
+ * <p>
+ */
public Message(Address dest) {
setDest(dest);
headers=createHeaders(3);
}
- /** Public constructor
- * @param dest Address of receiver. If it is <em>null</em> then the message sent to the group.
- * Otherwise, it contains a single destination and is sent to that member.<p>
- * @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 <em>null</em> then the message sent to the group.
+ * Otherwise, it contains a single destination and is sent to that member.
+ * <p>
+ * @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 <em>reference</em> 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.<br/>
- * <em>
- * 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 !
- * </em>
- * @param dest Address of receiver. If it is <em>null</em> then the message sent to the group.
- * Otherwise, it contains a single destination and is sent to that member.<p>
- * @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 <tt>buf</tt>. 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 <em>reference</em> 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.<br/>
+ * <em>
+ * 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 !
+ * </em>
+ *
+ * @param dest
+ * Address of receiver. If it is <em>null</em> then the message sent to the group.
+ * Otherwise, it contains a single destination and is sent to that member.
+ * <p>
+ * @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 <tt>buf</tt>. 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 <em>null</em> then the message sent to the group.
- * Otherwise, it contains a single destination and is sent to that member.<p>
- * @param src Address of sender
- * @param obj The object will be marshalled into the byte buffer. <em>Obj has to be serializable (e.g. implementing
- * Serializable, Externalizable or Streamable, or be a basic type (e.g. Integer, Short etc)).</em>!
- * 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().<p/>
- */
+ /**
+ * Constructs a Message given a destination Address, a source Address and the payload Object
+ *
+ * @param dest
+ * Address of receiver. If it is <em>null</em> then the message sent to the group.
+ * Otherwise, it contains a single destination and is sent to that member.
+ * <p>
+ * @param src
+ * Address of sender
+ * @param obj
+ * The object will be marshalled into the byte buffer.
+ * <em>Obj has to be serializable (e.g. implementing
+ * Serializable, Externalizable or Streamable, or be a basic type (e.g. Integer, Short etc)).</em>
+ * ! 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().
+ * <p/>
+ */
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 <em>reference</em> 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.<br/>
- * Even if offset and length are used: we return the <em>entire</em> buffer, not a subset.
- */
+ /**
+ * Returns a <em>reference</em> 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.<br/>
+ * Even if offset and length are used: we return the <em>entire</em> 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) {
}
}
- /**
- <em>
- * 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 !
- * </em>
- */
+ /**
+ * <em>
+ * 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 !
+ * </em>
+ */
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 <em>immutable</em>. Any attempt to
- * modify the returned map will cause a runtime exception */
+ /**
+ * Returns a reference to the headers hashmap, which is <em>immutable</em>. Any attempt to modify
+ * the returned map will cause a runtime exception
+ */
public Map<Short,Header> 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 <tt>null</tt> if there was no mapping for the key.
- * (A <tt>null</tt> return can also indicate that the map previously associated <tt>null</tt> 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 <tt>null</tt> if there was no
+ * mapping for the key. (A <tt>null</tt> return can also indicate that the map previously
+ * associated <tt>null</tt> 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
View
67 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.
+ * <p>
+ * 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;
}
View
5 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 {
View
3  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 {
View
28 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() {
}
}
View
9 src/org/jgroups/StateTransferException.java
@@ -1,13 +1,12 @@
package org.jgroups;
-
/**
- * <code>StateTransferException</code> is thrown to indicate failure of
- * state transfer between cluster members.
+ * <code>StateTransferException</code> is thrown to indicate a failure of a state transfer between
+ * cluster members.
* <p>
*
- * @author Vladimir Blagojevic
- * @since 2.6
+ * @author Vladimir Blagojevic
+ * @since 2.6
*
*/
public class StateTransferException extends Exception {
View
3  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;
View
3  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 {
View
19 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.
+ * <p>
+ * 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);
}
View
46 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<Address> {
- /* 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<Address> 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<Address> 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 Address getCreator() {
}
/**
- * 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() {
View
5 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.
- * <br/>
+/**
+ * Logical address which is unique over space and time. <br/>
* 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<Address> {
Please sign in to comment.
Something went wrong with that request. Please try again.