Package the Model

After implementing a Digital Twin model, a ZIP archive containing the model JARs, dependencies, and the scaleoutPackage.json can be deployed through the ScaleOut Active Caching UI. This ZIP archive is referred to as the ModulePackage

Digital Twin Dependencies

Digital Twin Clients should reference the com.scaleoutsoftware.digitaltwin:digitaltwin-client library.

<dependency>
    <groupId>com.scaleoutsoftware.digitaltwin</groupId>
    <artifactId>digitaltwin-client</artifactId>
    <version>3.0.0</version>
</dependency>

implementation group: 'com.scaleoutsoftware.digitaltwin', name: 'digitaltwin-client', version: '3.0.0'

implementation group: 'com.scaleoutsoftware.digitaltwin:digitaltwin-client:3.0.0'

implementation("com.scaleoutsoftware.digitaltwin:digitaltwin-client:3.0.0")

Digital Twin models (ScaleOut Module Packages) should reference the com.scaleoutsoftware.modules:modules-hosting library.

<dependency>
    <groupId>com.scaleoutsoftware.modules</groupId>
    <artifactId>modules-hosting</artifactId>
    <version>3.0.0</version>
</dependency>

implementation group: 'com.scaleoutsoftware.modules', name: 'modules-hosting', version: '3.0.0'

implementation group: 'com.scaleoutsoftware.modules:modules-hosting:3.0.0'

implementation("com.scaleoutsoftware.modules:modules-hosting:3.0.0")

Digital Twin Model Entry Point

The DigitalTwin service uses the digital twin model’s defined entry point to launch the model. The scaleout-realtime-digitaltwin and scaleout-simulation-digitaltwin archetypes generate an entry point that does not require any additional configuration. The generated entry point is available in the src/main/packageDirs/Main.java.

The following is an example from the Thermostat sample:

ModulePackage modulePackage = new ModulePackage();
// define the DigitalTwinModelOptions
DigitalTwinModelOptions<RealTimeThermostat> digitalTwinModelOptions = new DigitalTwinModelOptionsBuilder<RealTimeThermostat>(RealTimeThermostat.class).build();
// add the Digital Twin model to the package
modulePackage.addDigitalTwinModel("RealTimeThermostat", new RealTimeThermostatMessageProcessor(), digitalTwinModelOptions);
try {
    // wait for events
    modulePackage.waitForEvents();
} catch (ModuleRegistrationException e) {
    throw new RuntimeException(e);
} catch (Exception e) {
    throw new RuntimeException(e);
}

Notably, the entry point is responsible for the following:

Instantiating the ModulePackage.
Instantiating the ModuleOptions.
Adding the user-created digital twin model to the ModulePackage
Calling waitForEvents() on the ModulePackage instance.

Testing a Twin Locally

You can use the workbench to deploy your model locally, send messages, and debug the working model. The Workbench APIs are open source and available on Maven and GitHub.

scaleoutPackage.json

The scaleoutPackage.json metadata file is used to describe the digital twin model. The fields are:

Property	Description
`modules`	An array of Modules (see below)
`cmdLineParams`	The entry point into the Module

Module JSON definition

Property	Description
`moduleName`	The digital twin model name
`runtime`	java or dotnet
`moduleType`	dt

Adding Automatic Module Packaging to Maven Projects

The following package plugins will allow your Maven project to generate a ZIP archive for deployment. This task relies on the scaleoutPackage.json configuration file to be created/configured and then placed in the src/main/resources directory.

Begin by creating deployment.xml in the src\assembly directory (create the assembly directory if it does not already exist) with the following contents:

<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3 https://maven.apache.org/xsd/assembly-1.1.3.xsd">
    <id>deployment</id>
    <formats>
        <format>zip</format>
    </formats>
    <includeBaseDirectory>false</includeBaseDirectory>
    <fileSets>
        <!-- Compiled JAR -->
        <fileSet>
            <directory>${project.build.directory}</directory>
            <includes>
                <include>${project.build.finalName}.jar</include>
            </includes>
        </fileSet>

        <!-- Dependencies -->
        <fileSet>
            <directory>${project.build.directory}/dependency-jars</directory>
            <includes>
                <include>*.jar</include>
            </includes>
        </fileSet>

        <!-- scaleoutPackage.json -->
        <fileSet>
            <directory>src/main/resources</directory>
            <includes>
                <include>scaleoutPackage.json</include>
            </includes>
        </fileSet>
    </fileSets>
</assembly>

Next, add the following plugins to the project’s pom.xml under the <build><plugins> tag:

<!-- other plugins above... -->
<plugin>
  <artifactId>maven-assembly-plugin</artifactId>
  <version>3.6.0</version>
  <executions>
    <execution>
      <id>make-zip</id>
      <phase>package</phase>
      <goals>
        <goal>single</goal>
      </goals>
      <configuration>
        <finalName>${project.artifactId}</finalName>
        <appendAssemblyId>false</appendAssemblyId>
        <descriptors>
          <descriptor>src/assembly/deployment.xml</descriptor>
        </descriptors>
      </configuration>
    </execution>
  </executions>
</plugin>
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-dependency-plugin</artifactId>
  <version>3.6.0</version>
  <executions>
    <execution>
      <id>copy-dependencies</id>
      <phase>package</phase>
      <goals>
        <goal>copy-dependencies</goal>
      </goals>
      <configuration>
        <outputDirectory>${project.build.directory}/dependency-jars</outputDirectory>
        <includeScope>runtime</includeScope>
      </configuration>
    </execution>
  </executions>
</plugin>
<!-- other plugins below... -->

Now run the following:

mvn package

Adding Automatic Module Packaging to Gradle Projects

The following packageForDeployment ZIP task will generate a package for Gradle projects. This task relies on the scaleoutPackage.json configuration file to be created/configured and then placed in the src/main/resources directory. Add the following to your Gradle build:

tasks.register('packageForDeployment', Zip) {
    group = 'distribution'
    description = 'Packages build output, dependencies, and scaleoutPackage.json into a deployable ZIP'

    // The output zip will be named like: project-name.zip
    archiveFileName = "${project.name}.zip"
    destinationDirectory = layout.buildDirectory.dir("deployment")

    // Include the compiled JAR
    from(jar) {
        into('')
    }

    // Include all runtime dependencies (flattened)
    from(configurations.runtimeClasspath) {
        into('')
        // Optional: filter to include only JARs
        include '*.jar'
    }

    // Include scaleoutPackage.json from resources
    from('src/main/resources') {
        include 'scaleoutPackage.json'
        into('')
    }

    // Fail the build if scaleoutPackage.json is missing
    doFirst {
        def scaleoutPackageFile = file('src/main/resources/scaleoutPackage.json')
        if (!scaleoutPackageFile.exists()) {
            throw new GradleException("Missing required file: src/main/resources/scaleoutPackage.json")
        }
    }
}

tasks.register<Zip>("packageForDeployment") {
    group = "distribution"
    description = "Packages build output, dependencies, and scaleoutPackage.json into a deployable ZIP"

    archiveFileName.set("${project.name}.zip")
    destinationDirectory.set(layout.buildDirectory.dir("deployment"))

    // Include compiled JAR
    from(tasks.named("jar")) {
        into("")
    }

    // Include runtime dependencies
    from(configurations.runtimeClasspath) {
        into("")
        include("*.jar")
    }

    // Include scaleoutPackage from resources
    from("src/main/resources") {
        include("scaleoutPackage")
        into("")
    }

    // Fail if scaleoutPackage is missing
    doFirst {
        val scaleoutPackageFile = file("src/main/resources/scaleoutPackage.json")
        if (!scaleoutPackageFile.exists()) {
            throw GradleException("Missing required file: src/main/resources/scaleoutPackage.json")
        }
    }
}

Then run the following to generate the YourProjectName.zip ZIP package in the project’s build/deployment/ directory.

./gradlew clean build packageForDeployment

.\gradlew.bat clean build packageForDeployment

ModulePackage ZIP Archive

After implementing a digital twin model, a ZIP archive containing the model JARs, dependencies, and the scaleoutPackage.json can be deployed to the ScaleOut digital twin service.

You can generate the deployable ZIP archive through your build tool by packaging the scaleoutPackage.json, the project artifact, and the project’s dependencies. Alternatively, if using a different java build tool you can manually create the module package ZIP archive. To do this, collect the java project’s build output as a JAR, the dependency JARs, the scaleoutPackage.json configuration file, and compress them into a ZIP archive.

The sequence for creating the model package ZIP archive is as follows:

Compile model classes
JAR model classes
Copy build output into a common directory, i.e. _MyTwin_
Copy all dependencies of model classes into the _MyTwin_ directory
Copy scaleoutPackage.json into _MyTwin_ directory

The _MyTwin_ directory structure should now appear as follows:

    MyTwin
|
 \
  scaleoutPackage.json
  MyModel-1.0.jar
  modules-hosting-3.0.0.jar
  ... more dependencies ...

ZIP the _contents_ of the MyTwin directory. Now the scaleout module package can be uploaded to the ScaleOut digital twin service.

API Javadoc

API javadoc is available on the ScaleOut Software website.