ModelInitialiser (JSIT 0.2 API Documentation)

java.lang.Object
- uk.ac.soton.simulation.jsit.core.ModelInitialiser

Direct Known Subclasses:

ModelInitialiser_AnyLogic
```
public abstract class ModelInitialiser
extends java.lang.Object
```
Class which sets up the JSIT environment (logging, parameters serialisation and other per-framework and/or per-model environment configuration).
We want to separate logs for each run in multi-run experiments and use the standard way to do this in Logback: use sifting appenders which dynamically create per-run appenders based on an SLF4J MDC key-value pair, where this pair is unique per thread (with the value inherited by child threads). See:
- http://www.slf4j.org/manual.html
- http://logback.qos.ch/manual/appenders.html
Because visualised versions of the model may embed (or extend) unvisualised versions (which can also run standalone), they share a ModelInitialiser instance (created by the parent or superclass MainModel). It is expected that both (as MainModel instances) will want to get the shared instance of this class (see the static factory method).
Typically, single model runs exist in a single thread, and batch runs launch a thread per run therein. However, we have to allow for

(a) runs in a non-parallel multi-run experiment (or single-run ones which can be stopped/ re-run from scratch) being done in the same thread;

(b) models changing thread during their run. (For example, AnyLogic does both of these: (b) when a model is paused and resumed.)
Thus
- MDC keys will exist if a parent initiated this run or (a) above applies. In the first case that is OK; in the other they are not the correct key values for this run.
- MDC keys will vanish in case (b) above.
We handle all this by storing the key values that we set (in the constructor) so that we can compare to these and, in case (b), reapply the MDC keys from the stored values. These keys include one (INIT_MAIN_MODEL_KEY) which is the class name of the MainModel subclass which triggered the instantiation; if this exists and *isn't* the main model class name calling the factory method, we know that a parent already instantiated it and we return that (from our static Hashtable). In case (a) above, we would have the class name of the main model attempting the instantiation.
For case (b), this can only be detected by the (framework-specific) experiment running the model. We provide a method to reapply the stored MDC key values to the new thread, which code in the experiment needs to call at the appropriate time.
Since:

0.1

Author:

Stuart Rossiter

Field Summary

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`EVENT_LOGGER_NAME` 'Domain events' (from event managers) go to this single uniquely-named logger.
`static java.lang.String`	`SETTINGS_FILE` Name for the model run settings file produced.
`static java.lang.String`	`STOCH_CONTROL_FILE` Name for the input stochasticity control file.

Constructor Summary

Constructors
Constructor and Description

ModelInitialiser(java.lang.String experimentName, MainModel modelMain, boolean slf4jBoundToLogback)
Constructor.

Constructors
Constructor and Description
`ModelInitialiser(java.lang.String experimentName, MainModel modelMain, boolean slf4jBoundToLogback)` Constructor.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static void`	`debugThreadInfo(org.slf4j.Logger logger)` Using the Logger provided, produce a debug message showing the current thread and the run ID stored via MDCs.
`void`	`disableStochOverrides()` Disable stochastic overrides (as provided by the stochasticity control file).
`void`	`finaliseStochRegistrations()` Call this when sure that no further stochastic items will be registered, which then allows the per-run settings file to be produced.
`java.lang.String`	`getElapsedTimeSecs()` Get elapsed model processing time in seconds.
`static ModelInitialiser`	`getExistingInitialiser(MainModel modelMain)` Exposed for technical reasons; not intended for JSIT user use.
`static int`	`getJRE_MajorVersionNumber()` Utility method to get the current JRE major version number.
`ch.qos.logback.classic.LoggerContext`	`getLogbackContext()` Get the Logback context for this model.
`java.lang.String`	`getOutputFilesBasePath()` Get the base path for this run's output files.
`java.lang.String`	`getRunID()` Get the JSIT-derived run ID (as used in output folder names).
`boolean`	`isModelInitiator(MainModel modelMain)` Determine whether a main model is the model initialiser or not (since a model may have multiple MainModel instances and only one initiates the JSIT environment, typically the first instantiated).
`void`	`onMainModelDestroy()` Call this when the MainModel is destroyed to clean up statically-held storage for the run.
`void`	`possibleMDC_KeysLoss()` Primarily used internally (and exposed for technical reasons) to restore MDC key values used to associate an active thread with a model run (needed for AnyLogic models due to threading issues).
`Sampler`	`registerStochItem(AbstractStochasticItem stochItem)` Method exposed for technical reasons; not intended for JSIT user use.
`void`	`saveModelSettings()` Save model settings to a file in the output folder.

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

- Field Detail
  - SETTINGS_FILE
```
public static final java.lang.String SETTINGS_FILE
```
    Name for the model run settings file produced.
    
    Since:
    
    0.1
    
    See Also:
    
    Constant Field Values
  - STOCH_CONTROL_FILE
```
public static final java.lang.String STOCH_CONTROL_FILE
```
    Name for the input stochasticity control file.
    
    Since:
    
    0.1
    
    See Also:
    
    Constant Field Values
  - EVENT_LOGGER_NAME
```
public static final java.lang.String EVENT_LOGGER_NAME
```
    'Domain events' (from event managers) go to this single uniquely-named logger.
    
    Since:
    
    0.1
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - ModelInitialiser
```
public ModelInitialiser(java.lang.String experimentName,
                        MainModel modelMain,
                        boolean slf4jBoundToLogback)
```
    Constructor.
    
    Parameters:
    
    experimentName - A string defining the experiment (set of related runs) this model instance is part of. (Used to derive the JSIT run ID.)
    
    modelMain - The MainModel instance that is the 'root' object for the model.
    
    slf4jBoundToLogback - Whether SLF4J is bound to Logback or not. (If not, we need to explicitly initialise Logback ourselves; see later comments.)
    
    Since:
    
    0.1
- Method Detail
  - debugThreadInfo
```
public static void debugThreadInfo(org.slf4j.Logger logger)
```
    Using the Logger provided, produce a debug message showing the current thread and the run ID stored via MDCs. Intended primarily for JSIT debugging.
    
    Parameters:
    
    logger - The Logger to use to log the message. (This must be set to log DEBUG level messages for the message actually be produced.)
    
    Since:
    
    0.1
  - getExistingInitialiser
```
public static ModelInitialiser getExistingInitialiser(MainModel modelMain)
```
    Exposed for technical reasons; not intended for JSIT user use.
    
    Parameters:
    
    modelMain - The MainModel instance that is checking for an existing initialiser.
    
    Returns:
    
    The existing ModelInitialiser (produced by another MainModel) or null if there is no existing one.
    
    Since:
    
    0.1
  - getJRE_MajorVersionNumber
```
public static int getJRE_MajorVersionNumber()
```
    Utility method to get the current JRE major version number.
    
    Returns:
    
    The major version number.
    
    Since:
    
    0.2
  - possibleMDC_KeysLoss
```
public void possibleMDC_KeysLoss()
```
    Primarily used internally (and exposed for technical reasons) to restore MDC key values used to associate an active thread with a model run (needed for AnyLogic models due to threading issues).
    JSIT users may want to call this themselves if there are instances where their model can switch threads for a run (to one that is not a child of the previous one).
    
    Since:
    
    0.2
  - isModelInitiator
```
public boolean isModelInitiator(MainModel modelMain)
```
    Determine whether a main model is the model initialiser or not (since a model may have multiple MainModel instances and only one initiates the JSIT environment, typically the first instantiated).
    This is primarily used internally (and exposed for technical reasons).
    
    Parameters:
    
    modelMain - The MainModel interface to check.
    
    Returns:
    
    Whether the MainModel provided is the model initiator.
    
    Since:
    
    0.1
  - getElapsedTimeSecs
```
public java.lang.String getElapsedTimeSecs()
```
    Get elapsed model processing time in seconds.
    
    Returns:
    
    Elapsed processing time rounded to 2 d.p. (as a String).
    
    Since:
    
    0.1
  - getRunID
```
public java.lang.String getRunID()
```
    Get the JSIT-derived run ID (as used in output folder names).
    
    Returns:
    
    The unique run ID.
    
    Since:
    
    0.1
  - getOutputFilesBasePath
```
public java.lang.String getOutputFilesBasePath()
```
    Get the base path for this run's output files. User subclasses (when not using a helper library) may want to override this.
    
    Returns:
    
    The output files base path (as a String).
    
    Since:
    
    0.1
  - getLogbackContext
```
public ch.qos.logback.classic.LoggerContext getLogbackContext()
```
    Get the Logback context for this model.
    
    Returns:
    
    The context
    
    Since:
    
    0.2
  - saveModelSettings
```
public void saveModelSettings()
                       throws java.io.IOException
```
    Save model settings to a file in the output folder. This sets up the XStream object and calls writeModelSettings (implemented by the subclass) to do the actual writing.
    JSIT users will only need to call this manually if not using a helper library.
    
    Throws:
    
    java.io.IOException - if there are problems creating/writing the output file.
    
    Since:
    
    0.1
  - finaliseStochRegistrations
```
public void finaliseStochRegistrations()
```
    Call this when sure that no further stochastic items will be registered, which then allows the per-run settings file to be produced.
    This will be called as part of the main model destroy processing (onMainModelDestroy method) if the user does not call it earlier.
    
    Since:
    
    0.1
  - onMainModelDestroy
```
public void onMainModelDestroy()
```
    Call this when the MainModel is destroyed to clean up statically-held storage for the run.
    
    Since:
    
    0.1
  - registerStochItem
```
public Sampler registerStochItem(AbstractStochasticItem stochItem)
```
    Method exposed for technical reasons; not intended for JSIT user use.
    Register a dist or lookup, which involves setting its sample mode and checking for double registrations. Returns the sampler so that the caller (a stoch accessor) can register itself and the sampler in the stoch item.
    
    Parameters:
    
    stochItem - The stochastic item to register.
    
    Returns:
    
    The relevant Sampler for that stochastic item to use.
    
    Since:
    
    0.2
  - disableStochOverrides
```
public void disableStochOverrides()
```
    Disable stochastic overrides (as provided by the stochasticity control file). Must be called before registering any stochastic items to be effective. This allows JSIT users to set up a stochasticity control file (used, for example, during testing) but not actually have it used in a 'normal' run.
    
    Since:
    
    0.2

Class ModelInitialiser

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

SETTINGS_FILE

STOCH_CONTROL_FILE

EVENT_LOGGER_NAME

Constructor Detail

ModelInitialiser

Method Detail

debugThreadInfo

getExistingInitialiser

getJRE_MajorVersionNumber

possibleMDC_KeysLoss

isModelInitiator

getElapsedTimeSecs

getRunID

getOutputFilesBasePath

getLogbackContext

saveModelSettings

finaliseStochRegistrations

onMainModelDestroy

registerStochItem

disableStochOverrides