The Corus Descriptor

In the introductory tutorial, you've seen that a so-called Corus descriptor must be packaged as part of a distribution that is meant for deployment into Corus. That descriptor provides the information necessary for a Corus daemon to start applications that are part of the distribution. The descriptor also contains runtime JVM parameters.

How the descriptor is processed

When Corus receives a distribution archive, it first checks if it contains a descriptor - if not, the deployment is denied. If the distribution passes that check, it is unzipped under a specific directory - where all distributions are unzipped.

A directory structure is created for each distribution. That is: Corus uses the information in the descriptor to create directories corresponding to the distribution name and version. The path of a distribution under the Corus deployment directory is as follows: $CORUS_HOME/deploy/<domain_name><port>/<distribution_name><version>. It is in the subdirectory corresponding to that path that a distribution is unzipped, as you you can see.

It is also through the information contained in the descriptor of each distribution that Corus can display the related information to end users (using the ls command).

More on the contents

The really detailed information about the descriptor is in the Corus Guide. We will nevertheless delve into the most important elements here.

First, vocabulary: Corus works mainly with two concepts: "distribution" and "process". This becomes obvious when looking at the Corus descriptor:

<distribution name="basic-sample-jetty" version="1.0" xmlns="http://www.sapia-oss.org/xsd/corus/distribution-5.0.xsd">
  <process  name="server" 
            maxKillRetry="3" 
            shutdownTimeout="30000" 
            invoke="true">
    <java mainClass="org.sapia.corus.sample.jetty.BasicJettyServer"
          profile="dev" vmType="server">
      <xoption  name="ms" value="16M" />
    </java>
    <java mainClass="org.sapia.corus.sample.jetty.BasicJettyServer"
          profile="prod" vmType="server">
      <xoption  name="ms" value="128M" />
    </java>
  </process> 
</distribution>

At the root, the distribution element, which has two attributes:

  • Name: the distribution's arbitrarily chosen name.
  • Version: the distribution's arbitrarily chosen version.

Since there may be multiple versions of a distribution (or, to be more precise: multiple versions of the applications contained in a distribution), it must be assigned a version number that distinguishes from other distributions with the same name - it is also consistent with the common notion that a product evolves in time, and that the different steps in this evolution are identified by a version number.

In turn, under the distribution element, we find process elements. This element defines the configuration of a process instance. At the level of that element itself, we see attributes that pertain to how Corus is to handle the process instances at runtime.

Indeed, each process element is sort of a blueprint for process instances, defining various runtime parameters, as well as the application that's is started in the context of the process instances it describes.

As far as the applications themselves, we can see different java elements under the process element. Each such element holds the configuration that is specific to the JVMs that can be started - only one JVM configuration is chosen when starting the JVM process.

Furthermore, we can see that the java element has a profile attribute. The notion of profile has been introduced to support launching applications according to the environment in which they are deployed. When starting a process using the exec command, we must specify the profile "under" which we want to start the process. Corus thus chooses the JVM configuration whose profile matches the one passed in - if any.

In fact, the exec command mandates that we pass in the information that is necessary for Corus to be able to start a process, according to what we've described above:

  • distribution name: the name of the distribution to which the process belongs.
  • distribution version: the version of the distribution to which the process belongs.
  • process name: the name of the process.
  • profile: the profile under which to start the process.
You can view the full syntax of the exec by typing man exec in the CLI.

Variable Substitution

The descriptor supports the substition of configuration variables expressed in the following format: ${variable_name}

The values for those variables are gathered from:

<distribution name="basic-sample-jetty" version="1.0" xmlns="http://www.sapia-oss.org/xsd/corus/distribution-5.0.xsd">
  <process  name="server" 
            maxKillRetry="3" 
            shutdownTimeout="30000" 
            invoke="true">
    <java mainClass="org.sapia.corus.sample.jetty.BasicJettyServer"
          profile="dev" vmType="server">
      <arg value="-javaagent:${user.dir}/aop/spring-instrument.jar" />
      <xoption  name="ms" value="${dev.xms}" />
      <property name="server.logs.dir" value="${user.dir}/logs" />    
    </java>
    <java mainClass="org.sapia.corus.sample.jetty.BasicJettyServer"
          profile="prod" vmType="server">
      <xoption  name="ms" value="${prod.xms} />
     <property name="server.logs.dir" value="${logs.dir}" />
    </java>
  </process> 
</distribution>