Table of Contents
This example provides information on the following topics:
About persistence.
Using persistence.
Running the example.
The ADK offers persistence which allows a running application to continue after it has been restarted. Agents reside on a computer, and in the event that the computer, which contains the habitat, goes down, persistence prevents the agents from disappearing. The saving and restoring of agents is known as Persistence, and is an important feature of the ADK.
A persisted agent is stored in a database. To be able to do so, the ADK must be able to communicate with the database. With the release of ADK 2.0, persistence is preconfigured using hsqldb. Other databases are supported and configuring the coupling between the habitat and the database system is a crucial process during installation. This is further explained in the Quick Start guide. This example assumes that the habitat is already installed.
Persistence is provided by storing the complete state of agents in a database. All agents are automatically checkpointed, or stored in the database, when first arriving in a habitat. Agents can also request to be checkpointed by sending a message with the subject checkpoint-sender to the local place system agent. This feature is called snapshotting, which can be used to secure the agent state after an important transaction. The AFC provides a standard wrapper task for this protocol, the CheckpointTask.
Agents can also request to be suspended for a specific period. This is done by sending a message with the subject suspend-sender and a period in seconds to the place agent. When that period has passed, the agent will be resumed. An agent will also be resumed when it receives a message.
The suspend-resume feature allows one to swap inactive or less active agents out of memory, improving resource usage and scalability. The ARE ensures that supension is fully transparent to other agents.
By default, persistence is used when starting a habitat. To influence or override default persistence behavior, use command line arguments. Many are described in the Quickstart Guide. The --help command line argument provides a listing of all available options. When using persistence, the following are commonly used:
| --clean-db |
| --start-immediately |
The --start-immediately option is relevant when restoring a database with many agents. The --clean-db option is demonstated in the example.
The example uses a simple agent that performs two tasks. It frequently logs a message containing a counter, making it easy to checkpoint its progress. It also occasionally checkpoints itself (see the PersistenceDemoTask). The persistence.xml habitat file specifies a simple habitat with one agent.
The following steps take you through some features of persistence:
Start the habitat with the option to clear the persistence database and with an XML habitat file specifying the initial state. Check the XML habitat file to see if the habitat you get is indeed the one specified in that file. Stop the habitat using Control-C after the agent has logged around five messages.
habitat --clean-db persistence.xml
Execute the command again to restart the habitat. Note that the result is the same as when you started the habitat for the first time. Again, stop the habitat after the agent has logged a few messages.
habitat --clean-db persistence.xml
Start the habitat without any specification. Note that the database is used to restore the checkpointed agent to the most recently checkpointed state. This is neither the initial state nor the exact state it was in when you last stopped the habitat. Again, let the agent log a few messages and stop the habitat.
habitat
Start the habitat both using persistence (implicitly) and specifying an initial habitat state. Note that now you get two agents: the persisted one, which is restored from the database and a new one specified in the XML habitat file. Stop the habitat again.
habitat persistence.xml
Start the habitat again using a different habitat XML file. Note that you still get the two persistent agents from the previous run. They will always return when you start a habitat until you use them for the first time. Use the --clean-db startup option to remove them from the database.
habitat chat1.xml