src/uk/ac/ntu/n0521366/wsyd/libs/net/NetworkServerAbstract.java

   1 /*
   2  * The MIT License
   3  *
   4  * Copyright 2015 TJ <hacker@iam.tj>.
   5  *
   6  * Permission is hereby granted, free of charge, to any person obtaining a copy
   7  * of this software and associated documentation files (the "Software"), to deal
   8  * in the Software without restriction, including without limitation the rights
   9  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  10  * copies of the Software, and to permit persons to whom the Software is
  11  * furnished to do so, subject to the following conditions:
  12  *
  13  * The above copyright notice and this permission notice shall be included in
  14  * all copies or substantial portions of the Software.
  15  *
  16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  19  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  21  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  22  * THE SOFTWARE.
  23  */
  24 package uk.ac.ntu.n0521366.wsyd.libs.net;
  25
  26 import java.text.MessageFormat;
  27 import java.net.InetSocketAddress;
  28 import java.net.SocketException;
  29 import java.util.concurrent.ConcurrentLinkedQueue;
  30 import java.util.concurrent.ConcurrentHashMap;
  31 import java.util.ArrayList;
  32 import java.util.List;
  33 import java.util.logging.Logger;
  34 import java.util.logging.Level;
  35 import javax.swing.SwingWorker;
  36
  37 /**
  38  * Abstract dual-use multithreading network server that can be used stand-alone
  39  * or in a Swing GUI application as a background worker thread.
  40  *
  41  * Concrete classes are required to implement the Socket-specific functionality.
  42  *
  43  * The arguments to the Generics superclass SwingWorker<T, V> are:
  44  *
  45  *  < return-TYPE-of doInBackground(), publish(parameter-TYPE) >
  46  *
  47  * Here doInBackground() returns an Integer connection counter and publish() takes
  48  * a NetworkMessage type.
  49  *
  50  * Server sockets block in the operating system kernel waiting
  51  * for connections or incoming packets.
  52  *
  53  * SwingWorker objects avoid using the GUI event dispatcher thread. Without that the
  54  * user interface could be unresponsive for considerable periods whilst server
  55  * sockets wait for incoming connections via the blocking in
  56  * ServerSocket.accept() (TCP) or DatagramSocket.receive() (UDP) method.
  57  *
  58  * This design combines the multithreading support of the java.lang.Runnable
  59  * interface with the javax.swing.SwingWorker inheritance so that this single class
  60  * can be used in non-GUI daemon services and GUI applications, avoiding the need
  61  * to write the same server code in more than one class.
  62  *
  63  * The server registers NetworkMessageEventListener objects and notifies them
  64  * when a new NetworkMessage has been received.
  65  *
  66  * @see javax.swing.SwingWorker
  67  *
  68  * @author TJ <hacker@iam.tj>
  69  */
  70 public abstract class NetworkServerAbstract extends SwingWorker<Integer, NetworkMessage> implements NetworkMessageEventGenerator {
  71
  72     /**
  73      * Single Logger for the class used by all object instances.
  74      *
  75      * Can be instantiated once by objects of any sub-class.
  76      */
  77     @SuppressWarnings("NonConstantLogger")
  78     protected static Logger LOGGER = null;
  79
  80     /**
  81      * Inject simulated received NetworkMessages.
  82      *
  83      * A helpful tool for debugging.
  84      */
  85     protected boolean _simulate = false;
  86
  87     /**
  88      * Count of packets or connections received.
  89      */
  90     int _connectionCount;
  91
  92     /**
  93      * Service name for this server instance.
  94      *
  95      * E.g. "ServerSocial", "ServerChat", "ServerControl", "ClientControl", "ClientChat", "ServerLog"
  96      */
  97     String _title;
  98
  99     /**
 100      * Socket parameters for this server.
 101      */
 102     WSYD_SocketAddress _socketAddress;
 103
 104     /**
 105      * Thread safe First In, First Out Queue of NetworkMessage objects waiting to be sent.
 106      *
 107      * Allows the Owner Thread to submit new messages for sending that the Worker Thread
 108      * can safely access.
 109      */
 110     protected ConcurrentLinkedQueue<NetworkMessage> _sendMessageQueue = new ConcurrentLinkedQueue<>();
 111
 112     protected class LastSeenHost {
 113         long timeInMillis;
 114         InetSocketAddress address;
 115
 116         LastSeenHost(InetSocketAddress address, long timeInMillis) {
 117             this.address = address;
 118             this.timeInMillis = timeInMillis;
 119         }
 120         LastSeenHost(InetSocketAddress host) {
 121             this(host, System.currentTimeMillis());
 122         }
 123
 124     };
 125     /**
 126      * Maps service _title to its parent network host.
 127      * <p>
 128      * Used by methods on the Owner Thread to determine the list of valid service
 129      * names it can submit messages to (by iterating the keys using keySet()).</p>
 130      * <p>
 131      * New service names can be added in two ways:<br/>
 132      * <ol>
 133      *  <li>by the Worker Thread from received messages</li>
 134      *  <li>by the Owner or (other thread) from a service discovery helper (such as multicast discovery)</li>
 135      * </ol>
 136      */
 137     protected ConcurrentHashMap<String, LastSeenHost> _serviceToHostMap = new ConcurrentHashMap<>();;
 138
 139     /**
 140      * Wrapper for filtering NetworkMessageEvents based on the message intent
 141      */
 142     public class NetworkMessageEventListenerWithIntent {
 143         String _intent;
 144         NetworkMessageEventListener _listener;
 145
 146         public NetworkMessageEventListenerWithIntent(NetworkMessageEventListener listener, String intent) {
 147             _intent = intent;
 148             _listener = listener;
 149         }
 150     }
 151     protected ArrayList<NetworkMessageEventListenerWithIntent> _NetworkMessageEventListeners = new ArrayList<>();
 152
 153     /**
 154      *
 155      * @param level message importance
 156      * @param title source identifier
 157      * @param formatter parameter Formatter for log message
 158      * @param parameters variable length list of replaceable parameters for formatter
 159      */
 160     protected static void log(Level level, String title, String formatter, ArrayList<String> parameters) {
 161         if (LOGGER == null)
 162             return;
 163         // formatter = "{" + Integer.toString(parameters.size()) + "}: " + formatter;
 164         // parameters.add(title);
 165         LOGGER.logp(level, title, null, MessageFormat.format(formatter, parameters.toArray()));
 166     }
 167     /**
 168      *
 169      * @param level message importance
 170      * @param title source identifier
 171      * @param message the log entry
 172      */
 173     protected static void log(Level level, String title, String message) {
 174         if (LOGGER == null)
 175             return;
 176         LOGGER.logp(level, title, null, MessageFormat.format("{1}", message));
 177     }
 178
 179     /**
 180      * Set the log level for the server
 181      * @param level a new log level
 182      * @return the old log level
 183      */
 184     public Level setLogLevel(Level level) {
 185         Level result = Level.OFF;
 186         if (LOGGER != null) {
 187             Level temp = LOGGER.getLevel();
 188             LOGGER.setLevel(level);
 189             result = temp;
 190         }
 191         return result;
 192     }
 193
 194     /**
 195      * Default constructor.
 196      */
 197     NetworkServerAbstract() {
 198         this._connectionCount = 0;
 199         this._title = null;
 200         this._socketAddress = null;
 201     }
 202
 203     /**
 204      * Construct the server with a Logger.
 205      *
 206      * No socket is opened.
 207      *
 208      * @param socketAddress The socket to listen on
 209      * @param title source identifier for use in log messages and sent NetworkMessage objects
 210      * @param logger An instance of Logger to be used by all objects of this class
 211      */
 212     public NetworkServerAbstract(WSYD_SocketAddress socketAddress, String title, Logger logger) {
 213         this._connectionCount = 0;
 214         this._title = title;
 215         this._socketAddress = socketAddress;
 216         if (LOGGER == null) // do not replace existing logger reference
 217             LOGGER = logger;
 218     }
 219
 220     /**
 221      * Construct the server without a Logger.
 222      *
 223      * No socket is opened.
 224      *
 225      * @param socketAddress The socket to listen on
 226      * @param title source identifier for use in log messages and sent NetworkMessage objects
 227      */
 228     public NetworkServerAbstract(WSYD_SocketAddress socketAddress, String title) {
 229         this(socketAddress, title, null);
 230     }
 231
 232     /**
 233      * Enable or disable simulated received packet injection.
 234      *
 235      * @param simulate true to simulate received messages
 236      */
 237     public void setSimulate(boolean simulate) {
 238         this._simulate = simulate;
 239     }
 240
 241     /**
 242      * Get the simulation state.
 243      *
 244      * @return true if simulation is enabled.
 245      */
 246     public boolean getSimulate() {
 247         return this._simulate;
 248     }
 249
 250
 251     /* XXX: The following Methods execute on the background Worker Thread */
 252
 253     /**
 254      * The primary SwingWorker method, started on the Worker Thread when the Owner
 255      * Thread calls execute().
 256      *
 257      * Loops until isCancelled() == true. Within the loop calls serverListen() to
 258      * allow reception of one packet or connection and if so counts it.
 259      * Then  it checks if there are any messages to be sent out and if so calls
 260      * serverSend().
 261      *
 262      * @return the number of connections accepted
 263      */
 264     @Override
 265     public Integer doInBackground() {
 266         ArrayList<String> logMessages = new ArrayList<>();
 267         try {
 268             logMessages.add(_socketAddress.toString());
 269             log(Level.INFO, _title, "Opening socket {0}", logMessages);
 270             this.serverOpen();
 271         }
 272         catch(SocketException e) {
 273             logMessages.clear();
 274             logMessages.add(_socketAddress.getAddress().toString());
 275             logMessages.add(Integer.toString(_socketAddress.getPort()));
 276             logMessages.add(_socketAddress.getProtocol().toString());
 277             log(Level.SEVERE, _title, "{0}: Unable to open socket on {1}:{2} {3}", logMessages);
 278         }
 279
 280         // unless cancelled keep waiting for new packets or connections
 281         while (!this.isCancelled()) {
 282             if (this.serverListen())
 283                 this._connectionCount++;
 284
 285             // send a queued message
 286             NetworkMessage temp =  this.dequeueMessage();
 287             if (temp != null) {
 288                 if (!this.serverSend(temp)) {
 289                     logMessages.clear();
 290                     logMessages.add(temp.getSender());
 291                     logMessages.add(temp.getTarget());
 292                     log(Level.WARNING, _title, "Unable to send message from {0} to {1}", logMessages);
 293                 }
 294             }
 295         }
 296
 297         try {
 298             logMessages.clear();
 299             logMessages.add(_socketAddress.toString());
 300             log(Level.INFO, _title, "Closing socket {0}", logMessages);
 301             this.serverClose();
 302         }
 303         catch(SocketException e) {
 304             logMessages.clear();
 305             logMessages.add(_socketAddress.getAddress().toString());
 306             logMessages.add(Integer.toString(_socketAddress.getPort()));
 307             logMessages.add(_socketAddress.getProtocol().toString());
 308             log(Level.SEVERE, _title, "{0}: Unable to close socket on {1}:{2} {3}", logMessages);
 309         }
 310
 311         return this._connectionCount;
 312     }
 313
 314
 315     /**
 316      * Open the socket ready for accepting data or connections.
 317      *
 318      * It should also set a reasonable socket timeout with a call to setSoTimeout()
 319      *
 320      * @see java.net.ServerSocket#setSoTimeout
 321      * @see java.net.DatagramSocket#setSoTimeout
 322      * @throws SocketException
 323      */
 324     public abstract void serverOpen() throws SocketException;
 325
 326     /**
 327      * Close the socket.
 328      *
 329      * @throws SocketException
 330      */
 331     public abstract void serverClose() throws SocketException;
 332
 333     /**
 334      * Send an unsolicited message to a remote service.
 335      *
 336      * This method is called by the main worker loop if there is a message to
 337      * be sent.
 338      *
 339      * @param message must have its _serviceTarget parameter set
 340      * @return true if the message was sent
 341      */
 342     protected abstract boolean serverSend(NetworkMessage message);
 343
 344     /**
 345      * Accept packet or connection from remote hosts.
 346      *
 347      * This method must wait for a single incoming connection or packet, process it,
 348      * and then publish() it for consumption by process().
 349      *
 350      * It must add newly seen remote service names to _serviceToHostMap so that
 351      * methods on the Owner Thread can discover the destination service titles
 352      * they can use in new NetworkMessage submissions.
 353      *
 354      * @return true if the server should continue listening
 355      */
 356     public abstract boolean serverListen();
 357
 358     /**
 359      * Removes a message from the queue of pending messages.
 360      *
 361      * This method is called on the Worker Thread by the doInBackground() main loop.
 362      *
 363      * @return a message to be sent
 364      */
 365     protected NetworkMessage dequeueMessage() {
 366         return this._sendMessageQueue.poll();
 367     }
 368
 369     /* XXX: Methods below here all execute on the GUI Event Dispatch Thread */
 370
 371
 372     /**
 373      * Fetch messages received by the server.
 374      *
 375      * For delivery to event listeners; usually Swing GUI components. This method will run on the
 376      * Owner Thread so must complete quickly it that is the GUI Event Dispatch Thread.
 377      *
 378      * @param list messages received and queued
 379      */
 380     @Override
 381     protected void process(List<NetworkMessage> list) {
 382         for (NetworkMessage message: list) {
 383             fireNetworkMessageEvent(message);
 384         }
 385     }
 386
 387     /**
 388      * Clean up after doInBackground() has returned.
 389      *
 390      * This method will run on the GUI Event Dispatch Thread so must complete quickly.
 391      */
 392     @Override
 393     protected abstract void done();
 394
 395
 396     /**
 397      * Ensure service is in the map of known hosts.
 398      * @param service the service name to check
 399      * @return true is the target service is known
 400      */
 401     protected boolean isServiceValid(String service) {
 402         return this._serviceToHostMap.containsKey(service);
 403     }
 404
 405     /**
 406      * Adds a message to the queue of pending messages.
 407      *
 408      * This method will usually be called from the Owner Thread.
 409      *
 410      * @param message to be sent
 411      * @return true if the message was added to the queue
 412      * @throws IllegalArgumentException if the target does not exist in the serviceToHost mapping
 413      */
 414     public boolean queueMessage(NetworkMessage message) throws IllegalArgumentException {
 415         boolean result = false;
 416         if (message != null) {
 417             // ensure the target is set and is a valid service
 418             String target = message.getTarget();
 419             if (target == null)
 420                 throw new IllegalArgumentException("target cannot be null");
 421             if(!isServiceValid(target))
 422                 throw new IllegalArgumentException("target service does not exist: " + target);
 423
 424             NetworkMessage temp;
 425             try { // make a deep clone of the message
 426                 temp = NetworkMessage.clone(message);
 427                 result = this._sendMessageQueue.add(temp);
 428             } catch (CloneNotSupportedException e) {
 429                 // TODO: queueMessage() log CloneNotSupportedException
 430                 e.printStackTrace();
 431             }
 432         }
 433         return result;
 434     }
 435
 436     /**
 437      * Add a NetworkMessageEvent listener.
 438      *
 439      * Listens to all intents.
 440      *
 441      * @param listener
 442      */
 443     @Override
 444     public synchronized void addNetworkMessageEventListener(NetworkMessageEventListener listener) {
 445         _NetworkMessageEventListeners.add(new NetworkMessageEventListenerWithIntent(listener, null));
 446     }
 447
 448     /**
 449      * Add a filtered NetworkMessageEvent listener.
 450      *
 451      * Filters on the intent of the NetworkMessage.
 452      * @param listener
 453      * @param intent null to listen to all intents, otherwise the intent to listen for
 454      */
 455     @Override
 456     public synchronized void addNetworkMessageEventListener(NetworkMessageEventListener listener, String intent) {
 457         _NetworkMessageEventListeners.add(new NetworkMessageEventListenerWithIntent(listener, intent));
 458     }
 459
 460     /**
 461      * Remove a NetworkMessageEvent listener.
 462      *
 463      * @param listener
 464      */
 465     @Override
 466     public synchronized void removeNetworkMessageEventListener(NetworkMessageEventListener listener) {
 467         for (NetworkMessageEventListenerWithIntent intentListener : _NetworkMessageEventListeners)
 468             if (intentListener._listener == listener)
 469                 _NetworkMessageEventListeners.remove(intentListener);
 470     }
 471
 472     /**
 473      * Send a NetworkMessageEvent to all listeners.
 474      *
 475      * Only sends the message to listeners registered for the same intent, or for all messages.
 476      *
 477      * @param message the NetworkMessage to send
 478      */
 479     private synchronized void fireNetworkMessageEvent(NetworkMessage message) {
 480         NetworkMessageEvent event = new NetworkMessageEvent(this, message);
 481         for (NetworkMessageEventListenerWithIntent intentListener : _NetworkMessageEventListeners) {
 482             if (intentListener._intent.equals(message._intent) || intentListener._intent == null)
 483                 intentListener._listener.NetworkMessageReceived(event);
 484         }
 485     }
 486 }