[hornetq-commits] JBoss hornetq SVN: r8672 - in trunk/src/main/org/hornetq/core/remoting: impl and 1 other directory.
do-not-reply at jboss.org
do-not-reply at jboss.org
Fri Dec 11 06:02:23 EST 2009
Author: ataylor
Date: 2009-12-11 06:02:23 -0500 (Fri, 11 Dec 2009)
New Revision: 8672
Modified:
trunk/src/main/org/hornetq/core/remoting/Channel.java
trunk/src/main/org/hornetq/core/remoting/ChannelHandler.java
trunk/src/main/org/hornetq/core/remoting/CloseListener.java
trunk/src/main/org/hornetq/core/remoting/CommandConfirmationHandler.java
trunk/src/main/org/hornetq/core/remoting/FailureListener.java
trunk/src/main/org/hornetq/core/remoting/Interceptor.java
trunk/src/main/org/hornetq/core/remoting/Packet.java
trunk/src/main/org/hornetq/core/remoting/RemotingConnection.java
trunk/src/main/org/hornetq/core/remoting/impl/ChannelImpl.java
Log:
remoting javadocs
Modified: trunk/src/main/org/hornetq/core/remoting/Channel.java
===================================================================
--- trunk/src/main/org/hornetq/core/remoting/Channel.java 2009-12-11 10:08:41 UTC (rev 8671)
+++ trunk/src/main/org/hornetq/core/remoting/Channel.java 2009-12-11 11:02:23 UTC (rev 8672)
@@ -17,53 +17,165 @@
import org.hornetq.core.exception.HornetQException;
/**
- * A Channel A Channel *does not* support concurrent access by more than one thread!
- *
+ * A channel is a way of interleaving data meant for different endpoints over the same {@link org.hornetq.core.remoting.RemotingConnection}.
+ * <p/>
+ * Any packet sent will have its channel id set to the specific channel sending so it can be routed to its correct channel
+ * when received by the {@link org.hornetq.core.remoting.RemotingConnection}. see {@link org.hornetq.core.remoting.Packet#setChannelID(long)}.
+ * <p/>
+ * Each Channel should will forward any packets received to its {@link org.hornetq.core.remoting.ChannelHandler}.
+ * <p/>
+ * A Channel *does not* support concurrent access by more than one thread!
+ *
* @author <a href="mailto:tim.fox at jboss.com">Tim Fox</a>
*/
public interface Channel
{
+ /**
+ * returns the id of this channel.
+ *
+ * @return the id
+ */
long getID();
+ /**
+ * sends a packet on this channel.
+ *
+ * @param packet the packet to send
+ */
void send(Packet packet);
+ /**
+ * sends a packet on this channel and then blocks until it has been written to the connection.
+ *
+ * @param packet the packet to send
+ */
void sendAndFlush(Packet packet);
+ /**
+ * sends a packet on this channel and then blocks until a response is received or a timeout occurs.
+ *
+ * @param packet the packet to send
+ * @return the response
+ * @throws HornetQException if an error occurs during the send
+ */
Packet sendBlocking(Packet packet) throws HornetQException;
+ /**
+ * sets the {@link org.hornetq.core.remoting.ChannelHandler} that this channel should forward received packets to.
+ *
+ * @param handler the handler
+ */
void setHandler(ChannelHandler handler);
- ChannelHandler getHandler();
-
+ /**
+ * closes this channel.
+ * <p/>
+ * once closed no packets can be sent.
+ */
void close();
+ /**
+ * transfers the connection used by this channel to the one specified.
+ * <p/>
+ * All new packets will be sent via this connection.
+ *
+ * @param newConnection the new connection
+ */
void transferConnection(RemotingConnection newConnection);
+ /**
+ * resends any packets that have not received confirmations yet.
+ * <p/>
+ * Typically called after a connection has been transferred.
+ *
+ * @param lastConfirmedCommandID the last confirmed packet
+ * @param newID the new id to use
+ */
void replayCommands(int lastConfirmedCommandID, final long newID);
+ /**
+ * returns the last confirmed packet command id
+ *
+ * @return the id
+ */
int getLastConfirmedCommandID();
+ /**
+ * locks the channel.
+ * <p/>
+ * While locked no packets can be sent or received
+ */
void lock();
+ /**
+ * unlocks the channel.
+ */
void unlock();
+ /**
+ * forces any {@link org.hornetq.core.remoting.Channel#sendBlocking(Packet)} request to return with an exception.
+ */
void returnBlocking();
+ /**
+ * returns the channel lock
+ *
+ * @return the lock
+ */
Lock getLock();
+ /**
+ * returns the Remoting Connection being used by the channel
+ *
+ * @return
+ */
RemotingConnection getConnection();
+ /**
+ * sends a confirmation of a packet being received.
+ *
+ * @param packet the packet to confirm
+ */
void confirm(Packet packet);
+ /**
+ * sets the handler to use when a confirmation is received.
+ *
+ * @param handler the handler to call
+ */
void setCommandConfirmationHandler(CommandConfirmationHandler handler);
+ /**
+ * flushes any confirmations on to the connection.
+ */
void flushConfirmations();
+ /**
+ * Called by {@link org.hornetq.core.remoting.RemotingConnection} when a packet is received.
+ * <p/>
+ * This method should then call its {@link org.hornetq.core.remoting.ChannelHandler} after appropriate processing of
+ * the packet
+ *
+ * @param packet the packet to process.
+ */
void handlePacket(Packet packet);
+ /**
+ * clears any commands from the cache that are yet to be confirmed.
+ */
void clearCommands();
+ /**
+ * returns the confirmation window size this channel is using.
+ *
+ * @return the window size
+ */
int getConfirmationWindowSize();
-
+
+ /**
+ * notifies the channel if it is transferring its connection. When true it is illegal to send messages.
+ *
+ * @param transferring whether the channel is transferring
+ */
void setTransferring(boolean transferring);
}
Modified: trunk/src/main/org/hornetq/core/remoting/ChannelHandler.java
===================================================================
--- trunk/src/main/org/hornetq/core/remoting/ChannelHandler.java 2009-12-11 10:08:41 UTC (rev 8671)
+++ trunk/src/main/org/hornetq/core/remoting/ChannelHandler.java 2009-12-11 11:02:23 UTC (rev 8672)
@@ -13,12 +13,17 @@
package org.hornetq.core.remoting;
/**
- * A ChannelHandler
- *
+ * A ChannelHandler is used by {@link Channel}. When a channel receives a packet it will call its handler to deal with the
+ * packet.
+ *
* @author <a href="mailto:tim.fox at jboss.com">Tim Fox</a>
- *
*/
public interface ChannelHandler
{
+ /**
+ * called by the channel when a packet is received..
+ *
+ * @param packet the packet received
+ */
void handlePacket(Packet packet);
}
Modified: trunk/src/main/org/hornetq/core/remoting/CloseListener.java
===================================================================
--- trunk/src/main/org/hornetq/core/remoting/CloseListener.java 2009-12-11 10:08:41 UTC (rev 8671)
+++ trunk/src/main/org/hornetq/core/remoting/CloseListener.java 2009-12-11 11:02:23 UTC (rev 8672)
@@ -13,9 +13,16 @@
package org.hornetq.core.remoting;
/**
+ * CloseListeners can be registered with a {@link org.hornetq.core.remoting.RemotingConnection} to get notified when the connection is closed.
+ * <p/>
+ * {@link org.hornetq.core.remoting.RemotingConnection#addCloseListener(CloseListener)}
+ *
* @author <a href="mailto:andy.taylor at jboss.org">Andy Taylor</a>
*/
public interface CloseListener
{
+ /**
+ * called when the connection is closed
+ */
void connectionClosed();
}
Modified: trunk/src/main/org/hornetq/core/remoting/CommandConfirmationHandler.java
===================================================================
--- trunk/src/main/org/hornetq/core/remoting/CommandConfirmationHandler.java 2009-12-11 10:08:41 UTC (rev 8671)
+++ trunk/src/main/org/hornetq/core/remoting/CommandConfirmationHandler.java 2009-12-11 11:02:23 UTC (rev 8672)
@@ -14,15 +14,18 @@
package org.hornetq.core.remoting;
/**
- * A CommandConfirmationHandler
+ * A CommandConfirmationHandler is used by the channel to confirm confirmations of packets.
*
* @author <a href="mailto:tim.fox at jboss.com">Tim Fox</a>
- *
- * Created 9 Feb 2009 12:39:11
- *
- *
+ * <p/>
+ * Created 9 Feb 2009 12:39:11
*/
public interface CommandConfirmationHandler
{
+ /**
+ * called by channel after a confirmation has been received.
+ *
+ * @param packet the packet confirmed
+ */
void commandConfirmed(Packet packet);
}
Modified: trunk/src/main/org/hornetq/core/remoting/FailureListener.java
===================================================================
--- trunk/src/main/org/hornetq/core/remoting/FailureListener.java 2009-12-11 10:08:41 UTC (rev 8671)
+++ trunk/src/main/org/hornetq/core/remoting/FailureListener.java 2009-12-11 11:02:23 UTC (rev 8672)
@@ -16,18 +16,16 @@
import org.hornetq.core.exception.HornetQException;
/**
- *
- * A FailureListener notifies the user when a connection failure occured.
- *
+ * A FailureListener notifies the user when a connection failure occurred.
+ *
* @author <a href="mailto:tim.fox at jboss.com">Tim Fox</a>
* @author <a href="mailto:jmesnil at redhat.com">Jeff Mesnil</a>
- *
*/
public interface FailureListener
{
/**
* Notifies that a connection has failed due to the specified exception.
- *
+ *
* @param exception exception which has caused the connection to fail
*/
void connectionFailed(HornetQException exception);
Modified: trunk/src/main/org/hornetq/core/remoting/Interceptor.java
===================================================================
--- trunk/src/main/org/hornetq/core/remoting/Interceptor.java 2009-12-11 10:08:41 UTC (rev 8671)
+++ trunk/src/main/org/hornetq/core/remoting/Interceptor.java 2009-12-11 11:02:23 UTC (rev 8672)
@@ -16,20 +16,20 @@
import org.hornetq.core.exception.HornetQException;
/**
- *
* This is class is a simple way to intercepting server calls on HornetQ.
- *
+ * <p/>
* To Add this interceptor, you have to modify hornetq-configuration.xml
- *
+ *
* @author clebert.suconic at jboss.com
* @author <a href="mailto:tim.fox at jboss.com">Tim Fox</a>
*/
public interface Interceptor
{
/**
- *
- * @param packet
- * @param connection
+ * gets called when a packet is received prior to be sent to the channel
+ *
+ * @param packet the packet being received
+ * @param connection the connection the packet was received on
* @return true to process the next interceptor and handle the packet,
* false to abort processing of the packet
* @throws HornetQException
Modified: trunk/src/main/org/hornetq/core/remoting/Packet.java
===================================================================
--- trunk/src/main/org/hornetq/core/remoting/Packet.java 2009-12-11 10:08:41 UTC (rev 8671)
+++ trunk/src/main/org/hornetq/core/remoting/Packet.java 2009-12-11 11:02:23 UTC (rev 8672)
@@ -16,31 +16,68 @@
import org.hornetq.core.buffers.HornetQBuffer;
/**
- *
- * A Packet
- *
+ * A Packet represents a pcaket of data transmitted over a connection.
+ *
* @author <a href="mailto:tim.fox at jboss.com">Tim Fox</a>
- *
*/
public interface Packet
{
+ /**
+ * This sets the channel id that should be used once the packet has been successfully decoded it is sent to the correct channel.
+ *
+ * @param channelID the id of the channel to handle the packet
+ */
void setChannelID(long channelID);
+ /**
+ * returns the channel id of the channel that should handle this pcaket
+ *
+ * @return the id of the channel
+ */
long getChannelID();
+ /**
+ * returns true if this packet is being sent in response to a previously received packet
+ *
+ * @return true if a response
+ */
boolean isResponse();
+ /**
+ * returns the type of the packet.
+ * <p/>
+ * This is needed when decoding the packet
+ *
+ * @return the packet type
+ */
byte getType();
+ /**
+ * Encodes the packet and returns a {@link org.hornetq.core.buffers.HornetQBuffer} containing the data
+ *
+ * @param connection the connection
+ * @return the buffer to encode to
+ */
HornetQBuffer encode(RemotingConnection connection);
+ /**
+ * decodes the buffer into this packet
+ *
+ * @param buffer the buffer to decode from
+ */
void decode(HornetQBuffer buffer);
/**
- *
+ * returns the size needed to encode this packet.
+ *
* @return The size of the entire packet including headers, and extra data
*/
int getPacketSize();
+ /**
+ * returns true if a confirmation should be sent on receipt of this packet.
+ *
+ * @return true if confirmation is required
+ */
boolean isRequiresConfirmations();
}
Modified: trunk/src/main/org/hornetq/core/remoting/RemotingConnection.java
===================================================================
--- trunk/src/main/org/hornetq/core/remoting/RemotingConnection.java 2009-12-11 10:08:41 UTC (rev 8671)
+++ trunk/src/main/org/hornetq/core/remoting/RemotingConnection.java 2009-12-11 11:02:23 UTC (rev 8672)
@@ -21,60 +21,197 @@
import org.hornetq.core.remoting.spi.Connection;
/**
- * A RemotingConnection
- *
+ * A RemotingConnection is a connection between a client and a server.
+ * <p/>
+ * It allows multiple {@link org.hornetq.core.remoting.Channel}'s to be created and data multiplexed over them. It uses
+ * and a {@link Connection} implementation and takes care of failures etc.
+ *
* @author <a href="mailto:tim.fox at jboss.com">Tim Fox</a>
* @author <a href="mailto:jmesnil at redhat.com">Jeff Mesnil</a>
*/
public interface RemotingConnection extends BufferHandler
{
+ /**
+ * returns the unique id of the Remoting Connection
+ *
+ * @return the id
+ */
Object getID();
+ /**
+ * returns a string representation of the remote address of this connection
+ *
+ * @return the remote address
+ */
String getRemoteAddress();
+ /**
+ * return the channel with the channel id specified.
+ * <p/>
+ * If it does not exist create it with the confirmation window size.
+ *
+ * @param channelID the channel id
+ * @param confWindowSize the confirmation window size
+ * @return the channel
+ */
Channel getChannel(long channelID, int confWindowSize);
+ /**
+ * add the channel with the specified channel id
+ *
+ * @param channelID the channel id
+ * @param channel the channel
+ */
void putChannel(long channelID, Channel channel);
+ /**
+ * remove the channel with the specified channel id
+ *
+ * @param channelID the channel id
+ * @return true if removed
+ */
boolean removeChannel(long channelID);
+ /**
+ * generate a unique (within this connection) channel id
+ *
+ * @return the id
+ */
long generateChannelID();
+ /**
+ * add a failure listener.
+ * <p/>
+ * The listener will be called in the event of connection failure.
+ *
+ * @param listener the listener
+ */
void addFailureListener(FailureListener listener);
+ /**
+ * remove the failure listener
+ *
+ * @param listener the lister to remove
+ * @return true if removed
+ */
boolean removeFailureListener(FailureListener listener);
+ /**
+ * add a CloseListener.
+ * <p/>
+ * This will be called in the event of the connection being closed.
+ *
+ * @param listener the listener to add
+ */
void addCloseListener(CloseListener listener);
+ /**
+ * remove a Close Listener
+ *
+ * @param listener the listener to remove
+ * @return true if removed
+ */
boolean removeCloseListener(CloseListener listener);
+ /**
+ * return all the failure listeners
+ *
+ * @return the listeners
+ */
List<FailureListener> getFailureListeners();
+ /**
+ * set the failure listeners.
+ * <p/>
+ * These will be called in the event of the connection being closed. Any previosuly added listeners will be removed.
+ *
+ * @param listeners the listeners to add.
+ */
void setFailureListeners(List<FailureListener> listeners);
+ /**
+ * creates a new HornetQBuffer of the specified size.
+ *
+ * @param size the size of buffer required
+ * @return the buffer
+ */
HornetQBuffer createBuffer(int size);
+ /**
+ * called when the underlying connection fails.
+ *
+ * @param me the exception that caused the failure
+ */
void fail(HornetQException me);
+ /**
+ * destroys this connection.
+ */
void destroy();
+ /**
+ * resets the id generator used to when generating id's
+ *
+ * @param id the first id to set it to
+ */
void syncIDGeneratorSequence(long id);
+ /**
+ * return the next id that will be chosen.
+ *
+ * @return the id
+ */
long getIDGeneratorSequence();
+ /**
+ * return the underlying Connection.
+ *
+ * @return the connection
+ */
Connection getTransportConnection();
+ /**
+ * returns whether or not the Remoting Connection is a client
+ *
+ * @return true if client, false if a server
+ */
boolean isClient();
+ /**
+ * returns true if this Remoting Connection has been destroyed.
+ *
+ * @return true if destroyed, otherwise false
+ */
boolean isDestroyed();
+ /**
+ * return the current tomeout for blocking calls
+ *
+ * @return the timeout in milliseconds
+ */
long getBlockingCallTimeout();
+ /**
+ * return the transfer lock used when transferring connections.
+ *
+ * @return the lock
+ */
Object getTransferLock();
+ /**
+ * returns true if any data has been received since the last time this method was called.
+ *
+ * @return true if data has been received.
+ */
boolean checkDataReceived();
+ /**
+ * remove all channels from the remoting connection
+ */
void removeAllChannels();
-
+
+ /**
+ * flush all outstanding confirmations onto the connection.
+ */
void flushConfirmations();
}
Modified: trunk/src/main/org/hornetq/core/remoting/impl/ChannelImpl.java
===================================================================
--- trunk/src/main/org/hornetq/core/remoting/impl/ChannelImpl.java 2009-12-11 10:08:41 UTC (rev 8671)
+++ trunk/src/main/org/hornetq/core/remoting/impl/ChannelImpl.java 2009-12-11 11:02:23 UTC (rev 8672)
@@ -301,11 +301,6 @@
this.handler = handler;
}
- public ChannelHandler getHandler()
- {
- return handler;
- }
-
public void close()
{
if (closed)
More information about the hornetq-commits
mailing list