Adding support for a new actor

Adding support for a new actor

Table of Contents

• Actors and transactions
  • Adding new Transaction
  • Adding new Actor
• Simulators
  • Definition
    • Simple simulator
    • Compound simulator
  • Creating a new simulator instance
  • Simulator run time
• Test client
  • Adding transaction definition class
• Tests
  • Writing tests and indexing them against the actor type
  • Defining profile options in ActorOptionManager within Conformance tool
  • Generating the run-time indexes collections and actor-collections

Adding support for a new actor is not a simple thing. It involves the following major steps:

Actors and transactions

Actor and transaction definitions are in separate tables. An actor is configured with the transactions it accepts (receives). This affects simulators. The test client has no knowledge of actors. Its operation is entirely focused on transactions.

Adding new Transaction

Transactions are defined in the enum TransactionType. The definition of the Register transaction looks like:

REGISTER( "ITI-42",      // ID
          "Register",    // Name (used in displays)
          "rb",          // Short name
          "r.b",         // code - used in system configuration file format (External_Cache/actors/foo.xml)
          "r.as",        // async code - obsolete - async not supported
          false,         // requires a repositoryUniqueId
          "urn:ihe:iti:2007:RegisterDocumentSet-b",             // request SOAP Action
          "urn:ihe:iti:2007:RegisterDocumentSet-bResponse",     // response SOAP Action
          false          // requires MTOM
 ),

Adding new Actor

Actors are defined in the enum ActorType. The definition of the Registry actor looks like:

REGISTRY(                     // enum name - referenced in code
    "Document Registry",      // name - used in displays
    Arrays.asList("DOC_REGISTRY", "registryb", "initialize_for_stored_query"), // alternative names
    "reg",                    // short name
    "gov.nist.toolkit.simulators.sim.reg.RegistryActorSimulator",  // simulator run time
    Arrays.asList(TransactionType.REGISTER, TransactionType.REGISTER_ODDE, TransactionType.STORED_QUERY, TransactionType.UPDATE, TransactionType.MPQ),                              // transactions it accepts (as a simulator)
    true,                     // show in configuration (mainly the simulator manager tool)
    null                      // actors file label - not used

        // the following are optional
        "gov.nist.toolkit.simulators.sim.ids.IdsHttpActorSimulator", // http transaction types
        null                      // http simulator class name
),

Looking at the entry for simulator run time above. This is the class that is launched when a transaction request arrives at SimServlet. SimServlet is the servlet that receives all transaction messages to simulators. It uses this table to find the simulator implementation class which is creates an instance of and starts to handle the transaction.

Simulators

Definition

A simulator is a testing oriented implementation of an actor that starts it operation by accepting a transaction. You can think of a simulator as a server - it may generate transactions but its primary job is to wait for incoming requests.

In IHE test parlance a simulator is different from an implementation. A simulator is a test tool and an implementation is something created by a vendor.

Toolkit has two primary facilities, the test client and simulators. Where simulators are the server the test client is where you define clients, tools that start by sending a transaction. The test client is discussed below.

Simple simulator

A simple simulator is a simulator that offers an implementation of a single actor. In the configuration shown above the class referenced is class that implementation.

Compound simulator

A compound simulator is a special simulator that combines two or more simple simulators into one thing. Usually this integration includes some special linkage between the component simulators. Two examples are the Repository/Registry simulator which packages a Document Repository simulator and a Document Registry simulator into one compound simulator. The other is the Responding Gateway which includes a simple Responding Gateway, Document Repository, and Document Registry all in one.

The benefit of a compound simulator is that it can be selected off the Simulator Manager tool UI and created with a few UI selections and button pushes without the need to do detailed configuration. We offer these as a convenience to users.

Creating a new simulator instance

Toolkit can manage any number of simulator instances. There is no in-memory state kept for a simulator. It’s state is entirely kept on disk. Creating a simulator causes this disk image to be created. This image is loaded into memory only when a transaction is received for the simulator and then it is in memory only for the duration of the transaction execution.

The disk image for a simulator is discussed HERE.

Each simulator has an associated factory class that creates a new instance. An example is RegistryActorFactory which creates a new Document Registry actor simulator.

A table is maintained that links the name of an actor with its factory class. This table is found in AbstractActorFactory. An example entry from this table looks like:

factories.put(ActorType.REGISTRY.getName(),           		new RegistryActorFactory());

Notice that the name used is a reference to the ActorType. This assures that the if the name is changes later that it cascades to all its uses.

Simulator run time

Test client

Adding transaction definition class

Adding a transaction

Tests

Writing tests and indexing them against the actor type

Test organization

Test writing documentation

Defining profile options in ActorOptionManager within Conformance tool

See here.

Generating the run-time indexes collections and actor-collections

This is an automated process that happens under two conditions…​

When toolkit is started, the indexes (the contents of toolkitx/testkit/collections and toolkitx/testkit/actorcollections) are automatically built. These directories should not be edited, your edits will be erased at next restart.

There is a second, manual way to build the indexes. This can be used if you are developing tests and storing them in the ExternalCache. On the Toolkit Configuration tab, at the bottom, there is a button labeled Reindex Test Kits. This will rebuild the indexes.