Class Database

java.lang.Object
edu.uky.cs.nil.tt.Database
public class Database extends Object
A database is a server's persistent store of information about the story worlds and agents available for sessions.

All of the worlds and agents in the database are available for all sessions, but entries either advertise that they exist (listed) or do not advertise that they exist (unlisted). Listed entries are available when a new user connects to browse possible worlds and agents. Unlisted entries must be specifically requested by name.

A database is designed to be small and serializable. World entries do not store the assets or implementation logic of a world model in the database; they simply store a path to the file where the world model is serialized. When a database is deserialized, it should deserialize all world models.

Agent entries can be password protected. This means that an agent cannot use a protected name unless it provides the correct password. This can be used to prevent two different agents from using the same name, either accidentally or on purpose.

A database is not thread safe. Behavior is undefined if it is accessed simultaneously by multiple threads.

Author:
Stephen G. Ware

  • Constructor Details

    • Database

      public Database(File file, Log log) throws IOException
      Constructs a new empty database or deserializes it from a file.
      Parameters:
      file - the file in which the database is serialized, or null if an empty database should be created
      log - the log to which important status messages will be written as the database is created and deserialized
      Throws:
      IOException - if the file cannot be found or if a problem occurs when deserializing the database

  • Method Details

    • getListedWorlds

      public List<Database.Entry> getListedWorlds()
      Returns a list of entries for all listed worlds in this database.
      Returns:
      a list of worlds that are advertised as available

    • getWorld

      public Database.WorldEntry getWorld(String name)
      Returns the entry for the world model with the given name or null if the database has no world model with that name. This method may return an unlisted world.
      Parameters:
      name - the name of the world model whose entry is desired
      Returns:
      the entry for the world model with that name, or null if the database has no entry for a world with that name

    • requireWorld

      public Database.WorldEntry requireWorld(String name)
      Returns the entry for the world model with the given name or throws an exception if no such entry exists.
      Parameters:
      name - the name of the world model whose entry is desired
      Returns:
      the entry for the world model with that name
      Throws:
      IllegalArgumentException - if there is no entry for a world model with that name

    • getRandomWorld

      public Database.WorldEntry getRandomWorld()
      Returns a randomly chosen listed world entry.
      Returns:
      a random listed world entry
      Throws:
      IllegalStateException - if the database contains no listed world entries

    • addWorld

      public void addWorld(WorldModel world)
      Adds a new world entry to the database for a given world and writes the database to file. If the database already contains an entry for a world with the given world's name, the old entry is replaced.
      Parameters:
      world - the new world model to add to the database

    • addWorld

      public void addWorld(File file) throws IOException
      Deserializes a world model from a given file, adds the world model to the database, and writes the database to file.
      Parameters:
      file - a file that contains a serialized world model
      Throws:
      IOException - if the file does not exist or if there is a problem reading the world model from the file

    • setWorldTitle

      public void setWorldTitle(String name, String title)
      Sets the title of a world model's entry and writes the database to file.
      Parameters:
      name - the system name of the world model
      title - the new title for the world model
      Throws:
      IllegalArgumentException - if there is no entry for a world model with that name

    • setWorldDescription

      public void setWorldDescription(String name, String description)
      Sets the description of a world model's entry and writes the database to file.
      Parameters:
      name - the system name of the world model
      description - the new description for the world model
      Throws:
      IllegalArgumentException - if there is no entry for a world model with that name

    • setWorldListed

      public void setWorldListed(String name, boolean value)
      Sets whether a given world model's entry is listed and writes the database to file.
      Parameters:
      name - the system name of the world model
      value - true if the world should be listed, false if it should not be listed
      Throws:
      IllegalArgumentException - if there is no entry for a world model with that name

    • removeWorld

      public void removeWorld(String name)
      Removes the entry from this database for the world model with the given name (if one exists) and writes the database to file.
      Parameters:
      name - the system name of the world model
      Throws:
      IllegalArgumentException - if there is no entry for a world model with that name

    • getListedAgents

      public List<Database.Entry> getListedAgents()
      Returns a list of entries for all listed agents in this database.
      Returns:
      a list of agents that are advertised as available

    • getAgent

      public Database.AgentEntry getAgent(String name)
      Returns the entry for the agent with the given name or null if the database has no agent that name. This method may return an unlisted agent.
      Parameters:
      name - the name of the agent whose entry is desired
      Returns:
      the entry for the agent with that name, or null if the database has no entry for an agent with that name

    • requireAgent

      public Database.AgentEntry requireAgent(String name)
      Returns the entry for the agent with the given name or throws an exception if no such entry exists.
      Parameters:
      name - the name of the agent whose entry is desired
      Returns:
      the entry for the agent with that name
      Throws:
      IllegalArgumentException - if there is no entry for an agent with that name

    • addAgent

      public void addAgent(String name)
      Adds a new agent entry to the database for a given agent name and writes the database to file. If the database already contains an entry for an agent with the given name, the entry is unchanged.
      Parameters:
      name - the name of the agent to add to the database

    • setAgentTitle

      public void setAgentTitle(String name, String title)
      Sets the title of an agent's entry and writes the database to file.
      Parameters:
      name - the system name of the agent
      title - the new title for the agent
      Throws:
      IllegalArgumentException - if there is no entry for an agent with that name

    • setAgentDescription

      public void setAgentDescription(String name, String description)
      Sets the description of an agent's entry and writes the database to file.
      Parameters:
      name - the system name of the agent
      description - the new description for the agent
      Throws:
      IllegalArgumentException - if there is no entry for an agent with that name

    • setAgentPassword

      public void setAgentPassword(String name, String password)
      Sets the password of an agent's entry and writes the database to file. The password will be salted and hashed before it is stored.
      Parameters:
      name - the system name of the agent
      password - the new password for the agent
      Throws:
      IllegalArgumentException - if there is no entry for an agent with that name

    • setAgentLimit

      public void setAgentLimit(String name, int limit)
      Sets the limit on how many agents with the given name may be in sessions simultaneously and writes the database to file.
      Parameters:
      name - the system name of the agent
      limit - the maximum number of agents with the given name which may be running simultaneously, or 0 for no limit
      Throws:
      IllegalArgumentException - if there is no entry for an agent with that name

    • setAgentListed

      public void setAgentListed(String name, boolean value)
      Sets whether a given agent's entry is listed and writes the database to file.
      Parameters:
      name - the system name of the agent
      value - true if the agent should be listed, false if it should not be listed
      Throws:
      IllegalArgumentException - if there is no entry for an agent with that name

    • removeAgent

      public void removeAgent(String name)
      Removes the entry from this database for the agent with the given name (if one exists) and writes the database to file.
      Parameters:
      name - the system name of the agent
      Throws:
      IllegalArgumentException - if there is no entry for an agent with that name

    • write

      public void write() throws IOException
      Writes this database to file. The file to which it is written is set in the database's constructor. If this database is temporary (i.e. never written to file), this method does nothing.
      Throws:
      IOException - if a problem occurs while writing the database to file