Class ClientFactory

java.lang.Object
edu.uky.cs.nil.tt.ClientFactory
All Implemented Interfaces:
AutoCloseable, Callable<Void>
public abstract class ClientFactory extends Object implements Callable<Void>, AutoCloseable
A client factory creates continuously creates clients to connect to a server and is useful for deploying automated agents.

A factory starts by creating one client to join the server's queue of waiting players. When that client finds a partner and starts its session, the factory creates a new client to take its place in the queue.

You can limit the maximum number of clients this factory will run simultaneously.

If any client created by this factory throws an uncaught exception, this factory will shut down gracefully and throw that exception after shutting down.

This class provides several methods that are all called from the same thread at important moments in the factory's lifecycle. These methods can be overridden to, for example, log important information. See the call() method for a full description of these methods and when they are called.

Author:
Stephen G. Ware

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    final int
    maxClients
    The maximum number of clients that this factory will create to run simultaneously

  • Constructor Summary

    Constructors
    Constructor
    Description
    ClientFactory()
    Creates a new client factory with no upper limit on the number of clients that may run simultaneously.
    ClientFactory(int maxClients)
    Creates a new client factory with an upper limit on the number of clients that it will create simultaneously.

  • Method Summary

    Modifier and Type
    Method
    Description
    Void
    call()
    void
    close()
    protected abstract Client
    create()
    This method creates and returns a new client of the type produced by this factory.
    protected void
    onClose()
    This method is called once after this factory stops creating new clients and has begun shutting down.
    protected void
    onStart()
    This method is called once when this factory begins running.
    protected void
    onStop()
    This method is called once at the end of this factory's shutdown process after all clients have stopped running.
    String
    toString()
     

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Field Details

    • maxClients

      public final int maxClients
      The maximum number of clients that this factory will create to run simultaneously

  • Constructor Details

    • ClientFactory

      public ClientFactory(int maxClients)
      Creates a new client factory with an upper limit on the number of clients that it will create simultaneously.
      Parameters:
      maxClients - the maximum number of clients that may be running simultaneously, or 0 if there is no limit

    • ClientFactory

      public ClientFactory()
      Creates a new client factory with no upper limit on the number of clients that may run simultaneously.

  • Method Details

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • call

      public Void call() throws Exception

      This method starts the client factory, creates the first client, periodically creates new clients as needed, and shuts down gracefully if the factory is closed or if a client throw an uncaught exception.

      As this method runs, it calls other methods to notify the factory of important events. Some of these methods are guaranteed to be called even if an exception is thrown. The list of those methods and when they happen is as follows:

      • The onStart() method is called first. If this method throws an exception it is thrown immediately, and no other methods are called.
      • The first client is created and runs on a new virtual thread.
      • Each time a client starts its session, a new client will be created to take its place in the server's queue of waiting clients. If creating a new client would exceed this factory's limit on the number of clients which can run simultaneously, this factory will wait until a running client has completed its session to start the next client.
      • If one of the clients created by this factory throws an exception, or if the close() method is called, the onClose() method will run on the thread which called this method, regardless of which thread called close(). If the thread which called this method is interrupted, onClose() will not be called.
      • Any clients whose sessions have not yet begun will be closed. Clients whose sessions have begun will not be closed. If this factory stopped because of an exception or because the close() method was called, it will wait for all clients whose sessions have started to finish. If this factory stopped because the thread which called this method was interrupted, it will not wait for running clients to finish their sessions.
      • After all running clients have finished their sessions, onStop() is called. If this factory stopped because the thread which called this method was interrupted, that method will not be called.
      • If a client threw an exception, that exception will be thrown from this method. If no exception was thrown, this method returns null.
      Specified by:
      call in interface Callable<Void>
      Throws:
      Exception

    • close

      public void close()

      Causes the factory to shut down gracefully, closing any waiting clients and waiting for any running clients to finish. This method can be called safely from any thread. It will cause the thread which called call() to stop creating new clients, to call the onClose() method, to close all clients whose sessions have not started, to wait for all clients whose sessions have started to end, and finally to stop.

      Specified by:
      close in interface AutoCloseable

    • onStart

      protected void onStart() throws Exception
      This method is called once when this factory begins running.

      By default, this method does nothing. It can be overridden if the factory wants to do something when the factory first begins running.

      Throws:
      Exception - if a problem occurred during this method

    • create

      protected abstract Client create() throws Exception
      This method creates and returns a new client of the type produced by this factory. The factory will always call this method from the thread which called call().
      Returns:
      a new instance of the client this factory produces
      Throws:
      Exception - if a problem occurred while creating the client

    • onClose

      protected void onClose() throws Exception
      This method is called once after this factory stops creating new clients and has begun shutting down. This method is called either because this factory was closed or because a client threw an exception. This method will always be called from the thread which called call(). This method will not be called if the client shuts down because the call() method was interrupted.

      By default, this method does nothing. It can be overridden if the factory wants to do something when the factory first begins shutting down.

      Throws:
      Exception - if a problem occurred during this method

    • onStop

      protected void onStop() throws Exception
      This method is called once at the end of this factory's shutdown process after all clients have stopped running. This method will always be called from the thread which called call(). This method will not be called if the client shuts down because the call() method was interrupted.

      By default, this method does nothing. It can be overridden if the factory wants to do something just before the factory stops running.

      Throws:
      Exception - if a problem occurred during this method