Graphical type editor
From ControlTier
The ControlTier server hosts a graphical Type modeling tool that lets you design every aspect of your custom types and commands. Interfaces are provided to search and browse existing types. New types are defined through the process of sub-typing an existing type, choosing from one of the core types or from one of your own types. For existing types, you can define new commands, constraints, attributes and objects. Workbench generates modules for all types that declare commands.
Workbench's design features are the graphical counterpart to the ProjectBuilder command line based utility and type.xml.
Contents |
The Workbench interface provides several places to navigate the types defined in your project. Your project will have been initialized with all the core types but may also contain other subtypes.
Search form
After login, you are directed to the Workbench home page. In the top right, you will see the "Advanced Search" button. Pressing that reveals a search text field and type browser button.
You can always return to the home page to access the Type Search form.
Type search
Type in the name of the type you are looking for into the text field and hit return. Matching types are listed in a results page.
Search strings are not case sensitive. You can use regular expressions.
Type browser
The graphical editor includes a type browser that provides an interface to browse navigate the inheritance structure of the type model. All type editing pages include this type browser on the right hand of the page.
You can also access this type browser from the "Search" form in the home page. Pressing the "Browse Types" button will expand the type browser and reveal one level of the type inheritance hierarchy. Pressing the gray triangles to the left of the type name will show or hide that types subtypes.
You can navigate through the type inheritance hierarchy via the type browser. To the right of each type name is another button that when pressed will re-orient the type browser to focus on that type. The Subtypes and Supertypes views will be re-displayed accordingly. The type browser lets you look through the types without leaving the page your on.
View type
Once you have selected the type (either from the search results or via the type browser) you will be directed to the "Type View" page.
Types are are displayed in a standard way. The type's name and description are displayed near the top. Below the description is a toolbar of buttons each containing a link to a type editing action.
Below the toolbar is a row of buttons controlling tabbed views. Pressing a button in the tab button bar will select that view.
To the right is the type browser, automatically opened to the selected type (eg, "Service") and its super and subtypes.
Tabbed views
Information about each type is divided up into several views organized into a set of tabbed windows.
Pressing the label in the tab bar will change the view to display that window tab.
- Details: Describes object creation settings and command module settings.
- Commands: Lists all commands declared for that type
- Files: A file browser listing all files generated or uploaded for this type
- Constraints: Controls Constraints and Attributes
- Objects: Lists all instances created for this type.
Details tab
Inside the "Details" view you can see a number of configuration values:
Type toolbar
- Edit: Edit the type definition
- Copy: Create a new type definition using the selected type as the initial specification
- Graph: Graph the commands defined in the type
- Delete: Delete the type definition from the project
- Lock: Lock the type definition so it cannot be edited.
Edit form
Pressing the "Edit" icon in the toolbar will direct the browser to the "Edit Type" page. The form will include several form elements:
- Parent Type: This lets you change the super type
- Description: Change the description of the type
- Advanced Options: This is hidden but can be revealed by pressing the triangle icon to reveal the form element
- Role: Can be 'concrete' or 'abstract'
- Unique Object Name: Can be 'true' or 'false'
- Version History Log Entry: A comment that will be recorded in the history log.
Once the fill has been formed out to suit requirements the "Save Type" button is pressed to store the changes to the project.
Change supertype
The "Parent Type" form element described in the preceding section is actually a form itself.
Pressing the Edit button next to the supertype name will direct the browser to a new page. This page will list all the supertype choices appropriate for this type.
Choice is specified by pressing one of the radio buttons and pressing the "Change Supertype" button.
Copy form
New type definitions can be created by copying the specification from another type. Press the "Copy" button in the toolbar. This will direct the browser to the "Copy Type" form. The form includes elements:
- New Type Name: This is the name of the new type
- Description: Description of the new type
Graph form
Commands defined in the type can be graphed. This is useful when the type defines a set of workflows. Press the "Graph" button in the toolbar to bring up the graph tool. By default the graph tool will display all commands.
Inside the tool there is a "Graph Controls" link that will generate a pop-up window with several controls to configure the graph.
Remove form
A type definition can be removed from the project through the remove action. Press the "Remove" icon in the toolbar to remove the type.
If any instances of the type had been created, the remove action will list them and require you to delete them first.
Lock form
Workbench supports a locking feature to prevent future modifications to the type definition. To lock the type from being modified press the "Lock" icon in the toolbar.
Press the "Lock Type" button to store the change.
After the type has been locked the toolbar buttons are reconfigured to show only two buttons
- Graph: Graphing the type
- Unlock: Unlock the type so it can be modified.
Command module settings
Each Type has two Object Creation Settings:
- Creation role: either "concrete", or "abstract". If "abstract", then the Type is not allowed to have Objects created for it.
- Unique Object Names: true/false. If True, then all Objects of this Type must have a unique name.
To change the Object Creation Settings, choose the "Edit Type" link (Pencil icon) on the Type View page. Under the Advanced Options you can see options to change these values:
The Types also have a set of Command Module Settings:
- Logger Name: a string, unused.
- Transforms Directory: A path, used by the Documents feature. (optional)
- Failure Notifications: true/false. If True, then command failure notifications are sent to the Notification Email.
- Notification Email: An email address where failure notifications are sent.
- Dependencies View: Either Children, Parents, or both.
- View Degrees away: An integer from 1-4
To change the Command Module Settings, click the Pencil icon next to the list of Command Module Settings in the Type View.
You will see this form:
Create a type
Pick a supertype
The first question you should ask is "What Supertype should I use?"
ControlTier's Core Types, and all of the other pre-installed types offer a variety of solutions and features. You should examine them to determine what best suits your needs.
In the examples below we have decided to use Service as the Supertype. This is a good point to start from if you are implementing a Type to control some custom software service that does not already have a Type to control it.
Create subtype
To create a Type, first navigate to the Type you want as the Supertype. Click the "Create Subtype" button the right side of the page:
Fill in the Name, Description, and optionally change the Object Creation Settings under the Advanced Settings section, then Click the "Save Type" button:
After pressing "Save Type", you will be directed to the Type View page for your new type. Notice in the right hand of the screenshot how the "Package Commands" button has a warning icon. This means the type has been created but not packaged as a module archive.
You will also notice how the type browser has focused on the new type and shows its supertypes above. This is a new type and therefore has no subtypes of its own.
Next to the "Details" tab you will notice the "Commands" tab. This tab shows the new type has 28 commands. These commands are inherited from the super type.
To the right of each inherited command is the type that declared it. For example the "Deploy" command is declared by the supertype, Service.
Create first command
Commands can be created inside the Commands tab. To create a new command, press the "+" button.
Choose command type
The next screen shows a list of command types.
- Shell command: Implement the command as a shell command
- Ant command: Implement using Ant tasks
- BSF command: Implement using a Bean Scripting Framework langauge
- Workflow command: Define a command as a sequence of commands defined in this type
- Dispatch command: Dispatch a command across a set of objects.
The shell command type form contains these elements:
- Name: Command name (no spaces allowed)
- Description: Brief description
- Execution: Executable to invoke
- Arguments: Arguments to pass to executable
- Private: Checkbox specifying the command is private
- Static: If checked the command can be run outside of an object context. See CTL_Command_Reference#Context
- Daemon: The executable specified above will be spawned to the background
For this example we have chosen to define a Shell Command. Press the "Shell Command" link to bring up the command editing form. Fill in the name and description. Call the command "hello".
The "Static" checkbox is checked.
The "Execution" field specifies what shell command to call. This example uses the Unix bash command. The "Arguments" field contains the content passed to the executable. Here specify echo hello:
Press the "Add Command" button to save the command definition.
Once the command has been saved you will see your new command displayed at the top of the commands list. Your command has a yellow icon to the left of the command name. That yellow icon means that the command is defined in this type. The inherited commands have a gray icon to their left.
Command edit buttons
To the right of the type name you will see a button bar. This contains buttons to various command editing functions.
- Edit command options (flags)
- Edit command defintion
- View generated command handler file on the WebDAV
- Copy this command definition
- Delete the command definition from this type
Command option
You can define parameters to your command as command line options. Press the flag icon in the commands toolbar to edit its command options. A gray flag signifies no options have been defined for it yet.
Option form
The command option form lists existing options (still none) and an "Add Option" form where you can define a new option.
In the Add Option form you will notice the following fields:
- Name: Name of the command option
- Description: Brief explanation of its purpose
- Required: If checked, the command will fail if this option is not set
- Arguments: If checked, the option expects an argument. Otherwise, the option is a boolean type.
- Default property: You can default options that take arguments to a named property.
- Default value: You can default the option to a literal string.
In this example, the form is filled out to define an option named "message" that takes an argument defaulted to the string "world".
Pressing the "Add" link in the Add Option form will save the option definition to the list. The screen below shows the option "-message" has been defined. You can edit the option using the edit button or remove it using the delete button.
Option usage summary
After the options have been defined press the "Update Command Options" button. This will redirect the browser to the Commands tab.
The command will now show the new command options next to the command name: "hello [ -message < world > ]". Options that take arguments are shown with " < > " braces. If a default value is defined for the argument is is shown inside the braces (eg, "< world >").
Referencing command option data
The option has been defined for the command but nothing references its value. Command option data can be referenced from command implementations as property references. Each command option is accessible via an "opts.parameter" property name.
The command definition can be edited to get the value of the "-message" option. The command implemention can access it as ${opts.message}. Below the command edit form shows the Arguments field with the option data referenced.
The command option is defaulted to the string "world" which means that without arguments the hello command will echo "hello world" to the console.
Package commands
Modules
The definition of a Type exists in the ControlTier server's data model, yet in order to make the Commands of the Type usable, they must all be stored into an archive file and distributed to the various ControlTier Clients that need to use it.
A Module is a Java Jar Archive that is created to contain the Type definition and its related file resources, including the Command handler files, any included scripts or templates, and various metadata files which describe the Type itself.
To create the Type Module, navigate to the Type, and click the "Package Commands" button on the right side of the page:
The icon used on this button differs depending on whether the Type has been recently modified or not. When there are changes that have been made to the Type that have not yet been stored in a Module, then the button has an exclamation mark to indicate that the Module is out of date:
When you click this button, the ControlTier server creates the Module file and names it Type-head.jar. This file is then stored in the WebDAV repository under the path /PROJECT/publish/modules, where "PROJECT" is the name of your Project. This is the location that ControlTier Clients will use to find the latest version of the Module when they need to download it.
Files tab
After the "Package Commands" button is pushed, and Workbench has generated a module you can view them via the "Files" tab.
File listings
Pressing the Files tab will show the contents of the module directory. There are a number of standard subdirectories represented by folder icons and a set of files, each of which show their size, last modified time stamp and buttons.
You can navigate into any subdirectory by pressing the link name. For this example, a new command was created and its command handler file can be listed. Click the "commands" link and its files are listed:
File view
Clicking on a file name link will show the content of that file.
Pressing the edit button allows one to modify its content. Keep in mind that Workbench will re-write the command handler any time the "Package Commands" file is pressed.
File upload
You can upload files to the module directory by pressing the upload icon. Pressing that button will reveal an upload form. The form includes two buttons. A file chooser button which will bring up a dialog where you select the file to upload. An "Upload" button that will take the chosen file and upload it to the module directory on the WebDAV repository.
The example below shows the upload form has been revealed and a file called "date.sh" has been chosen.
After the file has been uploaded it, the Files tab will show the listing of the directory again this time with the new file.
In this example the "date.sh" file is now listed in the "bin/" directory. Two controls are provided. One button to edit the content of the uploaded file. The second button lets you delete the file from the directory.
File editor
Pressing the edit button brings up a simple HTML text box displaying the content. You can change the content and then press the "Save" button to store the changed contents back to the WebDAV.
Create second command
In the previous section a shell script was uploaded to the types "bin/" directory. The "bin/" directory is often used to store scripts called by commands. This approach lets you define an interface for a named procedure but maintain the implementation as an external shell script. Keeping the script inside the module lets you avoid worrying about distributing it separately to the CTL nodes.
Define command
As in the first command example, go to the "Commands" tab and press the "New Command" button. Again, choose "Shell command" type and set it "Static".
In command editing form the name, description, and execution strings are defined. In the Arguments string, the call to the script is expressed as "sh ${module.dir}/bin/date.sh".
The "${module.dir}" string is a dynamic property defined by the CTL command dispatcher that will reference the path to the installed module.
Save the command by pressing the "Add command" button. After the command has been added, Workbench will return back the the commands listing.
The type now has two commands defined.
As described in the previous section, it is necessary to package the commands again. Press the "Package Commands" button
With two commands defined, and packaged as a module it is now possible to install it on a CTL node and run them.
Use the module
Pressing the "Package Commands" button ensured the generated module files for the type were stored in the WebDAV for distribution. These modules must also be installed to the CTL nodes so their commands can be executed. Once the module has been installed to the desired nodes the commands are available to the command dispatcher and can be run via the ctl shell command or from Jobcenter.
Install the module
On any CTL node (the server host is fine), run the Managed-Entity#Install-Module command. This command will download the module from the WebDAV and extract it into the CTL project.
execute
ctl -p demo -m Managed-Entity -c Install-Module -- -module NewServiceSubType
output
Created dir: /Users/alexh/ctier/ctl/var/tmp/downloads/demo Getting: http://strongbad:8080/jackrabbit/repository/controltier/projects/demo/publish/modules/NewServiceSubType-head.jar To: /Users/alexh/ctier/ctl/var/tmp/downloads/demo/NewServiceSubType-head.jar Created dir: /Users/alexh/ctier/ctl/projects/demo/modules/NewServiceSubType Expanding: /Users/alexh/ctier/ctl/var/tmp/downloads/demo/NewServiceSubType-head.jar into /Users/alexh/ctier/ctl/projects/demo/modules/NewServiceSubType Attempting to get Service-head.jar ... Getting: http://strongbad:8080/jackrabbit/repository/controltier/projects/demo/publish/modules/Service-head.jar To: /Users/alexh/ctier/ctl/var/tmp/downloads/demo/Service-head.jar Service up to date Attempting to get Deployment-head.jar ... Getting: http://strongbad:8080/jackrabbit/repository/controltier/projects/demo/publish/modules/Deployment-head.jar To: /Users/alexh/ctier/ctl/var/tmp/downloads/demo/Deployment-head.jar Deployment up to date
You can install the module everywhere using node dispatch options. The example below uses the "-I .*" option to signify run that command across all hosts in the depot:
execute
ctl -I '.*' -p demo -m Managed-Entity -c Install-Module -- -module NewServiceSubType
You can see the installed module files in the CTL "modules" directory. Here's an example showing the Unix ls command listing the modules directory for the "demo" project name:
ls $CTL_BASE/projects/demo/modules
List the commands
After the module has been installed to the ControlTier clients the ctl shell tool can list its commands. See CTL_Command_Reference#Listing_Mode.
Ctl will list commands defined in a module by typing the module name but leaving out the command parameter.
The example below lists the commands for the new type.
execute
ctl -p demo -m NewServiceSubType
output (appreviated)
. . date: print the date . . . hello: a hello example [options] [-message <world>]: message to echo . . .
Run the commands
With the type's generated module downloaded and installed to the client nodes where CTL is installed one can now execute the defined commands.
Here's the general usage to execute a module's command: ctl -p project -m type -c command.
Below are examples using the two commands defined in this document.
Running the hello command without options prints the default message string ("world"):
execute
ctl -p demo -m NewServiceSubType -c hello
output
hello world
Specify a different message to print using the "-message <>" option:
execute
ctl -p demo -m NewServiceSubType -c hello -- -message dolly
output
hello dolly
The second command defined was won called date. This command calls an external shell script implementation that resides inside the module.
execute
$ ctl -p demo -m NewServiceSubType -c date
output
Tue Jul 7 10:45:23 PDT 2009
You can view the "date.sh" script that is called on the CTL host by looking in the local project.
This example type was defined in the "demo" project. Doing a file listing in the bin directory shows the "date.sh" script.
$ ls $CTL_BASE/projects/demo/modules/NewServiceSubType/bin date.sh
See also
| ||||||||||||||
