ModelVersioningAssistant (JSIT 0.2 API Documentation)

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

Direct Known Subclasses:

ModelVersioningAssistantNoVCS, ModelVersioningAssistantSVN
```
public abstract class ModelVersioningAssistant
extends java.lang.Object
```
Abstract utility class to be able to programmatically store and check information about the version of simulation model code, integrating with a version control system (VCS) and commit process. VCS-specific subclasses are instantiated by the static factory method createAssistant.
This class should be used in two places:

(i) To do commits of model material. This *replaces* the normal commit process, and is typically run via a batch file in the root model directory. (The commit is always being done for the current directory ".".) The change comments should always be in a local file called workingChanges.txt, which will be renamed to lastCommitChanges.txt on a successful commit. The main entry point and commitModelMaterial method handles this.

(ii) When running a model, to check which version is running and log this information for traceability and experiment replication. The various public get methods handle this, returning appropriate strings.
In both cases, the directories forming the in-VCS simulation code (ideally separated from experiments) are passed to the factory method.
Information on the model version is stored in a model version XML file within a sim code directory. The user sets a model name, version number and VCS used (currently NONE or SVN) manually, but every other entry is set automatically by this tool (and entries will differ per-VCS).
To be able to check whether model code has changed locally from the version checked-out or exported from the VCS, we store MD5 hashes of the model source files in the version file, updated automatically at commit time.

Since:

0.1

Author:

Stuart Rossiter

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class ModelVersioningAssistant.VersionControlSystem
Version control system (VCS) alternatives supported by this tool.

Nested Classes
Modifier and Type	Class and Description
`static class`	`ModelVersioningAssistant.VersionControlSystem` Version control system (VCS) alternatives supported by this tool.

Field Summary

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`COMMIT_TIME_PROPERTY`
`static java.lang.String`	`MODEL_NAME_PROPERTY`
`static java.lang.String`	`MODEL_REV_PROPERTY`
`static java.lang.String`	`MODEL_SOURCE_PATHS_FILE_NAME`
`static java.lang.String`	`MODEL_VER_PROPERTY`
`static java.lang.String`	`PREV_CHANGES_FILE`
`static java.lang.String`	`SIM_SOURCE_PATH_PROPERTY`
`static java.lang.String`	`SOURCE_DIRS_HASH_PROPERTY`
`static java.lang.String`	`VCS_PROPERTY`
`static java.lang.String`	`VERSION_FILE_DIR_PROPERTY`
`static java.lang.String`	`VERSION_FILE_NAME`
`static java.lang.String`	`VERSION_FILE_REPO_URL_PROPERTY`
`static java.lang.String`	`WORKING_CHANGES_FILE`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`static ModelVersioningAssistant`	`createAssistant(java.lang.String inputsBasePath)` Static factory method to create a model versioning assistant (of a suitable VCS-specific subclass to this one).
`abstract java.lang.String`	`getLastCommitID()` Abstract method to return the last commit ID (where this ID is in a suitable VCS-specific form), as in the model version file.
`java.lang.String`	`getModelCommittedURL()` Returns a URL string for the model code's VCS repository location (derived from that for the model version file in the model version file).
`java.lang.String`	`getModelVCS()` Returns string identifying the VCS being used (as in the model version file).
`java.lang.String`	`getUserModelName()` Returns the user-assigned model name (as in the model version file).
`java.lang.String`	`getUserModelVersion()` Returns the user-set model version (as in the model version file).
`static void`	`main(java.lang.String[] args)` Entry point.
`RunEnvironmentSettings.ModificationStatus`	`simHasLocalModifications()` Returns whether the model's sim code has local modifications from the version checksummed at commit time (as reported in the model version file; this includes not-in-VCS files in those folders).

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

- Field Detail
  - MODEL_SOURCE_PATHS_FILE_NAME
```
public static final java.lang.String MODEL_SOURCE_PATHS_FILE_NAME
```
    See Also:
    
    Constant Field Values
  - VERSION_FILE_NAME
```
public static final java.lang.String VERSION_FILE_NAME
```
    See Also:
    
    Constant Field Values
  - WORKING_CHANGES_FILE
```
public static final java.lang.String WORKING_CHANGES_FILE
```
    See Also:
    
    Constant Field Values
  - PREV_CHANGES_FILE
```
public static final java.lang.String PREV_CHANGES_FILE
```
    See Also:
    
    Constant Field Values
  - MODEL_NAME_PROPERTY
```
public static final java.lang.String MODEL_NAME_PROPERTY
```
    See Also:
    
    Constant Field Values
  - MODEL_VER_PROPERTY
```
public static final java.lang.String MODEL_VER_PROPERTY
```
    See Also:
    
    Constant Field Values
  - VCS_PROPERTY
```
public static final java.lang.String VCS_PROPERTY
```
    See Also:
    
    Constant Field Values
  - VERSION_FILE_DIR_PROPERTY
```
public static final java.lang.String VERSION_FILE_DIR_PROPERTY
```
    See Also:
    
    Constant Field Values
  - SIM_SOURCE_PATH_PROPERTY
```
public static final java.lang.String SIM_SOURCE_PATH_PROPERTY
```
    See Also:
    
    Constant Field Values
  - SOURCE_DIRS_HASH_PROPERTY
```
public static final java.lang.String SOURCE_DIRS_HASH_PROPERTY
```
    See Also:
    
    Constant Field Values
  - VERSION_FILE_REPO_URL_PROPERTY
```
public static final java.lang.String VERSION_FILE_REPO_URL_PROPERTY
```
    See Also:
    
    Constant Field Values
  - MODEL_REV_PROPERTY
```
public static final java.lang.String MODEL_REV_PROPERTY
```
    See Also:
    
    Constant Field Values
  - COMMIT_TIME_PROPERTY
```
public static final java.lang.String COMMIT_TIME_PROPERTY
```
    See Also:
    
    Constant Field Values
- Method Detail
  - main
```
public static void main(java.lang.String[] args)
```
    Entry point. Only used to commit model code.
    
    Parameters:
    
    args - Command-line parameters. Should be COMMIT and the under-VC sim code path. The model version file modelVersion.xml should be in one of the directories on the under-VC sim code path.
    
    Since:
    
    0.1
  - createAssistant
```
public static ModelVersioningAssistant createAssistant(java.lang.String inputsBasePath)
```
    Static factory method to create a model versioning assistant (of a suitable VCS-specific subclass to this one). The ModelVCS setting in the required model version file is used to determine what is needed.
    
    Parameters:
    
    inputsBasePath - Path to the inputs directory. A modelPath.properties file should exist there with a ModelPath property therein which gives the path to the main model code directory (where the modelVersion.xml file can be found). If the model path file does not exist, a path of "." (i.e. the current working directory) is assumed for the model code.
    
    Returns:
    
    A suitable subclass of ModelVersioningAssistant.
    
    Since:
    
    0.1
  - getLastCommitID
```
public abstract java.lang.String getLastCommitID()
```
    Abstract method to return the last commit ID (where this ID is in a suitable VCS-specific form), as in the model version file.
    
    Returns:
    
    The last commit ID.
    
    Since:
    
    0.1
  - getUserModelName
```
public java.lang.String getUserModelName()
```
    Returns the user-assigned model name (as in the model version file).
    
    Returns:
    
    The user model name.
    
    Since:
    
    0.1
  - getModelVCS
```
public java.lang.String getModelVCS()
```
    Returns string identifying the VCS being used (as in the model version file).
    
    Returns:
    
    The VCS-identifying string.
    
    Since:
    
    0.1
  - getModelCommittedURL
```
public java.lang.String getModelCommittedURL()
```
    Returns a URL string for the model code's VCS repository location (derived from that for the model version file in the model version file).
    
    Returns:
    
    URL string for the model's repository location.
    
    Since:
    
    0.1
  - simHasLocalModifications
```
public RunEnvironmentSettings.ModificationStatus simHasLocalModifications()
```
    Returns whether the model's sim code has local modifications from the version checksummed at commit time (as reported in the model version file; this includes not-in-VCS files in those folders).
    
    Returns:
    
    A ModificationStatus value as used by RunEnvironmentSettings (and included in the model settings file).
    
    Since:
    
    0.1
  - getUserModelVersion
```
public java.lang.String getUserModelVersion()
```
    Returns the user-set model version (as in the model version file).
    
    Returns:
    
    The user-set model version string.
    
    Since:
    
    0.1

Class ModelVersioningAssistant

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

MODEL_SOURCE_PATHS_FILE_NAME

VERSION_FILE_NAME

WORKING_CHANGES_FILE

PREV_CHANGES_FILE

MODEL_NAME_PROPERTY

MODEL_VER_PROPERTY

VCS_PROPERTY

VERSION_FILE_DIR_PROPERTY

SIM_SOURCE_PATH_PROPERTY

SOURCE_DIRS_HASH_PROPERTY

VERSION_FILE_REPO_URL_PROPERTY

MODEL_REV_PROPERTY

COMMIT_TIME_PROPERTY

Method Detail

main

createAssistant

getLastCommitID

getUserModelName

getModelVCS

getModelCommittedURL

simHasLocalModifications

getUserModelVersion