TestDriver (Decision Server Insights Java API)

java.lang.Object
- com.ibm.ia.testdriver.TestDriver

All Implemented Interfaces:

DebugReceiver
```
public class TestDriver
extends java.lang.Object
implements DebugReceiver
```
A Test Driver object that provides all methods required to test a solution. TestDriver is configured through a variety of properties contained within a Java Properties object which contains property/value pairs for the various properties. The java properties can be stored in a file called testdriver.properties. The file can be in one of 2 locations, in the user's current directory or in a directory location defined by the "testdriver_home" environment variable. For example:
    solutionname=HelloWorldSolution
    hostname=localhost
    catalogserverendpoints=localhost:2809,server1:2909,server2:2810

Field Summary

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`ALL_AGENTS`
`static int`	`MAX_EVENT_SUBMIT_DELAY`
`static java.lang.String`	`TEST_EPOCH_PROPERTY` This solution property is used to establish a temporal point of reference for a sequence of events containing time stamps in the past.

Constructor Summary

Constructors
Constructor and Description
`TestDriver()` A no-argument constructor, initialized test properties from a file named testdriver.properties in the system user.dir folder if it exists, or in a directory defined by the testdrive_home environment variable if it is set.
`TestDriver(java.util.Properties properties)` Create a TestDriver object with the passed properties.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addDebugReceiver(DebugReceiver r)` Add a listener to receive DebugInfo objects received by the TestDriver.
`boolean`	`clearTestEpoch()` Clears the value of the test epoch property.
`void`	`connect()` create a solution gateway connection to the grid for the given solution.
`void`	`connect(int timeout)` create a solution gateway connection to the grid.
`void`	`connect(java.lang.String solnName)` create a solution gateway connection to the grid for the passed solution.
`void`	`connect(java.lang.String name, int timeout)` create a solution gateway connection to the grid for the solution.
`EntitySource<java.io.File>`	`createFileEntitySource(DataFormat format, java.lang.String path)` A FileEntitySource can be used to create a collection of entities from a set of files in a directory.
`EntitySource<java.io.File>`	`createFileEntitySource(DataFormat format, java.lang.String path, java.lang.String pattern)` A FileEntitySource can be used to create a collection of entities from a set of files in a directory.
`EntitySource<java.io.File>`	`createFileEntitySource(DataFormat format, java.lang.String path, java.lang.String pattern, int skipFailureBitmask, java.lang.String encoding)` A FileEntitySource can be used to create a collection of entities from a set of files in a directory.
`EventSource<java.io.File>`	`createFileEventSource(DataFormat format, java.lang.String path)` A FileEventSource can be used to create a collection of events from a set of files in a directory.
`EventSource<java.io.File>`	`createFileEventSource(DataFormat format, java.lang.String path, java.lang.String pattern)` A FileEventSource can be used to create a collection of events from a set of files in a directory.
`EventSource<java.io.File>`	`createFileEventSource(DataFormat format, java.lang.String path, java.lang.String pattern, int skipFailureBitmask, java.lang.String encoding)` A FileEventSource can be used to create a collection of events from a set of files in a directory.
`<T extends Entity> Relationship<T>`	`createRelationship(java.lang.Class<T> entity, java.lang.String key)` Convenience method to create Relationships
`<T extends Entity> Relationship<T>`	`createRelationship(T t)` Convenience method to create Relationships
`boolean`	`deleteAllEntities()` delete all entity instances of all entity types in the current solution.
`void`	`deleteAllEntities(java.lang.String entityType)` delete all entities of the given type from the grid.
`void`	`deleteEntity(java.lang.String entityType, java.lang.String entityId)` remove an entity of the given type and ID from the grid.
`void`	`disconnect()` called after connect() to disconnect the TestDriver instance from the grid.
`boolean`	`endTest()` Can be called on the completion of a test to notify the server to trigger any processing that has been scheduled by, or on behalf of, an agent.
`<T extends Entity> T`	`fetchEntity(java.lang.Class<T> entityClass, java.lang.String entityId)` return an entity from the runtime for the specified entity Class and identifier.
`Event`	`getAgentEvent(DebugInfo db)` From the debug object, extract the actual event which was submitted by the agent.
`Event`	`getAgentEvent(DebugInfo db, java.lang.Boolean useXOM)`
`<T> T`	`getConceptFactory(java.lang.Class<T> conceptFactoryClass)` Provides access to the package specific ConceptFactory of the Java Model, which should be used to create Events, Entities and Concepts in that package
`EventFactory`	`getEventFactory()` Get an EventFactory to use for creating events.
`ModelSerializer`	`getModelSerializer()` Provides access to the ModelSerializer, which should be used to serialize and parse Events and Entities
`java.lang.String`	`getProductId()` get the name and version of the product
`java.util.Properties`	`getProperties()` get the properties currently defined in the system.
`int`	`getProperty(java.lang.String property, int def)` get an integer property.
`java.lang.String`	`getProperty(java.lang.String property, java.lang.String def)` get a String property.
`java.util.List<java.lang.String>`	`getRuntimeServers()` returns a list of runtime servers currently running in the grid cluster.
`SolutionGateway`	`getSolutionGateway()` returns the solution gateway that is used by the TestDriver instance.
`java.lang.String`	`getSolutionName()` Returns connected solution name, or null if not connected.
`java.lang.String`	`getSolutionProperty(java.lang.String propertyName)` retrieves specified solution property.
`boolean`	`isRuntimeReady()` test to see if the runtime is available and ready.
`boolean`	`isSolutionReady()` Test to see if the current solution is deployed and ready.
`boolean`	`isSolutionReady(java.lang.String solutionName)` Test to see if a solution is deployed and ready.
`java.util.Map<java.lang.String,java.util.Set<java.lang.String>>`	`loadEntities(java.util.Iterator<? extends Entity> entities)` Load a collection of entities into the system.
`java.util.Map<java.lang.String,java.util.Set<java.lang.String>>`	`loadEntities(java.util.List<? extends Entity> entities)` Load a collection of entities into the system.
`void`	`loadEntity(Entity entity)` Loads an entity into the grid entity map.
`boolean`	`processPendingSchedules(java.lang.String dateTime)` Notify the server to trigger any processing that has been scheduled by, or on behalf of, an agent.
`boolean`	`processPendingSchedules(java.time.ZonedDateTime dateTime)` Notify the server to trigger any processing that has been scheduled by, or on behalf of, an agent.
`void`	`removeDebugReceiver(DebugReceiver r)` remove a DebugInfo listener.
`boolean`	`resetSolutionState()` reset the state (clear history) of the current solution.
`void`	`setGatewayMaxSubmitDelay(int delay)` overrides max allowed event submission delay on the gateway.
`void`	`setProperties(java.util.Properties properties)` Replace all current TestDriver properties with the passed property values.
`void`	`setProperty(java.lang.String name, java.lang.String value)` set a specific TestDriver property.
`boolean`	`setTestEpoch(java.lang.String testEpoch)` Establish a temporal point of reference to process events with time stamps in the past.
`java.lang.String`	`startRecording()` Start a debug recording on the latest version of the current solution.
`boolean`	`stopRecording()` Stop the active debug recording on the current solution, after which the results of events processed can be viewed in the web-based debug tool.
`RoutingStatus`	`submitEvent(Event event)` Submit an event to the solution.
`java.util.Map<java.lang.String,RoutingStatus>`	`submitEvents(java.util.Iterator<? extends Event> events)` Submit a collection of events to the solution.
`java.util.Map<java.lang.String,RoutingStatus>`	`submitEvents(java.util.Iterator<? extends Event> events, boolean useProcessPendingSchedules)` Submit a collection of events to the solution.
`void`	`toXMLBytes(java.io.OutputStream stream, Entity entity)` serializes entity to XML using the generic entity schema and "UTF-8" encoding.
`java.lang.String`	`toXMLString(Entity entity)` serializes entity to XML using the generic entity schema.
`void`	`updateEntity(Entity entity)` update an entity in the grid.
`boolean`	`validateProperties()` Validate the current properties.
`boolean`	`waitUntilSolutionIdle()` Query the DSI runtime cluster-wide whether there are zero events being processed for the current solution.
`boolean`	`waitUntilSolutionIdle(int maxWaitSeconds)` Query the DSI runtime cluster-wide whether there are zero events being processed for the current solution.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.ibm.ia.testdriver.DebugReceiver
addDebugInfo

- Field Detail
  - ALL_AGENTS
```
public static java.lang.String ALL_AGENTS
```
  - MAX_EVENT_SUBMIT_DELAY
```
public static final int MAX_EVENT_SUBMIT_DELAY
```
    See Also:
    Constant Field Values
  - TEST_EPOCH_PROPERTY
```
public static final java.lang.String TEST_EPOCH_PROPERTY
```
    This solution property is used to establish a temporal point of reference for a sequence of events containing time stamps in the past. It should only be used for test purposes.
    
    See Also:
    Constant Field Values
- Constructor Detail
  - TestDriver
```
public TestDriver()
```
    A no-argument constructor, initialized test properties from a file named testdriver.properties in the system user.dir folder if it exists, or in a directory defined by the testdrive_home environment variable if it is set.
  - TestDriver
```
public TestDriver(java.util.Properties properties)
```
    Create a TestDriver object with the passed properties.
    
    Throws:
    
    TestDriverException - if an error occurs during initialization
    Parameters:
    properties - java properties used to initialize the TestDriver instance.
- Method Detail
  - connect
```
public void connect()
             throws GatewayException
```
    create a solution gateway connection to the grid for the given solution. If a connection is not made within a default time of 30 seconds, an exception is returned.
    
    Throws:
    
    GatewayException
    See Also:
    connect( int timeout )
  - connect
```
public void connect(java.lang.String name,
           int timeout)
             throws GatewayException
```
    create a solution gateway connection to the grid for the solution. If a connection is not made within the specified timeout (in seconds), an exception is returned. This method is equivalent to setting the SOLUTION_NAME property and calling connect( timeout ).
    
    Throws:
    
    GatewayException
    Parameters:
    name - of the solution for the gateway connection.
    timeout - number of seconds to wait for a connection to become available.
    See Also:
    connect( int timeout )
  - connect
```
public void connect(java.lang.String solnName)
             throws GatewayException
```
    create a solution gateway connection to the grid for the passed solution. If a connection is not made within a default time of 30 seconds, an exception is returned. This method is equivalent to setting the SOLUTION_NAME property and calling connect().
    
    Throws:
    
    GatewayException
    Parameters:
    name - of the solution for the gateway connection.
    See Also:
    connect( int timeout )
  - connect
```
public void connect(int timeout)
             throws GatewayException
```
    create a solution gateway connection to the grid. After this method completes, events can be sent to the system using the submitEvent method:
    submitEvent(Event event)
    A successful connection requires both a valid solution name and GridConfiguration. The solution name is specified as a the solutionname property within the testdriver properties. Set the GridConfiguration using the CatalogServerEndpoint property (see Class documentation).
    After a successful connection, changes to the solution name and GridConfiguration will have no effect. To connect with a different solution name or GridConfiguration first disconnect, and then connect with the new properties set.
    
    Throws:
    
    GatewayException - if the connection cannot be established.
    Parameters:
    timeout - number of seconds to wait for a connection to become available.
  - disconnect
```
public void disconnect()
```
    called after connect() to disconnect the TestDriver instance from the grid.
    
    Throws:
    
    java.lang.InterruptedException
  - getSolutionName
```
public java.lang.String getSolutionName()
```
    Returns connected solution name, or null if not connected.
    
    Returns:
  - fetchEntity
```
public <T extends Entity> T fetchEntity(java.lang.Class<T> entityClass,
                               java.lang.String entityId)
```
    return an entity from the runtime for the specified entity Class and identifier. fetchEntity uses the current runtimehostname (default: localhost) and httpport (default: 9443) to retrieve the entity. Both runtimehostname and httport can be set in the Java properties used to initialize testdriver.
    
    Throws:
    
    TestDriverException - on error
    Parameters:
    entityClass - the classname of a class that extends Entity
    entityId - the identifier of the new entity
    
    Returns:
    The fetched entity or null if the entity is not found
  - loadEntity
```
public void loadEntity(Entity entity)
                throws java.lang.Exception
```
    Loads an entity into the grid entity map.
    
    Throws:
    
    com.ibm.websphere.objectgrid.ObjectGridException
    
    java.lang.Exception
    Parameters:
    entity - the Entity to load
  - loadEntities
```
public java.util.Map<java.lang.String,java.util.Set<java.lang.String>> loadEntities(java.util.List<? extends Entity> entities)
                                                                             throws MultipleEntityLoadException
```
    Load a collection of entities into the system. Entity loading will halt if a problem is encountered. A map containing the types and IDs of the entities that were successfully loaded will be attached to the MultipleEntityLoadException thrown as a result of the failure.
    
    Throws:
    
    MultipleEntityLoadException - If a problem occurs during the load operation.
    Parameters:
    entities - the entities to load
    
    Returns:
    A map in which the keys are the types of the entities successfully loaded and the values are the the set of successfully loaded entity IDs of that type.
  - loadEntities
```
public java.util.Map<java.lang.String,java.util.Set<java.lang.String>> loadEntities(java.util.Iterator<? extends Entity> entities)
                                                                             throws MultipleEntityLoadException
```
    Load a collection of entities into the system. Entity loading will halt if a problem is encountered. A map containing the types and IDs of the entities that were successfully loaded will be attached to the MultipleEntityLoadException thrown as a result of the failure.
    
    Throws:
    
    MultipleEntityLoadException - If a problem occurs during the load operation.
    Parameters:
    entities - the entities to load
    
    Returns:
    A map in which the keys are the types of the entities successfully loaded and the values are the the set of successfully loaded entity IDs of that type.
  - updateEntity
```
public void updateEntity(Entity entity)
```
    update an entity in the grid. The entity must already exist (by loadEntity). Any field in the entity can be changed except the id field.
    
    Throws:
    
    TestDriverException - on error
    Parameters:
    genericEntity - the GenericEntity to update
  - deleteEntity
```
public void deleteEntity(java.lang.String entityType,
                java.lang.String entityId)
```
    remove an entity of the given type and ID from the grid.
    
    Throws:
    
    TestDriverException - on error
    Parameters:
    entityType - the type of the entity to remove
    entityID - the ID of the entity to remove
  - deleteAllEntities
```
public void deleteAllEntities(java.lang.String entityType)
```
    delete all entities of the given type from the grid. Only entities of the specified type are removed. Specifically, entities within a hierarchy are not removed. Java subtypes of the specified type are not removed
    
    Throws:
    
    TestDriverException - on error
    Parameters:
    entityType - type of the entity to remove.
  - deleteAllEntities
```
public boolean deleteAllEntities()
```
    delete all entity instances of all entity types in the current solution.
    
    Throws:
    
    TestDriverException - if connection or other error
    
    Returns:
    true if success
  - endTest
```
public boolean endTest()
```
    Can be called on the completion of a test to notify the server to trigger any processing that has been scheduled by, or on behalf of, an agent. Returns after the triggered processing has completed, or a predetermined time out (based on the http_timeout property value) is reached.
    
    Returns:
    true if processing is completed within a predetermined timeout, false otherwise.
    See Also:
    com.ibm.ia.Agent#schedule(int delay, TimeUnit unit, String cookie), com.ibm.ia.Agent#schedule(ZonedDateTime dateTime, String cookie)
  - processPendingSchedules
```
public boolean processPendingSchedules(java.lang.String dateTime)
                                throws java.time.format.DateTimeParseException
```
    Notify the server to trigger any processing that has been scheduled by, or on behalf of, an agent. Scheduled processing is synchronously triggered in chronological order, including any additional processing that may by scheduled, up to the specified cutoff time.
    
    Throws:
    
    java.time.format.DateTimeParseException - if the date string is not valid.
    Parameters:
    dateTime - an ISO 8601 date and time String representing the cutoff time. Pending calls beyond this time are unaffected.
    
    Returns:
    true if processing is successful, false otherwise.
    See Also:
    com.ibm.ia.Agent#schedule(int delay, TimeUnit unit, String cookie), com.ibm.ia.Agent#schedule(ZonedDateTime dateTime, String cookie)
  - processPendingSchedules
```
public boolean processPendingSchedules(java.time.ZonedDateTime dateTime)
```
    Notify the server to trigger any processing that has been scheduled by, or on behalf of, an agent. Scheduled processing is synchronously triggered in chronological order, including any additional processing that may by scheduled, up to the specified cutoff time.
    
    Parameters:
    dateTime - a ZonedDateTime object representing the cutoff time. Pending calls beyond this time are unaffected.
    
    Returns:
    true if processing is successful, false otherwise.
    See Also:
    com.ibm.ia.Agent#schedule(int delay, TimeUnit unit, String cookie), com.ibm.ia.Agent#schedule(ZonedDateTime dateTime, String cookie)
  - toXMLString
```
public java.lang.String toXMLString(Entity entity)
```
    serializes entity to XML using the generic entity schema.
    
    Parameters:
    entity - the entity instance to be serialized.
    
    Returns:
    XML string for the entity
  - toXMLBytes
```
public void toXMLBytes(java.io.OutputStream stream,
              Entity entity)
                throws java.io.IOException
```
    serializes entity to XML using the generic entity schema and "UTF-8" encoding.
    
    Throws:
    
    java.io.IOException
    Parameters:
    stream - Output stream to write XML bytes to
    entity - the entity instance to be serialized.
  - getSolutionGateway
```
public SolutionGateway getSolutionGateway()
                                   throws GatewayException
```
    returns the solution gateway that is used by the TestDriver instance.
    
    Throws:
    
    GatewayException
    
    Returns:
    the SolutionGateway
  - setGatewayMaxSubmitDelay
```
public void setGatewayMaxSubmitDelay(int delay)
                              throws GatewayException
```
    overrides max allowed event submission delay on the gateway.
    
    Throws:
    
    GatewayException
    Parameters:
    delay - delay in ms; 0 value means no delay is allowed
  - getEventFactory
```
public EventFactory getEventFactory()
                             throws SolutionException,
                                    GatewayException
```
    Get an EventFactory to use for creating events.
    
    Throws:
    
    SolutionException
    
    GatewayException
    
    Returns:
    the EventFactory
  - getConceptFactory
```
public <T> T getConceptFactory(java.lang.Class<T> conceptFactoryClass)
                    throws SolutionException,
                           GatewayException
```
    Provides access to the package specific ConceptFactory of the Java Model, which should be used to create Events, Entities and Concepts in that package
    
    Throws:
    
    SolutionChangedException - indicates that solution has been changed on the server
    
    GatewayException - indicates problem connecting to the solution
    
    SolutionException
    Parameters:
    conceptFactoryClass - ConceptFactory class for a specific Java Model package
    
    Returns:
    instance of ConceptFactory for this test driver
  - getModelSerializer
```
public ModelSerializer getModelSerializer()
                                   throws SolutionException,
                                          GatewayException
```
    Provides access to the ModelSerializer, which should be used to serialize and parse Events and Entities
    
    Throws:
    
    SolutionChangedException - indicates that solution has been changed on the server
    
    GatewayException - indicates problem connecting to the solution
    
    SolutionException
    
    Returns:
    instance of ModelSerializer for this test driver
  - createRelationship
```
public <T extends Entity> Relationship<T> createRelationship(T t)
                                                  throws SolutionException,
                                                         GatewayException
```
    Convenience method to create Relationships
    
    Throws:
    
    SolutionChangedException - indicates that solution has been changed on the server
    
    GatewayException - indicates problem connecting to the solution
    
    SolutionException
    Parameters:
    t - Entity instance for this relationship
    
    Returns:
    relationship to a given entity instance
  - createRelationship
```
public <T extends Entity> Relationship<T> createRelationship(java.lang.Class<T> entity,
                                                    java.lang.String key)
                                                  throws SolutionException,
                                                         GatewayException
```
    Convenience method to create Relationships
    
    Throws:
    
    SolutionChangedException - indicates that solution has been changed on the server
    
    GatewayException - indicates problem connecting to the solution
    
    SolutionException
    Parameters:
    entity - entity class type for this relationship
    key - entity id for this relationship
    
    Returns:
    relationship to entity instance identified by type and key
  - createFileEntitySource
```
public EntitySource<java.io.File> createFileEntitySource(DataFormat format,
                                                java.lang.String path)
                                                  throws TestDriverException
```
    A FileEntitySource can be used to create a collection of entities from a set of files in a directory. These files will be read by the entity source and converted into entities using the default encoding determined from the file contents. This collection of entities can then be loaded into the system using the loadEntities() method by passing the iterator returned by the entity source iterator() method.
    
    Throws:
    
    TestDriverException - Thrown if an error occurs initializing the FileEntitySource.
    Parameters:
    format - The DataFormat to use when creating the entities from the content of the files.
    path - The path to the directory where the files are located. All files in the directory will be loaded. Null or the empty string are not accepted values.
    
    Returns:
  - createFileEntitySource
```
public EntitySource<java.io.File> createFileEntitySource(DataFormat format,
                                                java.lang.String path,
                                                java.lang.String pattern)
                                                  throws TestDriverException
```
    A FileEntitySource can be used to create a collection of entities from a set of files in a directory. These files will be read by the entity source and converted into entities using the default encoding determined from the file contents. This collection of entities can then be loaded into the system using the loadEntities() method by passing the iterator returned by the entity source iterator() method.
    
    Throws:
    
    TestDriverException - Thrown if an error occurs initializing the FileEntitySource.
    Parameters:
    format - The DataFormat to use when creating the entities from the content of the files.
    path - The path to the directory where the files are located. All files in the directory will be loaded. Null or the empty string are not accepted values.
    pattern - A regular expression describing the files in the directory you wish to load. All files will be loaded if set to null.
    
    Returns:
  - createFileEntitySource
```
public EntitySource<java.io.File> createFileEntitySource(DataFormat format,
                                                java.lang.String path,
                                                java.lang.String pattern,
                                                int skipFailureBitmask,
                                                java.lang.String encoding)
                                                  throws TestDriverException
```
    A FileEntitySource can be used to create a collection of entities from a set of files in a directory. These files will be read by the entity source and converted into entities using the encoding information supplied. This collection of entities can then be loaded into the system using the loadEntities() method by passing the iterator returned by the entity source iterator() method.
    Throws:
    
    TestDriverException - Thrown if an error occurs initializing the FileEntitySource.
    Parameters:
    format - The DataFormat to use when creating the entities from the content of the files.
    path - The path to the directory where the files are located. Null or the empty string are not accepted values.
    pattern - A regular expression describing the files in the directory you wish to load. All files will be loaded if set to null.
    skipFailureBitmask - A bit mask allowing you to modify the behaviour of this FileEntitySource when it encounters a problem with loading an entity. Current allowed values are:
    EntitySource.SKIP_NO_FAILURES - Do not skip any failures. An exception will be thrown when the first problem is encountered.
    
    EntitySource.SKIP_UNRECOGNISED_ENTITIES - Skip any entities that are unrecognised by the solution. Files containing unrecognised entities will not trigger an exception.
    encoding - The character encoding to use when parsing the entities. The default encoding determined from the file contents will be used if set to null.
    
    Returns:
  - createFileEventSource
```
public EventSource<java.io.File> createFileEventSource(DataFormat format,
                                              java.lang.String path)
                                                throws TestDriverException
```
    A FileEventSource can be used to create a collection of events from a set of files in a directory. These files will be read by the event source and converted into events using the default encoding determined from the file contents. This collection of events can then be submitted to the system using the submitEvents() method by passing the iterator returned by the event source iterator() method.
    
    Throws:
    
    TestDriverException - Thrown if an error occurs initializing the FileEventSource.
    Parameters:
    format - The DataFormat to use when creating the events from the content of the files.
    path - The path to the directory where the files are located. All files in the directory will be loaded. Null or the empty string are not accepted values.
    
    Returns:
  - createFileEventSource
```
public EventSource<java.io.File> createFileEventSource(DataFormat format,
                                              java.lang.String path,
                                              java.lang.String pattern)
                                                throws TestDriverException
```
    A FileEventSource can be used to create a collection of events from a set of files in a directory. These files will be read by the event source and converted into events using the default encoding determined from the file contents. This collection of events can then be submitted to the system using the submitEvents() method by passing the iterator returned by the event source iterator() method.
    
    Throws:
    
    TestDriverException - Thrown if an error occurs initializing the FileEventSource.
    Parameters:
    format - The DataFormat to use when creating the events from the content of the files.
    path - The path to the directory where the files are located. Null or the empty string are not accepted values.
    pattern - A regular expression describing the files in the directory you wish to load. All files will be loaded if set to null.
    
    Returns:
  - createFileEventSource
```
public EventSource<java.io.File> createFileEventSource(DataFormat format,
                                              java.lang.String path,
                                              java.lang.String pattern,
                                              int skipFailureBitmask,
                                              java.lang.String encoding)
                                                throws TestDriverException
```
    A FileEventSource can be used to create a collection of events from a set of files in a directory. These files will be read by the event source and converted into events using the encoding information supplied. This collection of events can then be submitted to the system using the submitEvents() method by passing the iterator returned by the event source iterator() method.
    Throws:
    
    TestDriverException - Thrown if an error occurs initializing the FileEventSource.
    Parameters:
    format - The DataFormat to use when creating the events from the content of the files.
    path - The path to the directory where the files are located. Null or the empty string are not accepted values.
    pattern - A regular expression describing the files in the directory you wish to load. All files will be loaded if set to null.
    skipFailureBitmask - A bit mask allowing you to modify the behaviour of this FileEventSource when it encounters a problem with submitting an event. Current allowed values are:
    EventSource.SKIP_NO_FAILURES - Do not skip any failures. An exception will be thrown when the first problem is encountered.
    
    EventSource.SKIP_UNRECOGNISED_EVENTS - Skip any events that are unrecognised by the solution. Files containing unrecognised events will not trigger an exception.
    encoding - The character encoding to use when parsing the events. The default encoding determined from the file contents will be used if set to null.
    
    Returns:
  - submitEvent
```
public RoutingStatus submitEvent(Event event)
                          throws GatewayException,
                                 RoutingException
```
    Submit an event to the solution.
    
    Any processing that is scheduled to be processed before or at the time stamp of the event is triggered in chronological order before the event is submitted. However, this method does not synchronize event submission with solution processing.
    
    Throws:
    
    GatewayException
    
    RoutingException
    Parameters:
    event - The event to be submitted
  - submitEvents
```
public java.util.Map<java.lang.String,RoutingStatus> submitEvents(java.util.Iterator<? extends Event> events)
                                                           throws MultipleEventSubmitException
```
    Submit a collection of events to the solution. Events will be submitted in the order they are provided by the supplied iterator.
    
    Event submission will halt upon the first problem encountered. A map of the RoutingStatus values for all successful event submissions up to the point of the first failure will be attached to the MultipleEventSubmitException thrown as a result of the failure.
    
    Any processing that is scheduled to be processed before or at the time stamp of each event is triggered in chronological order before the event is submitted. However, this method does not synchronize event submission with solution processing.
    
    Throws:
    
    MultipleEventSubmitException - If a problem occurs with delivery of one of the events.
    
    java.lang.NullPointerException - If the supplied iterator is null.
    Parameters:
    events - An iterator returning the events to be submitted.
    
    Returns:
    A map of RoutingStatus return values keyed off the event ID related to the RoutingStatus. One for each event successfully submitted.
  - submitEvents
```
public java.util.Map<java.lang.String,RoutingStatus> submitEvents(java.util.Iterator<? extends Event> events,
                                                         boolean useProcessPendingSchedules)
                                                           throws MultipleEventSubmitException
```
    Submit a collection of events to the solution. Events will be submitted in the order they are provided by the supplied iterator.
    
    Event submission will halt upon the first problem encountered. A map of the RoutingStatus values for all successful event submissions up to the point of the first failure will be attached to the MultipleEventSubmitException thrown as a result of the failure.
    
    Event submission can be optionally synchronized with solution processing. When synchronized, the test client waits for the solution to process previously submitted events, and any processing that is scheduled to take place before the event to be submitted. Even when not synchronized, processing that is scheduled to be processed before or at the time stamp of the event is triggered in chronological order before the event is submitted.
    
    Throws:
    
    MultipleEventSubmitException - If a problem occurs with delivery of one of the events.
    
    java.lang.NullPointerException - If the supplied iterator is null.
    Parameters:
    events - An iterator returning the events to be submitted.
    useProcessPendingSchedules - If true, event submission is synchronized with solution processing.
    
    Returns:
    A map of RoutingStatus return values keyed off the event ID related to the RoutingStatus. One for each event successfully submitted.
  - isRuntimeReady
```
public boolean isRuntimeReady()
```
    test to see if the runtime is available and ready. These required properties must be set: DriverProperties.RUNTIME_HOST_NAME DriverProperties.HTTP_PORT DriverProperties.ADMIN_USERNAME DriverProperties.ADMIN_PASSWORD DriverProperties.TRUSTSTORE_PATH
    
    Throws:
    
    TestDriverException - on error
    
    Returns:
    - true if the CIS server is available and ready, false otherwise.
  - isSolutionReady
```
public boolean isSolutionReady()
```
    Test to see if the current solution is deployed and ready. The current solution is set by a TestDriver property of by using one of the connect methods which require a solution name parameter.
    
    Returns:
    - true if the current solution is deployed and ready, false otherwise
    See Also:
    connect(String name, int timeout ), These required properties must be set: DriverProperties.RUNTIME_HOST_NAME DriverProperties.HTTP_PORT DriverProperties.ADMIN_USERNAME DriverProperties.ADMIN_PASSWORD DriverProperties.TRUSTSTORE_PATH
  - isSolutionReady
```
public boolean isSolutionReady(java.lang.String solutionName)
```
    Test to see if a solution is deployed and ready. These required properties must be set: DriverProperties.RUNTIME_HOST_NAME DriverProperties.HTTP_PORT DriverProperties.ADMIN_USERNAME DriverProperties.ADMIN_PASSWORD DriverProperties.TRUSTSTORE_PATH
    
    Parameters:
    solutionName - the name of the solution to query
    
    Returns:
    true if solutionName is deployed, false otherwise
  - getRuntimeServers
```
public java.util.List<java.lang.String> getRuntimeServers()
```
    returns a list of runtime servers currently running in the grid cluster. You must set the following properties: DriverProperties.RUNTIME_HOST_NAME DriverProperties.HTTP_PORT DriverProperties.ADMIN_USERNAME DriverProperties.ADMIN_PASSWORD DriverProperties.TRUSTSTORE_PATH
    
    Throws:
    
    TestDriverException - on error
    
    Returns:
    a java.util.List of all servers in the grid cluster.
  - getSolutionProperty
```
public java.lang.String getSolutionProperty(java.lang.String propertyName)
```
    retrieves specified solution property. Required set properties are: DriverProperties.RUNTIME_HOST_NAME DriverProperties.HTTP_PORT DriverProperties.ADMIN_USERNAME DriverProperties.ADMIN_PASSWORD DriverProperties.TRUSTSTORE_PATH
    
    Parameters:
    propertyName -
    
    Returns:
    the property value
  - getAgentEvent
```
public Event getAgentEvent(DebugInfo db)
```
    From the debug object, extract the actual event which was submitted by the agent.
    
    Parameters:
    DebugInfo - object
    
    Returns:
    event generated by the agent.
  - getAgentEvent
```
public Event getAgentEvent(DebugInfo db,
                  java.lang.Boolean useXOM)
```
    Parameters:
    DebugInfo - object
    
    Returns:
    event generated by the agent.
  - addDebugReceiver
```
public void addDebugReceiver(DebugReceiver r)
```
    Add a listener to receive DebugInfo objects received by the TestDriver. Listener must implement the DebugReceiver interface. The addDebugInfo method will be called for any registered DebugReceiver.
    
    Parameters:
    listener -
  - removeDebugReceiver
```
public void removeDebugReceiver(DebugReceiver r)
```
    remove a DebugInfo listener. Removes an DebugListener which was previously added.
    
    Parameters:
    listener -
  - getProperties
```
public java.util.Properties getProperties()
```
    get the properties currently defined in the system.
    
    Returns:
    java.util.properties
  - getProperty
```
public java.lang.String getProperty(java.lang.String property,
                           java.lang.String def)
```
    get a String property.
    
    Parameters:
    property - the name of the property to return.
    def - value to return if no property with the given name is currently defined.
  - getProperty
```
public int getProperty(java.lang.String property,
              int def)
```
    get an integer property.
    
    Parameters:
    property - the name of the property to return.
    def - value to return if no property with the given name is currently defined.
  - validateProperties
```
public boolean validateProperties()
```
    Validate the current properties.
    
    Throws:
    
    java.lang.IllegalStateException - if properties are invalid
    
    Returns:
    true if the properties are all valid
  - setProperties
```
public void setProperties(java.util.Properties properties)
```
    Replace all current TestDriver properties with the passed property values.
    
    Parameters:
    properties - the set of properties to use.
  - setProperty
```
public void setProperty(java.lang.String name,
               java.lang.String value)
```
    set a specific TestDriver property.
    
    Parameters:
    name - the name of the property
    value - the value to which the property it set
  - setTestEpoch
```
public boolean setTestEpoch(java.lang.String testEpoch)
                     throws java.time.format.DateTimeParseException,
                            java.lang.IllegalArgumentException
```
    Establish a temporal point of reference to process events with time stamps in the past. For test use only.
    
    Throws:
    
    java.time.format.DateTimeParseException - if the date string is not valid.
    
    java.lang.IllegalArgumentException - if the date string represents a time after the current date and time.
    Parameters:
    testEpoch - an ISO 8601 date and time String representing a point in the past to establish as the epoch for a sequence of test events.
    
    Returns:
    true if the test epoch property was set, false if not.
    See Also:
    TEST_EPOCH_PROPERTY
  - clearTestEpoch
```
public boolean clearTestEpoch()
```
    Clears the value of the test epoch property.
    
    Returns:
    true if the test epoch property was cleared, false if not.
    See Also:
    TEST_EPOCH_PROPERTY
  - getProductId
```
public java.lang.String getProductId()
```
    get the name and version of the product
    
    Throws:
    
    TestDriverException - on error
    
    Returns:
    String value representing the product name and version
  - resetSolutionState
```
public boolean resetSolutionState()
```
    reset the state (clear history) of the current solution. The state includes the rule agent history, cached engines, time triggers, pending events, global aggregates and solution recordings
    
    Throws:
    
    TestDriverException - on error
    
    Returns:
    true if success, false otherwise
  - waitUntilSolutionIdle
```
public boolean waitUntilSolutionIdle(int maxWaitSeconds)
```
    Query the DSI runtime cluster-wide whether there are zero events being processed for the current solution. If there are no events being processed then the call will return true immediately, otherwise it will wait for up to maxWaitSeconds for the number of events being processed in the system to drop to zero, then return true. After maxWaitSeconds if the system has not dropped to zero events it will return false. maxWaitSeconds should not be greater than the http_timeout property value.
    
    Parameters:
    maxWaitSeconds - the maximum number of seconds to wait for the number of events being processed to become zero. The minimum number of seconds to wait is 1
    
    Returns:
    true if the number of events being processed is zero at any time during the maxWaitSeconds period, false otherwise
  - waitUntilSolutionIdle
```
public boolean waitUntilSolutionIdle()
```
    Query the DSI runtime cluster-wide whether there are zero events being processed for the current solution. If there are no events being processed then the call will return true immediately, otherwise it will wait for the number of events being processed in the system to drop to zero, then return true. If the system has not dropped to zero events within a predetermined time out (based on the http_timeout property value) it will return false.
    
    Returns:
    true if the number of events being processed is zero within the predetermined time out.
  - startRecording
```
public java.lang.String startRecording()
```
    Start a debug recording on the latest version of the current solution. The results of any events processed after the recording has started will be captured. Then the results can be viewed in the web-based debug tool after the recording is stopped using the method stopRecording. Typically, this method is called inside a @Test method of your unit test class. An example is as follows:
```
 
                public class AJUnitClient {
                        private TestDriver testDriver = null;

                        @Before
                        public void setUp() throws Exception {
                                testDriver = new TestDriver();
                                testDriver.connect();
                        }

                        @Test
                        public void testFlightMove() throws Exception {
                                testDriver.startRecording();
                                ...
                                // submit event here
                                ...
                                testDriver.stopRecording();
                        }
 
 
```
    You may also span the recording across multiple @Test, or call this method in @BeforeClass, and stopRecording in @AfterClass. However, take note that only one recording per solution is allowed. So, if you have several @Test in your unit test class, and you call the two methods in @Before and @After, respectively, only the last @Test ran will have recording data. Also, whenever startRecording() is called, any currently active recording will be stopped before a new recording starts. If the recording is successfully started, a message looks like one below will be logged.
```
 [08/06/2014 12:07:28] [.] ::INFO:: startRecording was called at com.ibm.ia.runtime.test.HelloWorldRuleAgentTest.sendRuleAgentSingleEvent(HelloWorldRuleAgentTest.java:47)
 [08/06/2014 12:07:39] [.] ::INFO:: Debug recording started. [SolutionVersion: hello_world, Author: tester, Recording id: hello_world-0.1|2014-08-06T12:07:39.844-0400]
 
 
```
    If the recording cannot be started, check log for reason. An example of the possible cause.
```
 [08/06/2014 11:59:02] [.] ::SEVERE:: Error occurred when starting recording. [SolutionVersion: hello_world_bad, Author: tester]. Message: Not Found
 
 
```
    Throws:
    
    TestDriverException - on error
    
    Returns:
    the recording id
  - stopRecording
```
public boolean stopRecording()
```
    Stop the active debug recording on the current solution, after which the results of events processed can be viewed in the web-based debug tool. See startRecording for example use. If the recording is successfully stopped, a message like below will be logged.
```
 [8/6/14 12:30:23:064 EDT] 00000001 TestDriver    I   stopRecording() was called at com.ibm.ia.runtime.test.HelloWorldRuleAgentTest.sendRuleAgentMultipleEvents(HelloWorldRuleAgentTest.java:60)
 [8/6/14 12:30:25:947 EDT] 00000001 TestDriver    I   Recording stopped [solution name: hello_world, recording id: hello_world-0.1|2014-08-06T12:26:06.917-0400]
 
 
```
    If the recording cannot be stopped, check log for reason. An example of the possible cause:
```
 [08/02/2014 12:38:54] [.] ::SEVERE:: Error occurred when stopping recording. [Solution name: hello_world]. Message: CWMBD0135I:  There is no active recording for solution hello_world to stop.
 
 
```
    Throws:
    
    TestDriverException - on error
    
    Returns:
    true is the recording is stopped; otherwise, false

Methods inherited from class java.lang.Object

Methods inherited from interface com.ibm.ia.testdriver.DebugReceiver

ALL_AGENTS

MAX_EVENT_SUBMIT_DELAY

TEST_EPOCH_PROPERTY

TestDriver

TestDriver

connect

connect

connect

connect

disconnect

getSolutionName

fetchEntity

loadEntity

loadEntities

loadEntities

updateEntity

deleteEntity

deleteAllEntities

deleteAllEntities

endTest

processPendingSchedules

processPendingSchedules

toXMLString

toXMLBytes

getSolutionGateway

setGatewayMaxSubmitDelay

getEventFactory

getConceptFactory

getModelSerializer

createRelationship

createRelationship

createFileEntitySource

createFileEntitySource

createFileEntitySource

createFileEventSource

createFileEventSource

createFileEventSource

submitEvent

submitEvents

submitEvents

isRuntimeReady

isSolutionReady

isSolutionReady

getRuntimeServers

getSolutionProperty

getAgentEvent

getAgentEvent

addDebugReceiver

removeDebugReceiver

getProperties

getProperty

getProperty

validateProperties

setProperties

setProperty

setTestEpoch

clearTestEpoch

getProductId

resetSolutionState

waitUntilSolutionIdle

waitUntilSolutionIdle

startRecording

stopRecording