Package de.gebit.integrity.runner

## Class TestModel

- java.lang.Object
- - de.gebit.integrity.runner.TestModel

-     public class TestModel
      extends Object

  The test model. There's not much more to say ;-)
  Author:
    Rene Schneider - initial API and implementation

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected Set<AmbiguousDefinition>` | `ambiguousDefinitions` | Ambiguous definitions which are found during variable/suite/etc.
    `protected Map<String,​CallDefinition>` | `callMap` | Call names -> Calls.
    `protected TreeSet<ConstantDefinition>` | `constantDefinitionsInPackages` | Stores an ordered list of global constant definitions.
    `protected Map<String,​AmbiguousDefinition>` | `duplicateMap` | This map is used to find duplicates which then end up in `ambiguousDefinitions`.
    `protected Map<String,​ForkDefinition>` | `forkMap` | Fork names -> Forks.
    `protected com.google.inject.Injector` | `injector` | The Google Guice Injector.
    `protected List<InMemoryTestResourceProvider>` | `inMemoryResourceProviders` | This list stores copies of the `loadedResourceProviders` which refer to resources which have been fully loaded in memory.
    `protected List<TestResourceProvider>` | `loadedResourceProviders` | All resource providers that this model has been filled from.
    `protected Queue<TestResource>` | `loadedResources` | All successfully loaded resources, in the order in which they were loaded.
    `protected static int` | `MAX_SCRIPT_COUNT_AUTO_VERBOSE_LOADING` | The maximum number of scripts which are always loaded in "verbose" mode.
    `protected List<Model>` | `models` | All models.
    `protected ModelSourceExplorer` | `modelSourceExplorer` | The model source explorer.
    `protected static int` | `MULTITHREADED_SECTIONS_THREAD_COUNT_DEFAULT_MAX` | The maximum of multithreaded threads if default determination is used.
    `protected static String` | `MULTITHREADED_SECTIONS_THREAD_COUNT_PROPERTY` | The system property that allows to override the number of threads used to do some time-critical sections in the test runner, such as defining constants and variables.
    `protected TestRunnerPerformanceLogger` | `performanceLogger` | The performance logger.
    `static String` | `PRINT_ALL_LOADED_SCRIPTS_PROPERTY` | Set this system property to turn on verbose script loading.
    `protected Object` | `resourceLoadingSyncObject` | This sync object is used to synchronize access to `XtextResourceFactory`, `XtextResource` and `XtextResourceSet`.
    `protected Object` | `statusOutputSyncObject` | Used to synchronize potential printouts - printing to stdout with multiple threads can quickly lead to chaos.
    `protected Map<String,​SuiteDefinition>` | `suiteMap` | Suite names -> Suites.
    `protected Map<String,​TestDefinition>` | `testMap` | Test names -> Tests.
    `protected Map<String,​VariableOrConstantEntity>` | `variableAndConstantMap` | Variable/constant names -> Entities.
    `protected Map<VariableOrConstantEntity,​String>` | `variableAndConstantReverseMap` | The reverse of `variableAndConstantMap`.
    `protected TreeSet<VariableDefinition>` | `variableDefinitionsInPackages` | Stores an ordered list of global variable definitions.
    `protected Map<String,​VariantDefinition>` | `variantMap` | Variant names -> Variants.
    `protected boolean` | `verboseScriptLoading` | Whether to load scripts in a verbose fashion (=printing every load).

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `TestModel()` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addIntegrityScriptModel​(Model aModel)` | Adds a given Integrity script file to the test model.
    `void` | `addIntegrityScriptModels​(List<Model> someModels)` | Adds all given Integrity script files to the test model.
    `protected List<Diagnostic>` | `customValidateSingleModel​(Model aModel)` | Performs validation of a single model.
    `Collection<CallDefinition>` | `getAllCalls()` | Returns all calls in the test model.
    `Collection<ForkDefinition>` | `getAllForks()` | Returns all forks in the test model.
    `Collection<SuiteDefinition>` | `getAllSuites()` | Returns all suites in the test model.
    `Collection<TestDefinition>` | `getAllTests()` | Returns all tests in the test model.
    `Collection<VariantDefinition>` | `getAllVariants()` |
    `CallDefinition` | `getCallByName​(String aFullyQualifiedCallName)` | Resolves a fully qualified call name to the actual call definition.
    `TreeSet<ConstantDefinition>` | `getConstantDefinitionsInPackages()` | Iterates through the whole model and searches for constant definitions.
    `Set<AmbiguousDefinition>` | `getDuplicateDefinitions()` |
    `ForkDefinition` | `getForkByName​(String aFullyQualifiedForkName)` | Resolves a fully qualified fork name to the actual fork definition.
    `String` | `getFullyQualifiedVariableOrConstantName​(VariableOrConstantEntity anEntity)` | Returns the fully-qualified name of a variable/constant entity.
    `com.google.inject.Injector` | `getInjector()` |
    `List<InMemoryTestResourceProvider>` | `getInMemoryResourceProviders()` | Returns a list of duplicates of all resource providers ever used to load test scripts into this `TestModel`.
    `List<TestResourceProvider>` | `getLoadedResourceProviders()` |
    `List<TestResource>` | `getLoadedResources()` |
    `List<Model>` | `getModels()` |
    `int` | `getMultithreadedSectionsThreadCount()` | Returns the number of threads to use during multithreaded sections, such as defining constants and variables.
    `protected int` | `getMultithreadedSectionsThreadCountDefault()` | Returns the default number of threads to use during multithreaded sections, such as defining constants and variables.
    `SuiteDefinition` | `getSuiteByName​(String aFullyQualifiedSuiteName)` | Resolves a fully qualified suite name to the actual suite definition.
    `TestDefinition` | `getTestByName​(String aFullyQualifiedTestName)` | Resolves a fully qualified test name to the actual test definition.
    `TreeSet<VariableDefinition>` | `getVariableDefinitionsInPackages()` | Iterates through the whole model and searches for variable definitions hosted in packages (global variables).
    `VariableOrConstantEntity` | `getVariableOrConstantByName​(String aFullyQualifiedName)` | Resolves a fully qualified variable/constant name to the actual entity.
    `VariantDefinition` | `getVariantByName​(String aFullyQualifiedVariantName)` | Resolves a fully qualified variant name to the actual variant definition.
    `TestRunner` | `initializeTestRunner​(TestRunnerCallback aCallback, Map<String,​String> someParameterizedConstants, String aResultLocale, Integer aRemotingPort, String aRemotingBindHost, Long aRandomSeed, String[] someCommandLineArguments)` | Initializes a fresh test runner instance, based on this test model.
    `static TestModel` | `instantiateTestModel​(ClassLoader aClassLoader, Class<? extends IntegrityDSLSetup> aSetupClass, boolean aSkipModelChecksFlag)` | Instantiates a TestModel using the provided setup class.
    `protected List<Diagnostic>` | `loadSingleResource​(TestResourceProvider aResourceProvider, TestResource aResourceName, org.eclipse.xtext.resource.XtextResourceSet aResourceSet, org.eclipse.xtext.resource.IResourceFactory aResourceFactory, boolean aVerboseFlag)` | Loads a single `TestResource` from the given `TestResourceProvider`.
    `static TestModel` | `loadTestModel​(TestResourceProvider aResourceProvider, boolean aSkipModelChecksFlag, boolean aPerformModelValidationFlag, Class<? extends IntegrityDSLSetup> aSetupClass)` | Loads a `TestModel` from a given `TestResourceProvider`.
    `List<Diagnostic>` | `readIntegrityScriptFiles​(TestResourceProvider aResourceProvider, boolean aPerformModelValidationFlag)` | Reads all Integrity scripts from the provided resource provider and initializes this test model with them.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### models

          protected List<Model> models

      All models. Every file is a model of itself (though they are all linked, of course).

    - #### suiteMap

          protected Map<String,​SuiteDefinition> suiteMap

      Suite names -> Suites.

    - #### variantMap

          protected Map<String,​VariantDefinition> variantMap

      Variant names -> Variants.

    - #### forkMap

          protected Map<String,​ForkDefinition> forkMap

      Fork names -> Forks.

    - #### callMap

          protected Map<String,​CallDefinition> callMap

      Call names -> Calls.

    - #### testMap

          protected Map<String,​TestDefinition> testMap

      Test names -> Tests.

    - #### variableAndConstantMap

          protected Map<String,​VariableOrConstantEntity> variableAndConstantMap

      Variable/constant names -> Entities.

    - #### variableAndConstantReverseMap

          protected Map<VariableOrConstantEntity,​String> variableAndConstantReverseMap

      The reverse of `variableAndConstantMap`.

    - #### ambiguousDefinitions

          protected Set<AmbiguousDefinition> ambiguousDefinitions

      Ambiguous definitions which are found during variable/suite/etc. indexing are collected here.

    - #### duplicateMap

          protected Map<String,​AmbiguousDefinition> duplicateMap

      This map is used to find duplicates which then end up in `ambiguousDefinitions`.

    - #### constantDefinitionsInPackages

          protected TreeSet<ConstantDefinition> constantDefinitionsInPackages

      Stores an ordered list of global constant definitions. This is intended as a cache - if it's null, it must be recreated.

    - #### variableDefinitionsInPackages

          protected TreeSet<VariableDefinition> variableDefinitionsInPackages

      Stores an ordered list of global variable definitions. This is intended as a cache - if it's null, it must be recreated.

    - #### injector

          @Inject
          protected com.google.inject.Injector injector

      The Google Guice Injector.

    - #### modelSourceExplorer

          @Inject
          protected ModelSourceExplorer modelSourceExplorer

      The model source explorer.

    - #### performanceLogger

          @Inject
          protected TestRunnerPerformanceLogger performanceLogger

      The performance logger.

    - #### loadedResources

          protected Queue<TestResource> loadedResources

      All successfully loaded resources, in the order in which they were loaded.

    - #### loadedResourceProviders

          protected List<TestResourceProvider> loadedResourceProviders

      All resource providers that this model has been filled from.

    - #### inMemoryResourceProviders

          protected List<InMemoryTestResourceProvider> inMemoryResourceProviders

      This list stores copies of the `loadedResourceProviders` which refer to resources which have been fully loaded in memory. It is intended as a cache to avoid repeated duplication of the same `TestResourceProvider`s. If it is null, the cache is empty and must be recreated. If not, it can be used.

    - #### PRINT_ALL_LOADED_SCRIPTS_PROPERTY

          public static final String PRINT_ALL_LOADED_SCRIPTS_PROPERTY

      Set this system property to turn on verbose script loading. This makes Integrity list all scripts that it loads, regardless of the number of scripts being loaded. If this is turned off, only a summary is printed if more than `MAX_SCRIPT_COUNT_AUTO_VERBOSE_LOADING` scripts are being loaded.
      See Also:
        Constant Field Values

    - #### MAX_SCRIPT_COUNT_AUTO_VERBOSE_LOADING

          protected static final int MAX_SCRIPT_COUNT_AUTO_VERBOSE_LOADING

      The maximum number of scripts which are always loaded in "verbose" mode.
      See Also:
        Constant Field Values

    - #### verboseScriptLoading

          protected final boolean verboseScriptLoading

      Whether to load scripts in a verbose fashion (=printing every load).

    - #### MULTITHREADED_SECTIONS_THREAD_COUNT_PROPERTY

          protected static final String MULTITHREADED_SECTIONS_THREAD_COUNT_PROPERTY

      The system property that allows to override the number of threads used to do some time-critical sections in the test runner, such as defining constants and variables.
      See Also:
        Constant Field Values

    - #### MULTITHREADED_SECTIONS_THREAD_COUNT_DEFAULT_MAX

          protected static final int MULTITHREADED_SECTIONS_THREAD_COUNT_DEFAULT_MAX

      The maximum of multithreaded threads if default determination is used. This is not taken into account if a custom number of threads is set via `MULTITHREADED_SECTIONS_THREAD_COUNT_PROPERTY`.
      See Also:
        Constant Field Values

    - #### resourceLoadingSyncObject

          protected Object resourceLoadingSyncObject

      This sync object is used to synchronize access to `XtextResourceFactory`, `XtextResource` and `XtextResourceSet`. I'm not sure if those are parallelizable, so better be safe than sorry.

    - #### statusOutputSyncObject

          protected Object statusOutputSyncObject

      Used to synchronize potential printouts - printing to stdout with multiple threads can quickly lead to chaos.

  - ### Constructor Detail

    - #### TestModel

          public TestModel()

  - ### Method Detail

    - #### getMultithreadedSectionsThreadCount

          public int getMultithreadedSectionsThreadCount()

      Returns the number of threads to use during multithreaded sections, such as defining constants and variables. This public method is located here for practical reasons - the test model and test runner both need this information, but the model needs it first, so I've placed it here.

    - #### getMultithreadedSectionsThreadCountDefault

          protected int getMultithreadedSectionsThreadCountDefault()

      Returns the default number of threads to use during multithreaded sections, such as defining constants and variables.

    - #### addIntegrityScriptModels

          public void addIntegrityScriptModels​(List<Model> someModels)

      Adds all given Integrity script files to the test model.
      Parameters:
        `someModels` - the models to add

    - #### addIntegrityScriptModel

          public void addIntegrityScriptModel​(Model aModel)

      Adds a given Integrity script file to the test model.
      Parameters:
        `aModel` - the model to add

    - #### readIntegrityScriptFiles

          public List<Diagnostic> readIntegrityScriptFiles​(TestResourceProvider aResourceProvider,
                                                           boolean aPerformModelValidationFlag)
                                                    throws ModelLoadException

      Reads all Integrity scripts from the provided resource provider and initializes this test model with them. This is an "additive" operation, meaning that it is possible to call this method on a model multiple times and inject more and more scripts.
      For each successfully loaded resource provider, a reference to the provider is stored in the model as well. The same is done for each successfully loaded resource (see `TestResource`). These references may later be retrieved by `getLoadedResourceProviders()` and `getLoadedResources()`.
      Parameters:
        `aResourceProvider` - the resource provider to use for loading
        `aPerformModelValidationFlag` - whether model validation is to be done
      Returns:
        any errors that happened while loading or validating
      Throws:
        `ModelLoadException`

    - #### loadSingleResource

          protected List<Diagnostic> loadSingleResource​(TestResourceProvider aResourceProvider,
                                                        TestResource aResourceName,
                                                        org.eclipse.xtext.resource.XtextResourceSet aResourceSet,
                                                        org.eclipse.xtext.resource.IResourceFactory aResourceFactory,
                                                        boolean aVerboseFlag)
                                                 throws ModelLoadException

      Loads a single `TestResource` from the given `TestResourceProvider`. This method is deliberately designed to be thread-safe and shall be invoked in parallel for parallelized script loading.
      Parameters:
        `aResourceProvider` - the resource provider to load from
        `aResourceName` - the resource to load
        `aResourceSet` - the resource set to add the resource to
        `aResourceFactory` - the resource factory to use
        `aVerboseFlag` - whether to make verbose output
      Returns:
        a list of errors
      Throws:
        `ModelLoadException`

    - #### customValidateSingleModel

          protected List<Diagnostic> customValidateSingleModel​(Model aModel)

      Performs validation of a single model. THIS IS NOT THREAD-SAFE, as the model is being lazy-resolved during validation, which may trigger modifications to other models' internal structures.
      Parameters:
        `aModel` - the model to validate
      Returns:
        a list of validation errors (only errors are reported)

    - #### getInjector

          public com.google.inject.Injector getInjector()

    - #### getModels

          public List<Model> getModels()

    - #### getLoadedResources

          public List<TestResource> getLoadedResources()

    - #### getLoadedResourceProviders

          public List<TestResourceProvider> getLoadedResourceProviders()

    - #### getDuplicateDefinitions

          public Set<AmbiguousDefinition> getDuplicateDefinitions()

    - #### getSuiteByName

          public SuiteDefinition getSuiteByName​(String aFullyQualifiedSuiteName)

      Resolves a fully qualified suite name to the actual suite definition.
      Parameters:
        `aFullyQualifiedSuiteName` - the suite name
      Returns:
        the suite, or null if none was found

    - #### getAllSuites

          public Collection<SuiteDefinition> getAllSuites()

      Returns all suites in the test model.
      Returns:
        all suites

    - #### getVariantByName

          public VariantDefinition getVariantByName​(String aFullyQualifiedVariantName)

      Resolves a fully qualified variant name to the actual variant definition.
      Parameters:
        `aFullyQualifiedVariantName` - the variant name
      Returns:
        the variant, or null if none was found

    - #### getAllVariants

          public Collection<VariantDefinition> getAllVariants()

    - #### getForkByName

          public ForkDefinition getForkByName​(String aFullyQualifiedForkName)

      Resolves a fully qualified fork name to the actual fork definition.
      Parameters:
        `aFullyQualifiedForkName` - the fork name
      Returns:
        the fork, or null if none was found

    - #### getAllForks

          public Collection<ForkDefinition> getAllForks()

      Returns all forks in the test model.
      Returns:
        all forks

    - #### getCallByName

          public CallDefinition getCallByName​(String aFullyQualifiedCallName)

      Resolves a fully qualified call name to the actual call definition.
      Parameters:
        `aFullyQualifiedCallName` - the call name
      Returns:
        the call definition, or null if none was found

    - #### getAllCalls

          public Collection<CallDefinition> getAllCalls()

      Returns all calls in the test model.
      Returns:
        all calls

    - #### getTestByName

          public TestDefinition getTestByName​(String aFullyQualifiedTestName)

      Resolves a fully qualified test name to the actual test definition.
      Parameters:
        `aFullyQualifiedTestName` - the call name
      Returns:
        the test definition, or null if none was found

    - #### getAllTests

          public Collection<TestDefinition> getAllTests()

      Returns all tests in the test model.
      Returns:
        all tests

    - #### getVariableOrConstantByName

          public VariableOrConstantEntity getVariableOrConstantByName​(String aFullyQualifiedName)

      Resolves a fully qualified variable/constant name to the actual entity.
      Parameters:
        `aFullyQualifiedName` - the name to resolve
      Returns:
        the entity, or null if none was found

    - #### getFullyQualifiedVariableOrConstantName

          public String getFullyQualifiedVariableOrConstantName​(VariableOrConstantEntity anEntity)

      Returns the fully-qualified name of a variable/constant entity. The stuff returned by this equals `IntegrityDSLUtil.getQualifiedVariableEntityName(VariableOrConstantEntity, boolean)` with the boolean value set to true.
      Parameters:
        `anEntity` - the entity to resolve
      Returns:
        the name, or null if none was found

    - #### getVariableDefinitionsInPackages

          public TreeSet<VariableDefinition> getVariableDefinitionsInPackages()

      Iterates through the whole model and searches for variable definitions hosted in packages (global variables).
      Returns:
        a set of variable definitions (sorted by fully qualified name)

    - #### getConstantDefinitionsInPackages

          public TreeSet<ConstantDefinition> getConstantDefinitionsInPackages()

      Iterates through the whole model and searches for constant definitions.
      Returns:
        a set of constant definitions (sorted by fully qualified name)

    - #### loadTestModel

          public static TestModel loadTestModel​(TestResourceProvider aResourceProvider,
                                                boolean aSkipModelChecksFlag,
                                                boolean aPerformModelValidationFlag,
                                                Class<? extends IntegrityDSLSetup> aSetupClass)
                                         throws ModelLoadException

      Loads a `TestModel` from a given `TestResourceProvider`. During this process, the files provided by the resource provider are parsed, the resulting models are linked and stored in the `TestModel` container.
      Errors, like unresolved symbols, will cause an exception. If a model is returned by this method, you can be sure that everything was linked fine and the model can be executed by the `TestRunner`.
      Parameters:
        `aResourceProvider` - The resource provider to use for loading the test scripts for the model.
        `aSkipModelChecksFlag` - if true, the test runner will skip the model consistency checks it would otherwise perform during the dry run
        `aPerformModelValidationFlag` - if true, the test runner will perform extensive model validation
        `aSetupClass` - the setup class to use for EMF setup and Guice initialization (if null, the default class is used)
      Returns:
        the test model ready for execution
      Throws:
        `ModelLoadException` - if any errors occur during loading (syntax errors or unresolvable references)

    - #### instantiateTestModel

          public static TestModel instantiateTestModel​(ClassLoader aClassLoader,
                                                       Class<? extends IntegrityDSLSetup> aSetupClass,
                                                       boolean aSkipModelChecksFlag)

      Instantiates a TestModel using the provided setup class.
      Parameters:
        `aClassLoader` - the class loader to use for Integrity stuff
        `aSetupClass` - the setup class to use for EMF setup and Guice initialization (if null, the default class is used)
        `aSkipModelChecksFlag` - if true, the test runner will skip the model consistency checks it would otherwise perform during the dry run
      Returns:
        the new (but still empty) test model

    - #### initializeTestRunner

          public TestRunner initializeTestRunner​(TestRunnerCallback aCallback,
                                                 Map<String,​String> someParameterizedConstants,
                                                 String aResultLocale,
                                                 Integer aRemotingPort,
                                                 String aRemotingBindHost,
                                                 Long aRandomSeed,
                                                 String[] someCommandLineArguments)
                                          throws IOException

      Initializes a fresh test runner instance, based on this test model.
      Parameters:
        `aCallback` - the callback to use to report test results
        `someParameterizedConstants` - Maps fully qualified constant names (must be those with the "parameterized" keyword) to their desired value. This way, test execution can be parameterized from outside.
        `aRemotingPort` - the port on which the remoting server should listen, or null if remoting should be disabled
        `aRemotingBindHost` - the host name (or IP) to which the remoting server should bind
        `aRandomSeed` - the seed for the `RandomNumberOperation` (optional; randomly determined if not given).
        `someCommandLineArguments` - all command line arguments as given to the original Java programs' main routine (required for forking!)
      Returns:
        the initialized test runner instance
      Throws:
        `IOException` - if the remoting server startup fails

    - #### getInMemoryResourceProviders

          public List<InMemoryTestResourceProvider> getInMemoryResourceProviders()
                                                                          throws IOException

      Returns a list of duplicates of all resource providers ever used to load test scripts into this `TestModel`. These duplicates are instances of `InMemoryTestResourceProvider`, meaning they contain the whole script data inside their instances, so nothing has to be loaded from the file system or other sources anymore. They also are transferable via Serialization, so they can be used to initialize Forks, which is their primary use!
      Returns:
        duplicates of the used resource providers
      Throws:
        `IOException` - in case of errors during duplication