netconnection.java

Vyger offers a D & D and Rogue-like environment in a graphical online roleplay game.

/*
 * Light And Shadow. A Persistent Universe based on Robert Jordan's Wheel of Time Books.
 * Copyright (C) 2001-2002 WOTLAS Team
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
 
package wotlas.libs.net;

import wotlas.utils.Debug;
import wotlas.libs.net.message.*;

import java.io.IOException;
import java.net.Socket;

/** 
 * A NetConnection brings together a NetSender and NetReceiver to send and receive
 * messages. This class is abstract because there are many different types of
 * NetSender and NetReceiver. You have to create your own ones by redefining
 * the init() method. Default personalities are provided in the
 * wotlas.libs.net.connection package.
 *<br>
 * Useful methods you can invoke to send messages :
 *<br>
 *    - queueMessage( message );
 *      To queue a message you want to send. 
 *      Works with every connection type ( but with different behaviour ).
 *<br>
 *    - sendAllMessages();
 *      Asks the NetSender to send all his queued messages now. It's typically the method
 *      you use in case of a USER_AGGREGATION NetSender.
 *
 *<br><p>
 * Useful methods you can invoke to receive messages :
 *<br>
 *    - receiveAllMessages();
 *      Asks the NetReceiver to process all received messages now. This method
 *      does nothing if the NetReceiver is in the asynchronous mode. In the
 *      asynchronous mode you have no method to call : everything is automated.
 *<br>
 *    - waitForMessage();
 *      Waits for a message to arrive. Useful in some cases when the NetReceiver
 *      is synchronous. This method does nothing if the NetReceiver is asynchronous.
 *</p>
 * @author Aldiss
 * @see wotlas.libs.net.NetSender
 * @see wotlas.libs.net.NetReceiver
 */

public abstract class NetConnection {

 /*------------------------------------------------------------------------------------*/

   /** Our NetSender
    */
      protected NetSender myNetsender;

   /** Our NetReceiver
    */
      protected NetReceiver myNetreceiver;

   /** Our connection listeners (objects that will be told when the connection is created or closed).
    */
      private NetConnectionListener listeners[];

   /** An eventual PingThread ( internal class )
    */
      private PingThread pingThread;

   /** A lock for the pingThread
    */
      private Object pingLock;

 /*------------------------------------------------------------------------------------*/

  /** Constructor with an already opened socket.
   *
   * @param socket an already opened socket
   * @exception IOException if the socket wasn't already connected.
   */
     public NetConnection( Socket socket ) throws IOException {
           this( socket, null );
     }

 /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -*/

  /** Constructor with an already opened socket and a session context to use.
   *
   * @param socket an already opened socket
   * @param sessionContext object to give to messages when they arrive.
   * @exception IOException if the socket wasn't already connected.
   */
     public NetConnection( Socket socket, Object sessionContext ) throws IOException {
           init( socket, sessionContext );
           listeners = new NetConnectionListener[0]; // no listeners for now
     }

 /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -*/

  /** In this method you have to create your own NetSender and NetReceiver and
   *  save them in the "myNetsender" and "my_net_receiver" class attributes.
   *  If you want to create a new Connection model you can take the classes
   *  in wotlas.libs.net.connection as examples.
   *
   * @param socket an already opened socket
   * @param sessionContext an object to give to messages as they arrive.
   * @exception IOException if the socket wasn't already connected.
   */
     protected abstract void init( Socket socket, Object sessionContext )
     throws IOException;

 /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -*/

  /** Starts this connection. When you create a new connection you can just
   * send messages but not receives ones. By calling this start() method you
   * launch your NetReceiver and thus can process incoming messages.
   */
     public void start() {
          myNetreceiver.start();
     }

 /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -*/

  /** To set the current sessionContext. It can be any wanted object and it will be given
   *  to NetMessageBehaviour in their doBehaviour() method.
   *
   * @param sessionContext the new sessionContext.
   */
     public void setContext( Object sessionContext ) {
         myNetreceiver.setContext( sessionContext );
     }

 /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -*/

   /** Are we still connected ?
    * @return true if we are, false otherwise.
    */
     public boolean isConnected() {
     	  if( myNetsender==null ||  myNetreceiver==null )
     	      return false;
     	  return true;
     }

 /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -*/

  /** To get the NetSender.
   *
   * @return the connection's NetSender
   */
     public NetSender getNetSender() {
         return myNetsender;
     }

 /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -*/

  /** To get the NetReceiver.
   *
   * @return the connection's NetReceiver
   */
     public NetReceiver getNetReceiver() {
         return myNetreceiver;
     }

 /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -*/

  /** To add a NetConnectionListener on this connection.
   *  The listener will receive information on the life on this connection : when it's
   *  created and when it's closed.
   *
   *  If this NetConnection is still alive we automatically call connectionCreated() on
   *  the new listener.
   *
   * @param listener an object implementing the NetConnectionListener interface.
   */
     public void addConnectionListener( NetConnectionListener listener ) {

         NetConnectionListener tmp[] = new NetConnectionListener[listeners.length+1];

         for( int i=0; i<listeners.length; i++ )
              tmp[i] = listeners[i];

         tmp[tmp.length-1]= listener;
         listeners = tmp;

       // We warn the listener that this connection has been created
         if( myNetsender!=null && myNetreceiver!=null )
             listener.connectionCreated( this );
     }

 /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -*/

  /** To remove the specified network listener. We don't call any method on the listener.
   * @param listener listener to remove.
   * @return true if the listener was removed, false if it was nor found
   */
     public boolean removeConnectionListener( NetConnectionListener listener ) {

       // does the listener exists ?
          boolean found = false;

          for( int i=0; i<listeners.length; i++ )
               if( listeners[i]==listener ) {
                   found = true;
                   break;
               }

          if( !found )
             return false;  // not found

       // We remove the connection listener
          NetConnectionListener tmp[] = new NetConnectionListener[listeners.length-1];
          int nb=0;

          for( int i=0; i<listeners.length; i++ )
               if( listeners[i]!=listener ) {
                   tmp[nb]=listeners[i];
                   nb++;
               }

          listeners = tmp;
          return true;
     }

 /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -*/

  /** Asks the NetSender to send all his queued messages now. It's typically the method
   *  you use in case of a USER_AGGREGATION NetSender when the messages are not sent
   *  automatically, waiting for you to call this method to send them.
   *  If the NetSender is not in the USER_AGGREGATION it will still try to send currently
   *  queued messages (asynchronous, we just fire a "send!" signal).
   */
     public void sendAllMessages() {
           myNetsender.sendAllMessages();
     }

 /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -*/

  /** Asks the NetReceiver to process all received messages now. This method
   *  does nothing if the NetReceiver is in the asynchronous mode. If in synchronous mode
   *  messages are queued when they arrive and wait for this method call to be processed.
   */
     public void receiveAllMessages() {
           myNetreceiver.receiveAllMessages();
     }