Class Agent

java.lang.Object
com.sgware.serialsoc.SerialSocket
edu.uky.cs.nil.tt.Agent
All Implemented Interfaces:
Named, Closeable, AutoCloseable
public class Agent extends com.sgware.serialsoc.SerialSocket implements Named
An agent represents an individual connection to a server that can server as one of the roles in a session.

Every agent is assigned a unique, sequential ID number when it is created. These ID numbers have no special meaning; they exist mainly to identify an agent in system log messages. ID numbers start over at 0 each time the server starts, and an agent's ID number is not preserved in places like the database or session log.

An agent also has a name, which identifies the type of agent it is. It is possible that multiple agents with the same name can be connected to the server at the same time (if all of those agents are of the same type). To identify a specific agent on the server, use its ID number.

Author:
Stephen G. Ware

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    final int
    id
    A unique, sequential ID number assigned to this agent
    final Server
    server
    The server which manages this agent

    Fields inherited from class com.sgware.serialsoc.SerialSocket

    socket

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    Agent(Server server, SSLSocket socket, int id)
    Constructs an agent.

  • Method Summary

    Modifier and Type
    Method
    Description
    List<Turn>
    getChoices()
    Returns the current list of turns this agent can take in their session (which may be empty), or null if this agent has not yet been matched.
    boolean
    getConnected()
    Returns true if this agent is still being managed in some way by the server.
    Agent
    getGM()
    Returns the game master for this agent's session (which might be this agent or their partner), or null if this agent has not yet been matched.
    String
    getName()
    Returns this object's unique name that distinguishes it from other objects of the same type in the same context.
    Agent
    getPartner()
    Returns the other agent in this agent's session, or null if this agent has not yet been matched.
    Agent
    getPlayer()
    Returns the player for this agent's session (which might be this agent or their partner), or null if this agent has not yet been matched.
    Role
    getRole()
    Returns the role this agent is playing in its session, or null if the agent has not yet been matched.
    Session
    getSession()
    Returns the session this agent is participating in, or null if this agent has not yet been matched.
    State
    getState()
    Returns the current state of the story world for this agent's session, as perceived by this agent, or null if this agent has not yet been matched.
    Status
    getStatus()
    Returns the current status of the story for this agent's session, or null if this agent has not yet been matched.
    boolean
    getStopped()
    Checks whether this agent has been sent a stop message yet.
    WorldModel
    getWorld()
    Returns the story world model in which this agent's session takes place, or null if the agent has not yet been matched.
    protected void
    onChoice(Choice choice)
    This method is called each time a choice message is received to take the chosen turn in the agent's session.
    protected void
    onClose()
     
    protected void
    onConnect()
     
    protected void
    onDisconnect()
     
    protected void
    onJoin(Join join)
    This method is called each time a join message is received to establish the agent's identity and preferences.
    protected void
    onReport(Report report)
    This method is called each time a report message is received to record the agent's responses.
    protected void
    onStart(Session session, Agent gm, Agent player)
    This method is called when the server starts a new session that includes this agent.
    protected void
    onStop(Stop stop)
    This method is called either when a stop message is received or when a session is stopped by an agent's partner or the server.
    protected void
    onTurn(Turn turn)
    This method is called each time a new turn is taken in the this agent's session.
    protected void
    receive(String string)
     
    void
    send(Message message)
    Encodes a message as JSON and sends it to the client via this agent's socket.
    protected void
    tick()
    This method is called regularly by the Server to check things that are time-sensative but not triggered by events, such as disconnecting agents who have taken too long to send a message.
    String
    toString()
     

    Methods inherited from class com.sgware.serialsoc.SerialSocket

    close, send

    Methods inherited from class Object

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

  • Field Details

    • server

      public final Server server
      The server which manages this agent

    • id

      public final int id
      A unique, sequential ID number assigned to this agent

  • Constructor Details

    • Agent

      protected Agent(Server server, SSLSocket socket, int id) throws Exception
      Constructs an agent.
      Parameters:
      server - the server that manages this agent
      socket - the socket this agent uses to send and receive messages
      id - a unique ID number assigned to the agent by the server
      Throws:
      Exception - if a problem occurs when creating the agent

  • Method Details

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getName

      public String getName()
      Description copied from interface: Named
      Returns this object's unique name that distinguishes it from other objects of the same type in the same context.
      Specified by:
      getName in interface Named
      Returns:
      the object's unique name

    • getConnected

      public boolean getConnected()
      Returns true if this agent is still being managed in some way by the server. This method may continue to return true even after the agent's socket has been closed if the agent's information might still be needed by the server. When this method returns false, it means this agent's socket has been closed and its information is no longer needed.
      Returns:
      true if the agent is still being used in some way by the server

    • getSession

      public Session getSession()
      Returns the session this agent is participating in, or null if this agent has not yet been matched.
      Returns:
      this agent's session, or null if the agent has not been matched

    • getWorld

      public WorldModel getWorld()
      Returns the story world model in which this agent's session takes place, or null if the agent has not yet been matched.
      Returns:
      this agent's story world model, or null if the agent has not yet been matched

    • getRole

      public Role getRole()
      Returns the role this agent is playing in its session, or null if the agent has not yet been matched.
      Returns:
      the agent's role, or null if the agent has not yet been matched

    • getPartner

      public Agent getPartner()
      Returns the other agent in this agent's session, or null if this agent has not yet been matched.
      Returns:
      this agent's partner, or null if this agent has not yet been matched

    • getGM

      public Agent getGM()
      Returns the game master for this agent's session (which might be this agent or their partner), or null if this agent has not yet been matched.
      Returns:
      the game master of this agent's session, or null if this agent has not yet been matched

    • getPlayer

      public Agent getPlayer()
      Returns the player for this agent's session (which might be this agent or their partner), or null if this agent has not yet been matched.
      Returns:
      the player of this agent's session, or null if this agent has not yet been matched

    • getStatus

      public Status getStatus()
      Returns the current status of the story for this agent's session, or null if this agent has not yet been matched.
      Returns:
      the status of the story for this agent's session, or null if this agent has not yet been matched

    • getState

      public State getState()
      Returns the current state of the story world for this agent's session, as perceived by this agent, or null if this agent has not yet been matched. If this agent is the session's game master, this method returns the actual state of the story world. If this agent is the session's player, this method returns the state the player perceives.
      Returns:
      the state of the story world for this agent's session, or null if this agent has not yet been matched

    • getChoices

      public List<Turn> getChoices()
      Returns the current list of turns this agent can take in their session (which may be empty), or null if this agent has not yet been matched.
      Returns:
      a list of available turns, or null if this agent has not yet been matched

    • getStopped

      public boolean getStopped()
      Checks whether this agent has been sent a stop message yet.
      Returns:
      true if this agent has been sent a stop message

    • onConnect

      protected void onConnect() throws Exception
      Overrides:
      onConnect in class com.sgware.serialsoc.SerialSocket
      Throws:
      Exception

    • send

      public void send(Message message) throws Exception
      Encodes a message as JSON and sends it to the client via this agent's socket.
      Parameters:
      message - the message to send
      Throws:
      Exception - if a problem occurs while encoding the message or sending it via the socket

    • receive

      protected void receive(String string) throws Exception
      Overrides:
      receive in class com.sgware.serialsoc.SerialSocket
      Throws:
      Exception

    • onJoin

      protected void onJoin(Join join) throws Exception
      This method is called each time a join message is received to establish the agent's identity and preferences. Typically, an agent should send exactly one join message. If there is a problem processing the join message, the agent may be notified of the problem, allowing them to send another. Once an agent has successfully established their identity, they should not send any further join messages. This method sets this agent's name. If the agent is requesting a password-protected name, the password is verified. If everything is in order, this method notifies the server that a new agent has joined.
      Parameters:
      join - the join message containing the agent's identity and preferences
      Throws:
      Exception - if a problem occurs while establishing this agent's identify or preferences
      IllegalStateException - if the agent has previously established its identity
      IllegalArgumentException - if the agent failed to provide the correct password when a password is needed

    • onStart

      protected void onStart(Session session, Agent gm, Agent player) throws Exception
      This method is called when the server starts a new session that includes this agent. Typically, this should only happen once per session because agents are disconnected after a session ends. This method establishes things like the story world, this agent's partner, etc.
      Parameters:
      session - the new session this agent is participating in
      gm - the agent who is playing the game master role in the session
      player - the agent who is playing the player role in the session
      Throws:
      Exception - if a problem occurs while the agent is joining the session
      IllegalStateException - if the agent has not yet joined or if the agent is already part of a different session

    • onChoice

      protected void onChoice(Choice choice) throws Exception
      This method is called each time a choice message is received to take the chosen turn in the agent's session. Choices can only be made after a session starts, before it stops, and when it is this agent's turn. Once a turn is taken, both agent in the session are notified.
      Parameters:
      choice - the choice that specifies which turn the agent wants to take
      Throws:
      Exception - if a problem occurs when taking the chosen turn
      IllegalStateException - if the agent has not yet begun a session, if that session has ended, if it is not this agent's turn to act, or if the index of the choice is out of bounds for the list of choices

    • onTurn

      protected void onTurn(Turn turn) throws Exception
      This method is called each time a new turn is taken in the this agent's session. The agent updates their current story status and sends the relevant information over the socket.
      Parameters:
      turn - the turn to be taken in the story
      Throws:
      Exception - if a problem occurs updating the story status
      IllegalStateException - if the agent's session has not yet started

    • onReport

      protected void onReport(Report report)
      This method is called each time a report message is received to record the agent's responses. Reports can only be received after a session starts and before this agent either sends a stop message or causes the session to stop.
      Parameters:
      report - the report message containing the details of the item and reported value
      Throws:
      IllegalStateException - if the agent's session has not yet started or has already stopped

    • tick

      protected void tick() throws Exception
      This method is called regularly by the Server to check things that are time-sensative but not triggered by events, such as disconnecting agents who have taken too long to send a message.
      Throws:
      Exception - if a problem occurs while this method is running

    • onStop

      protected void onStop(Stop stop) throws Exception
      This method is called either when a stop message is received or when a session is stopped by an agent's partner or the server. A session can only stop after it has started. Stop messages may be sent to the agent when the story reaches one of its pre-defined endings, but this method is not called then. This method is only called when the agent sends a stop message to the server, when the agent disconnects, or when the server stops a session. After this method is called, the agent cannot take more turns or send more reports. So an agent may send reports after they receive a stop message because the story reached a pre-defined ending, but they cannot send reports after they send a stop message to the server. Once both agents have either acknowledged that the session has stopped or disconnected, this method alerts the server that the session has ended.
      Parameters:
      stop - the stop message containing the reason for stopping the session
      Throws:
      Exception - if a problem occurs while ending the session
      IllegalStateException - if the agent's session has not yet started

    • onClose

      protected void onClose() throws Exception
      Overrides:
      onClose in class com.sgware.serialsoc.SerialSocket
      Throws:
      Exception

    • onDisconnect

      protected void onDisconnect() throws Exception
      Overrides:
      onDisconnect in class com.sgware.serialsoc.SerialSocket
      Throws:
      Exception