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@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@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@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@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@jboss.com">Tim Fox</a> * @author <a href="mailto:jmesnil@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(a)jboss.com * @author <a href="mailto:tim.fox@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@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@jboss.com">Tim Fox</a> * @author <a href="mailto:jmesnil@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)