Mock Site Example

From ControlTier

Requires Version: 3.4.3

Note: This document describes how to run the example with Unix. For Windows instructions, see Mock site example for windows.

The Mock Site Example shows the basics of using an object of the Site type, which allows you to dispatch commands to all Service resources organized within the Site.

This example defines two Service objects and groups them beneath one Site object. Commands executed on the Site object are automatically dispatched down to the Services in accordance to their ranking. The ranking is determined by the startuprank property, which is simply a number which orders the Services relative to each other, and is used by the Site commands to determine the order in which the resources should be used. By default for most dispatched commands, ranks are sorted in ascending order except for the Stop command which sorts startup rank values in descending order.

The Service lifecycle commands (see the Service Concepts document for more information) are: Start,Stop, and Status. Each of these commands is also defined in the Site type as a Dispatch command. When you call one of these commands on a Site object, it iterates over each of its Service child dependencies and sends the same command to each Service, in the order determined by the startuprank. This makes it easy to control an entire set of Services using a single command sent to the Site.

The Site Type also has a command named dispatchCmd. You can use this command to send any subcommand to the entire set of Services within the Site. You may have Service resources which have other special-purpose commands that the Site doesn't know about, and you can relay those using the dispatchCmd command in the same way that the Start,Stop, and Status lifecycle commands work automatically.

This Example shows you how to do the following things:

1. Use the Start,Stop, and Status lifecycle commands from a Site, where the commands will be dispatched to the Services
2. Use the dispatchCmd command to dynamically dispatch any named command to the Services for the Site.
3. Use the project.xml resource model format to define a Site object and its related Services

The Example does not define any actual implementation for the lifecycle command scripts. It merely demonstrates how to use the Site to dispatch commands to the Site's Service resources. (For an example on how to implement the lifecycle commands for a Service, see the Mock Unix Service Example or the Windows service example.)

The diagram below describes two Services (mock1 and mock2) grouped within one Site (mock). Notice also each Service resource has its own startuprank value. mock1 has a startuprank of 1, and mock2 has a startuprank of 2:

Site commands normally execute commands in ascending startup rank order. Below you can see "mock1" is first to run "Start" and after that completes, "mock2" runs Start:

The Stop command executes commands in descending startup rank order:

This time "mock2" runs Stop first and once it completes, "mock1" runs Stop.

Dependencies

This has these dependencies.

• ControlTier 3.4.3
  • Meet the prerequisites and install ControlTier according to the Installing ControlTier instructions.
• Linux or Unix based Operating System.
  • For Windows, see: Mock site example for windows.

Building the Example

Follow the instructions in this section to setup the example code into your environment.

Note: Don't worry about what these commands do, as they just bootstrap the example code to work in your environment and to pre-load the resource model for you. (For complete detail about how to use the Examples see Using the Examples):

Execute these bootstrap steps:

1. cd $CTIER_ROOT/examples/mock-site

   • At the command line, navigate to the examples/mock-site directory under your $CTIER_ROOT directory.
2. Edit the file: templates/defaults.xml (optional)
   • Examine and possibly modify the templates/defaults.xml file to contain suitable node name values.

3. ctl -p demo -m ProjectBuilder -c Register -- -xml projectbuilder.xml -install

   • This loads a ProjectBuilder object definition into the ControlTier Server.

4. ctl -p demo -t ProjectBuilder -r mock-site -c Build

   • Builds a working example based on template files and your working environment. Later see Further Customization

The result of these bootstrap steps results in a Site resource named "mock" that you can use to control the life cycle of two Services, "mock1" and "mock2".

You are now ready to run the examples.

Running the Example

You can run any of the Site commands via CTL like so:

ctl -p demo -t Site -r mock -c <command-name>

If you run the command without the "-c <command-name>" parameter you will see a listing of commands.

In the commands below, we will show the output of the command first, then an explanation of what occurred.

Run Start

The Start command calls Start on the Service resources, in the order determined by the startuprank. Notice how the Start command is called on "mock1" before "mock2".

execute:

ctl -p demo -t Site -r mock -c Start

output:

Dispatching command 'Start' to objects: mock1[Service], mock2[Service] ...
starting: mock1[Service]->Start ...
starting: mock2[Service]->Start ...
begin workflow command (1/1) -> "assertServiceIsUp " ...
end workflow command (1/1) -> "assertServiceIsUp "
begin workflow command (1/1) -> "assertServiceIsUp " ...
end workflow command (1/1) -> "assertServiceIsUp "

What happened?

1. The Start command determines the order of the Services, and indicates the commands that will be dispatched
   • Dispatching command 'Start' to objects: mock1[Service], mock2[Service] ...
   • starting: mock1[Service]->Start ...
   • starting: mock2[Service]->Start ...
2. After that, it then sends the Start command to each Service. The Start command invokes the assertServiceIsUp.
   • begin workflow command (1/1) -> "assertServiceIsUp " ...
   • end workflow command (1/1) -> "assertServiceIsUp "

Since this is a "mock" Site example, the Services don't actually do any startup routine, and merely succeed quietly. But you can see that the order was correct as determined by the startuprank, and that each Service actually ran the Start command as intended.

Run Status

The Status command dispatches to "Status" to all Services bound to this Site, and the Status command uses the same sort order as does Start.

execute:

ctl -p demo -t Site -r mock -c Status

output:

Dispatching command 'Status' to objects: mock1[Service], mock2[Service] ...
starting: mock1[Service]->Status ...
starting: mock2[Service]->Status ...
begin workflow command (1/1) -> "assertServiceIsUp " ...
end workflow command (1/1) -> "assertServiceIsUp "
begin workflow command (1/1) -> "assertServiceIsUp " ...
end workflow command (1/1) -> "assertServiceIsUp "

What happened?

Exactly as with Start command above, the Status command was dispatched to each of the Services in the correct order, and the underlying assertServiceIsUp command is then executed for each Service.

Run Stop

The Stop command calls Stop on the Service resources. Since the Stop command uses the startuprank property in descending order to sort the Services, Stop is called on "mock2" before "mock2". Stop works in reverse order relative to Start, as this is typically the behavior desired when managing a set of related software services.

execute:

ctl -p demo -t Site -r mock -c Stop

output:

Dispatching command 'Stop' to objects: mock2[Service], mock1[Service] ...
starting: mock2[Service]->Stop ...
starting: mock1[Service]->Stop ...
begin workflow command (1/1) -> "assertServiceIsDown " ...
end workflow command (1/1) -> "assertServiceIsDown "
begin workflow command (1/1) -> "assertServiceIsDown " ...
end workflow command (1/1) -> "assertServiceIsDown "

What happened?

1. The Stop command determines the order of the Services to dispatch to, now executing on mock2 prior to mock1:
   • Dispatching command 'Stop' to objects: mock2[Service], mock1[Service] ...
   • starting: mock2[Service]->Stop ...
   • starting: mock1[Service]->Stop ...
2. The Stop command is then executed on the two Services in the order shown, which invokes the assertServiceIsDown in turn.

Run dispatchCmd

The dispatchCmd command lets you dispatch any command to a Site's services

• The command to be dispatched must exist in the Services but is not required to have been defined in the Site itself
• The -resourcename and -resourcetype options filter which Services to match (Regular expressions allowed)

The example below runs the "assertServiceIsUp" command across all Service instances, using the regular expression mock[12] to match both the mock1 and mock2 Services. The default sortorder is "ascending", so the mock1 Service is dispatched to first:

execute:

ctl -p demo -t Site -r mock -c dispatchCmd -- -resourcename 'mock[12]' -command assertServiceIsUp

output:

dispatching command: "assertServiceIsUp " to: [(Service) mock1,(Service) mock2 ]...
dispatching to resource: mock1 [Service] -> "assertServiceIsUp "
dispatching to resource: mock2 [Service] -> "assertServiceIsUp "
dispatched command: assertServiceIsUp completed for objects: (Service) mock1,(Service) mock2

What happened?

The assertServiceIsUp is dispatched in the ascending order of startuprank.

We can select the sortorder using the -sortorder option. If we use it with the value "descending" we will see the dispatch happen in reverse order:

execute:

ctl -p demo -t Site -r mock -c dispatchCmd -- -resourcename 'mock[12]' -command assertServiceIsUp -sortorder descending

output:

dispatching command: "assertServiceIsUp " to: [(Service) mock2,(Service) mock1 ]...
dispatching to resource: mock2 [Service] -> "assertServiceIsUp "
dispatching to resource: mock1 [Service] -> "assertServiceIsUp "
dispatched command: assertServiceIsUp completed for objects: (Service) mock2,(Service) mock1

How it Works

The mock Site resource model is defined in a project XML file generated into the $CTIER_ROOT/examples/mock-site. directory. This section walks through the XML definition files used to define the Site and Service resources.

Examine the contents of this file to see the full resource model definition excerpted below:

$CTIER_ROOT/examples/mock-site/default-object.xml

The Service definitions

From Workbench's "Service Manager" page you can navigate to the mock[Site] object and click its link. From that page you can graph the resource model for it and see the graph below:

There are two Service definitions, one for "mock1" and another for "mock2". Services are defined using the deployment tag and its attributes.

The "mock1" Service resource is shown first. Notice the startuprank attribute uses the value "1".

<deployment 
    type="Service"
    name="mock1" 
    description="The first mock Service." 
    installRoot="${env.CTIER_ROOT}/examples/mock-site" 
    basedir="${env.CTIER_ROOT}/examples/mock-site" 
    startuprank="1">
    <!--
  <resources>
  </resources>
    --> 
  <!--
	**
	** Define a parent dependency to the node where you are running this example. 
	**
  -->
  <referrers replace="false">
    <!--
	  ** Change this line to one that matches your node name:
    -->
    <resource type="Node" name="strongmad.local"/>
  </referrers>
</deployment>

The "mock2" Service resource is shown next. Notice the startuprank attribute uses the value "2".

<deployment 
    type="Service"
    name="mock2" 
    description="The first mock Service." 
    installRoot="${env.CTIER_ROOT}/examples/mock-site" 
    basedir="${env.CTIER_ROOT}/examples/mock-site" 
    startuprank="2">
    <!--
  <resources>
  </resources>
    --> 
  <!--
	**
	** Define a parent dependency to the node where you are running this example. 
	**
  -->
  <referrers replace="false">
    <!--
	  ** Change this line to one that matches your node name:
    -->
    <resource type="Node" name="strongmad.local"/>
  </referrers>
</deployment>

The Site definition

The "mock" Site object is defined next. It binds the two Service resources, mock1 and mock2, as child resources. The resources tag lets you represent "whole-part" relationships between objects. Each of the Service resources is referenced via the resource tag:

<deployment 
    type="Site"
    name="mock" 
    description="The mock deployment site." >
  <resources>
    <!--
	  ** Bind the mock1 and mock2 Services to this Site:
    -->
    <resource type="Service" name="mock1"/>
    <resource type="Service" name="mock2"/>
  </resources>
  <!--
	**
	** Define a parent dependency to the node where you are running this example. 
	**
  -->
  <referrers replace="false">
    <!--
	  ** Change this line to one that matches your node name:
    -->
    <resource type="Node" name="strongmad.local"/>
  </referrers>
</deployment>

Command dispatching

After the Site and Service resources were defined they were loaded and installed by the steps in the #Building the Example section. Once installed, commands could be executed via the CTL command dispatcher. In these examples, dispatching occurs at two levels:

1. Site command invocation: At this level, the ctl command line is used to call the specified command in the context of the mock Site object. The dispatcher resolves the command and invokes it for the Site.
2. Service command invocation: The Site commands are nothing more than relays to the bound Services. At this level, the Site commands call the CTL command dispatcher directly, specifying to it the command and the resources they want to target.

The Output

First let's look at the Start command.

You can preview the actions of the Start workflow from Workbench. Navigate to the mock[Site] object in the "Service Manager" and press the "Commands" tab. Locate the "Start" workflow and press the yellow button to right. You will see the Process Flow view display workflow structure across the commands that are dispatched by Start.

From the command line you ran:

$ ctl -p demo -t Site -r mock -c Start

You can see from the output that the Site has dispatched "Start" to "mock1[Service], mock2[Service]" objects. The next two lines are from the command dispatcher invoking the Start command on the Service resources. The last four lines are output from the Service Start commands and reflect that the Service's Start command is a workflow that calls "assertServiceIsUp":

Dispatching command 'Start' to objects: mock1[Service], mock2[Service] ...
starting: mock1[Service]->Start ...
starting: mock2[Service]->Start ...
begin workflow command (1/1) -> "assertServiceIsUp " ...
end workflow command (1/1) -> "assertServiceIsUp "
begin workflow command (1/1) -> "assertServiceIsUp " ...
end workflow command (1/1) -> "assertServiceIsUp "

Next, let's look at the Stop command.

You can preview the actions of the Stop workflow from Workbench. Navigate to the mock[Site] object in the "Service Manager" and press the "Commands" tab. Locate the "Stop" workflow and press the yellow button to right. You will see the Process Flow view display workflow structure across the commands that are dispatched by Stop.

From the command line you ran:

$ ctl -p demo -t Site -r mock -c Stop

You can see from the output that the Site has dispatched "Stop" to "mock2[Service], mock1[Service]" objects. The "mock2" object now precedes the "mock1" since the Site has specified a descending sort order for this command.

Dispatching command 'Stop' to objects: mock2[Service], mock1[Service] ...
starting: mock2[Service]->Stop ...
starting: mock1[Service]->Stop ...
begin workflow command (1/1) -> "assertServiceIsDown " ...
end workflow command (1/1) -> "assertServiceIsDown "
begin workflow command (1/1) -> "assertServiceIsDown " ...
end workflow command (1/1) -> "assertServiceIsDown "

Related Topics

• The Site_Coordination_Models page describes various forms of nesting Sites to coordinate groups of Services using hierarchical forms.
• Mock Service Example shows how to attach your own scripts to the Service types startup and shutdown workflows.