The Ostara Service is a JAX-RS 2.0 compliant service that orchestrates platform upgrade flows.

It is intended as a generic and pluggable design to accommodate multiple upgrade flow variations. In its current implementation it ships with integration with Git repositories hosted on GitHub deployments (both open-source and enterprise). It is also delegating the application upgrade operation to the [Ostara Upgrade module].

The service chains together commands to accomplish the upgrade operations. Each command performs atomic operations based on the input parameters.

The build-in commands that make use of GitHub read their configuration from the service's Config class. By default this class gets populated at startup from the ostara.properties file.

This can be overridden by third parties. The recommended override mechanism is to call TaskServiceInitializer.init(InputStream) with the stream to the custom property file.

The chaining of commands is configured in a JSON file. The service ships with a reference upgradetask.json configuration which can be customized by third parties.

The structure of the JSON file follows the following pattern:

{
 "name": "name-of-task",
 "commands": [
  {"name":"command1", "commandClass":"org.ostara.cmd.impl.Command1"},
  {"name":"command2", "commandClass":"org.ostara.cmd.impl.Command2"}
  ],
 "cmdParameterMapping":{
  "gitfork.gitUrl":"gitUrl","gitfork.organization":"config.organization","gitfork.username":"config.username", "gitfork.password":"config.password",
  "gitclone.gitUrl":"gitfork.forkedGitUrl",
 }

TODO Describe the command parameter mapping

Minimally a command is expected to extend the ICommand interface. For convenience the org.ostara.cmd.BaseCommand class is provided with basic functionality such as storing the name and context of the command.

TODO Describe what the context is used for

Commands may have one or more input parameters, either mandatory or optional. Use the @InParameter annotation with the required flag (defaults to false) to mark fields that will be populated by Ostara upon the invocation of the command.

A number of built-in commands are integrated into Ostara. They can be excluded if needed by providing a custom configuration for Ostara.

1. CmdLineCmd: Executes an arbitrary operating system command line command
2. GitAddCmd: Adds to the Git index the contents of the specified directory.
3. GitBranchCmd: Creates a new local Git branch from an existing one.
4. GitCheckoutCmd: TODO
5. GitCloneCmd: Clones a remote Git repository into a local repository.
6. GitCommitCmd: Commits the Git index to the local Git clone.
7. GitPushCmd: Pushes the local commits to the remote Git repository.
8. GitReleaseVersionCmd: TODO
9. GitForkCmd: Performs a remote fork of the repository in GitHub.
10. GitPullRequestCmd: Creates a pull request in the remote GitHub installation.
11. RestAPICommand: A generic command for RESTful operations.
12. VersionUpgradeCmd: Sample command showcasing a minimal transformation on a Maven POM file.

A convenient way to extend the service is using the overlay feature of the WAR plugin.

This design ensures that the endpoints of Ostara and the extension match yet the extension can reconfigure and extend the behavior of Ostara.

A sample WAR overlay configuration looks like the one described as follows.

Add the Ostara service dependencies to your project. This way you will have visibility of the Ostara Service API and access to the Ostara war file.

        <dependency>        
          <groupId>org.ostara</groupId>
          <artifactId>ostara-service</artifactId>
          <version>0.0.1-SNAPSHOT</version>
          <type>war</type>
          <!-- scope>runtime</scope -->
        </dependency>

        <dependency>        
          <groupId>org.ostara</groupId>
          <artifactId>ostara-service</artifactId>
          <version>0.0.1-SNAPSHOT</version>
          <type>jar</type>
          <classifier>classes</classifier>
        </dependency>

Next ensure that in the build/plugins section you add a similar configuration to the maven-war-plugin:

            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-war-plugin</artifactId>
                <configuration>
                    <warName>ROOT</warName>
                    
                    <workDirectory>target/overlay-war-folder</workDirectory>
                    
                    <overlays>
                      <overlay>
                        <groupId>org.ostara</groupId>
                        <artifactId>ostara-service</artifactId>
                        
                        <excludes>
                          <exclude>WEB-INF/web.xml</exclude>
                        </excludes>
                        
                      </overlay>
                      <overlay>
                        <!-- empty groupId/artifactId represents the current build -->
                      </overlay>
                    </overlays>
                </configuration>
            </plugin>

Using this setup the web.xml of Ostara is excluded and the third party service application can configure the web container to its own liking. Additional exclusions and inclusions can be intermixed as needed.