Chapter 2 Creating a Plug-In

This chapter explains how to use the plug-in framework to create a provisioning solution for a specific application or platform. The chapter includes the following information:

• Installing the Plug-In Development Environment

• Creating a Plug-In: Process Overview

• Plug-In Directory Structure

• Developing a Model

• Creating Components and Plans

• Limiting Hosts for a Plug-In

• Enabling Users to Browse and Export Files

• Defining the Plug-In

• Defining an Interface to the Plug-In

• Packaging the Solution

• Testing the Solution

Installing the Plug-In Development Environment

Most of the pieces that you need to create a plug-in solution are part of the standard N1 Grid Service Provisioning System software. However, you must install a few additional software ingredients to provide you with a complete development solution. These key pieces are contained in the plugin-core.jar file on the N1 Grid Service Provisioning System 5.0 Supplement CD.

Once you place the plugin-core.jar file where you want, be sure to modify the classpath for your Java tools to find the file.

The plugin-core.jar contains three packages that provide file system-based component browse and export classes:

com.sun.n1.sps.pluginimpl.system

Includes several constants that identify supported platforms

com.sun.n1.sps.pluginimpl.system.browse

Includes five classes that you can use to support file system-based browsing functionality:

• FileDisplay – A display appropriate for file system files

• FilesystemBrowser – A hierarchy browser for files ystems

• FilesystemBrowserFactory – Factory to return types sufficient for browsing a file system as a hierarchy

• FilesystemExtensionFilter – A FilesystemFilter that filters based on the file extension suffix

• FilesystemFilter – Base class for all file system filters

com.sun.n1.sps.pluginimpl.system.export

Provides one class FilesystemExporter that you can use to export a simple filesystem object

Creating a Plug-In: Process Overview

Developing a plug-in solution can be simple or complex, depending on the needs of your environment and the application or platform to which the solution applies. A plug-in solution can involve any of the following segments of the N1 Grid Service Provisioning System environment:

• Working with variables and configuration templates

• Enabling users to browse through files and export those files to the master server

• Executing Java applications through the execJava feature

• Creating and modifying components and plans

• Packaging the plug-in and defining an interface for it through the plug-in XML

The general process that you follow includes the following steps:

1. Develop a general model for the platform or application.

2. Create plans and components to implement the model.

3. Define specific host types, host sets, and host searches to easily constrain the plug-in.

4. Define an interface for the application within N1 Grid Service Provisioning System.

5. Package the plans, components, resources, and interface definition into a Java Archive (JAR) file.

6. Test the plug-in.

Plug-In Directory Structure

As you develop your solution using the plug-in framework, you need to pay attention to where files are placed. Having an accurate record of the files is essential when you package your solution into a JAR file. The following list illustrates a recommended directory structure for plug-ins:

META-INF
components
plans
resources           
gui                  
plugin-descriptor.xml  
readme.txt

META-INF directory

Contains the mainfest of pieces of the plug-in.

components directory

Contains a series of subdirectories that contain component and component type XML definition files. Subdirectories follow the structure of the plug-in name. For example, if the plug-in name is com.sun.solaris, the components subdirectories would be com, then sun then solaris. For example, the actual component XML files would live inside the components/com/sun/solaris directory.

---

Note –

You might want to wrap the components, plans, and resources directories into a larger directory structure for a given plug-in version. For example, to differentiate between versions 1.0 and 1.1 of a given plug-in, you might use directory structures such as 1.0/components/com/sun/solaris/Project.xml and 1.1/components/com/sun/solaris/Project.xml

---

plans directory

Contains a series of subdirectories that contain execution plan XML definition files. Subdirectories follow the structure of the plug-in name. For example, if the plug-in name is com.sun.solaris, the plans subdirectories would be com, then sun then solaris. For example, the actual execution plan XML files would live inside the plans/com/sun/solaris directory.

resources directory

Contains a series of subdirectories that contain resource files. Subdirectories follow the structure of the plug-in name. For example, if the plug-in name is com.sun.solaris, the resource subdirectories would be com, then sun then solaris. For example, the actual resource files would live inside the resources/com/sun/solaris directory.

gui directory

Contains the user interface descriptor file (pluginUI.xml) and files for any icons that need to be displayed in the user interface. See Chapter 6, Plug-in User Interface Schema, in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide for more information about the elements in the user interface descriptor file.

plugin-descriptor.xml file

XML file that describes the plug-in. See Chapter 5, Plug-in Description Schema, in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guidefor more information about the elements in the plug-in descriptor file.

readme.txt file

Text file that contains any instructions on configuring the system for the plug-in.

Developing a Model

Before you build your plug-in solution, you need to do some planning and modeling work. The following questions indicate some common areas to consider:

• What is the expected environment in which you want this solution to be used? For example, operating system requirements, application version requirements, and so on.

• Do you need to account for any variable values, such as path names, when provisioning this platform or application?

• What files need to be deployed to the provisionable hosts to enable this platform or application to function? For example, configuration files.

• Do you need to define any new component types for this solution, or can you use the existing component types? Many simple solutions can use existing component types, such as system#file and system#directory. If necessary, however, you can define your own component types that extend the existing component types.

• Will a user need to browse for and create instances of a component from a remote system?

• What is the flow of tasks you need your users to be able to perform?

The following illustrates one possible modelling flow, based on the flow for deploying Java^TM 2 Platform, Enterprise Edition (J2EE) :

1. Deploy infrastructure.

   • Execute installer binaries to install infrastructure

   • Installs targetable components

2. Capture all application objects as components, such as the following objects:

   • Java Archive (JAR) files, Enterprise Archive (EAR) files, Web Archive (WAR) files, Enterprise Java Beans (EJB) files

   • JDBC connection and data sources

3. Create an “environment” component that contains environment settings, such as the following:

   • Java Virtual Machine (JVM) settings

   • Session management settings

4. Configure application/environment components

5. Deploy components into targetable components

Creating Components and Plans

To be able to effectively reproduce a given solution across an enterprise, you need to define components, resources, and plans that identify common parts of the solution. In addition, you need to define a process for deploying them. For more information about plans, components, and how to manage them, see N1 Grid Service Provisioning System 5.0 Plan and Component Developer’s Guide.

Building Components

A key piece in developing your solution is creating components. In the N1 Grid Service Provisioning System environment, components are deployable objects. Some examples of the objects you might have in components include the following:

• A collection of files and directories

• Archive files, such as JAR files or EAR files

• Complete applications, including all needed resources

• Specific application resources, such as configuration files or documentation

For information about creating components by using the N1 Grid Service Provisioning System browser interface, see How to Create a Component in N1 Grid Service Provisioning System 5.0 Plan and Component Developer’s Guide.

Simple and Composite Components

Simple components contain a single physical resource, such as a file, directory, archive file, or application. Simple components do not reference other components.

Composite components only reference other simple or composite components. Composite components do not directly contain any physical resources.

Example 2–1 XML for a Simple Component

The following XML example shows a simple component that extends the system component type system#CR Simple Base to contain a JAR file. For more information about the specific elements and attributes used to define a component, see Chapter 3, Component Schema, in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide.

<?xml version="1.0" encoding="UTF-8"?>
<component xmlns='http://www.sun.com/schema/SPS' name='plugin-core.jar' 
    version='5.0' description='Jar file implementation of core plugin services' 
    xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' author='system' 
    softwareVendor='Sun Microsystems' path='/system' 
    xsi:schemaLocation='http://www.sun.com/schema/SPS component.xsd'>
  <extends>
    <type name='system#CR Simple Base'>
    </type>
  </extends>
  <resourceRef>
    <resource name='/system/plugin-core.jar' version='1.1'>
    </resource>
  </resourceRef>
</component>

Variables

When you create a component or plan, you can define variables to use when that component is deployed or the plan is executed. Many component types include common variables, such as installPath, which defines where to install the component. The value of the installPath variable is determined for a given host when the component is installed on that host.

Some common variables that you might see include the following:

• installPath – Path to where the component, plug-in, or other resource file is installed

• installName – Name of item being installed

• installUser – Login name of the user who installed the component, plug-in, or other resource file

• pluginClasspath – Path to where the classes that apply to a specific plug-in are installed

A variable can refer to another variable, such as the variable of a container component. For example, the value of the installPath variable for a simple component could be the value of the installPath variable for its parent container component.

When defined, each variable must have a name and a default value attribute. The default value can be obtained from several places:

• A literal string

• The host, using the target keyword

• Another component, using the component keyword

• The user's session, using the session keyword

For detailed information about using these attributes, see Types of Variables Available for Substitution in N1 Grid Service Provisioning System 5.0 Plan and Component Developer’s Guide.

You can define a variable through the browser interface or directly in the XML file. Within the XML file, variables are defined using the <var> element and contained within a <varList> element.

Example 2–2 Variable Definitions in XML

The following XML fragment shows several variable definitions.

<varList>
    <var name='installPath' 
         default=':[target:sys.raDataDir]:[/]systemcomps'>
    </var>
    <var name='pluginClasspath' 
         default=':[installPath]:[/]plugin-core.jar'>
    </var>
    <var name='fileBrowser' 
          default='com.sun.n1.sps.pluginimpl.system.browse.FilesystemBrowserFactory'>
    </var>
    <var name='directoryBrowser' 
          default='com.sun.n1.sps.pluginimpl.system.browse.FilesystemBrowserFactory'>
    </var>
    <var name='symlinkBrowser' 
          default='com.sun.n1.sps.pluginimpl.system.browse.FilesystemBrowserFactory'>
    </var>
</varList>

Configuration Templates

A configuration template is a special type of file component. The configuration template enables you to do token substitution in a file that you are deploying. An example of this usage would be deploying the DNS /etc/resolv.conf file. The goal for deployment might be to have the file use a variable substitution and use a host type attribute to define the closest DNS server. The configuration template might look like the following example:

search :[search_path]
nameserver :[primary_dns]
nameserver :[secondary_dns]

In this case, the configuration template would automatically create component variables called search_path, primary_dns, secondary_dns. Then you could use variable substitutions in plans or component controls to provide appropriate values.

How to Define a Configuration Template

Step

To designate a file component as a configuration template, select “configuration template” in the Options section of the Component Details page.

Defining Component Types

Many basic component types are included with the N1 Grid Service Provisioning System product. Some of these basic component types include such items as files and directories. You can also define specific component types for use with a specific application or platform. For example, perhaps your application has some specific file types that would always exist for this application. You could then define a new component type for your application that is based on the system#CR Simple Base component type but extends that component type for your specific application.

The component type definition is stored in an XML file like any other component XML file. When you define your plug-in, you provide a path to the file for the backing component in the <component> element in the descriptor file. You use the <componentType> child element of the <component> element to provide additional information, such as its name, description, and so on. For more information, see Example 2–15.

How to Create a Component Type

Steps

1. Determine what component types you need to create.

2. From the Administrative section of the browser interface, click Component Types.

3. From the Component Types page, click Create in the Action column.

   ---

   Note –

   You can type a name for the component type before you choose the Create action or you can type or change the name in the Edit window. Once you check in the component type, you cannot change its name.

   ---

4. Accept the name or change it.

   A component type name has a maximum of 64 characters. The name must start with a letter or underscore, followed by any number of letters, digits, or special characters, such as underscore (_), period (.), plus (+), minus (-), and space ( ). Unicode letters and digits are permitted.

5. (Optional) Type a menu group name.

   Group names follow the same requirements as the component type name . In addition, a group can be declared as hidden, which prevents the type from showing up in the component type drop-down list on the component list page.

6. Type an alpha-numeric string for the menu order.

   The menu order is a maximum of 18 characters. In addition to Unicode letters and digits, any character that you can type on an ASCII keyboard is permitted. The order should be sufficient to sequence all of the types that are defined within a particular plug-in.

7. Type a numeric value between 0 and 10 for the indent level.

   The indent level specifies how types should appear within the component type drop-down list on the component list page. Indents are used in conjunction with ordering to imply relationships between component types. For example, a wep app type might have related types web app configuration and web app archive that are indented more to highlight the relationship.

8. (Optional) Type a description.

   The description must be less than 1024 characters in length. In addition to Unicode letters and digits, any character that you can type on an ASCII keyboard is permitted.

9. Select a backing component.

   A backing component provides a template for the component type.

10. Click Save.

Creating Plans

A plan is a sequence of instructions that is used to manage one or more components on the specified hosts. For example, a plan might install three components and initiate the startup control of another component. To create most plans, you have to edit the XML. The one exception to this rule is an auto-generated plan. The N1 Grid Service Provisioning System software can automatically generate a plan consisting of direct run procedures. For example, you could auto-generate a plan that consists of installing a single component. You could then run this plan directly or save it for use as a template for authoring more complex plans.

Simple and Composite Plans

Simple plans contain a series of deployment instructions, or steps. Simple plans are executed on a single host or host set. Simple plans can call common procedures, such as install or uninstall, and can also use conditional programming constructs.

Composite plans contain calls to simple plans. Composite plans can apply some procedures to one host, while applying other procedures to a different host or host set.

Example 2–3 XML for a Simple Plan

A simple plan might look like the following example. This plan provides an install block and an uninstall block. For more information about the specific elements and attributes used to define a plan, see Chapter 4, Plan Schema, in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide.

<?xml version="1.0" encoding="UTF-8"?>
<!-- generated by N1 SPS -->
<executionPlan xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' 
    name='plugin-core.jar-1096573592002' version='5.0' 
    xsi:schemaLocation='http://www.sun.com/schema/SPS plan.xsd' 
    xmlns='http://www.sun.com/schema/SPS' path='/system/autogen'>
    <simpleSteps>
        <install blockName='default'>
            <component name='plugin-core.jar' path='/system' version='1.1'>
            </component>
        </install>
        <uninstall blockName='default'>
            <installedComponent name='plugin-core.jar' versionOp='=' 
                 version='1.1' path='/system'>
            </installedComponent>
        </uninstall>
    </simpleSteps>
</executionPlan>

Example 2–4 XML for a Composite Plan

A composite plan might look like the following example. This example calls three sub-plans.

<executionPlan 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  name="apache-tomcat-uninstall" version="4.0"
  xsi:schemaLocation="http://www.centerrun.com/schema/CR plan.xsd"
  xmlns="http://www.centerrun.com/schema/CR">
    <compositeSteps>
        <execSubplan planName="mod-jk-uninstall" />
        <execSubplan planName="apache-uninstall" />
        <execSubplan planName="tomcat-uninstall" />
    </compositeSteps>
</executionPlan>

Example 2–5 XML for a More Sophisticated Plan

The following example shows a more complicated plan that determines what to execute based on some conditions.

<?xml version="1.0" encoding="UTF-8"?>
<!-- generated by CR -->
<executionPlan xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    name="BAM_backout_new_version_NODE-A" version="4.0" 
    xsi:schemaLocation="http://www.centerrun.com/schema/CR plan.xsd" 
    xmlns="http://www.centerrun.com/schema/CR" path="/plans/uat">
   <paramList>
      <param name="backout_type" prompt="Enter type of backout (all,ear,prop)"></param>
   </paramList>
   <varList>
      <var name="admin_server" default="wusx119"></var>
      <var name="node" default="wust3022"></var>
      <var name="wl_server_name" default="bamC"></var>
      <var name="apphome" default="/opt/uat/ceodomain"></var>
      <var name="prop_args" default="-s wust3022"></var>
      <var name="application_name" default="bam"></var>
      <var name="staging_base" default="/usr/local"></var>
      <var name="user" default="weblogic"></var>
   </varList>
   <simpleSteps limitToHostSet="uat-bam">
      <if>
         <condition>
            <or>
               <equals value2="all" value1=":[backout_type]"></equals>
               <equals value2="prop" value1=":[backout_type]"></equals>
               <equals value2="ear" value1=":[backout_type]"></equals>
            </or>
         </condition>
      <then>
         <call blockName="backout_application">
            <argList application_name=":[application_name]" 
                 staging_base=":[staging_base]" 
                 backout_type=":[backout_type]" 
                 user=":[user]">
            </argList>
            <installedComponent name="deploy_tools" 
                  path="/components/function_library">
             </installedComponent>
         </call>
         <call blockName="wl_stop">
            <argList wl_server_name=":[wl_server_name]" 
                  node=":[node]" apphome=":[apphome]" user=":[user]">
            </argList>
            <installedComponent name="deploy_tools" 
                  path="/components/function_library">
            </installedComponent>
         </call>
         <if>
            <condition>
              <equals value2="all" value1=":[backout_type]"></equals>
            </condition>
         <then>
               <call blockName="clusterdeploy">
                  <argList application_name=":[application_name]" 
                        staging_base=":[staging_base]" node=":[node]" user=":[user]">
                  </argList>
                  <installedComponent name="deploy_tools" 
                        path="/components/function_library">
                  </installedComponent>
               </call>
               <call blockName="deploy_prop">
                  <argList application_name=":[application_name]" 
                        prop_args=":[prop_args]" staging_base=":[staging_base]" 
                        user=":[user]">
                  </argList>
                  <installedComponent name="deploy_tools" 
                        path="/components/function_library">
                     </installedComponent>
                  </call>
                  <call blockName="wl_startjsp">
                     <argList application_name=":[application_name]" 
                        wl_server_name=":[wl_server_name]" 
                        node=":[node]" apphome=":[apphome]" user=":[user]">
                     </argList>
                     <installedComponent name="deploy_tools" 
                        path="/components/function_library">
                     </installedComponent>
                  </call>
               </then>
            </if>
            <if>
               <condition>
                  <equals value2="ear" value1=":[backout_type]"></equals>
               </condition>
               <then>
                  <call blockName="clusterdeploy">
                     <argList application_name=":[application_name]" 
                        staging_base=":[staging_base]" node=":[node]" user=":[user]">
                     </argList>
                     <installedComponent name="deploy_tools" 
                        path="/components/function_library">
                     </installedComponent>
                  </call>
                  <call blockName="wl_startjsp">
                     <argList application_name=":[application_name]" 
                        wl_server_name=":[wl_server_name]" 
                        node=":[node]" apphome=":[apphome]" user=":[user]">
                     </argList>
                     <installedComponent name="deploy_tools" 
                        path="/components/function_library">
                     </installedComponent>
                  </call>
               </then>
            </if>
            <if>
               <condition>
                  <equals value2="prop" value1=":[backout_type]"></equals>
               </condition>
               <then>
                  <call blockName="deploy_prop">
                     <argList application_name=":[application_name]" 
                        prop_args=":[prop_args]" 
                        staging_base=":[staging_base]" user=":[user]">
                     </argList>
                     <installedComponent name="deploy_tools" 
                        path="/components/function_library">
                     </installedComponent>
                  </call>
                  <call blockName="wl_start">
                     <argList application_name=":[application_name]" 
                        wl_server_name=":[wl_server_name]" 
                        node=":[node]" 
                        apphome=":[apphome]" 
                        user=":[user]">
                     </argList>
                     <installedComponent name="deploy_tools" 
                        path="/components/function_library">
                     </installedComponent>
                  </call>
               </then>
            </if>
         </then>
         <else>
            <raise message="Please enter a valid deployment type (all/ear/prop)"></raise>
         </else>
      </if>
   </simpleSteps>
</executionPlan>

How to Generate a Plan

Steps

1. Go to the Components page.

2. Select the component for which you want to generate the plan.

3. View the component's details.

4. If needed, scroll down the page until you see Component Procedures.

5. Select the procedures that you want to use in the plan.

6. Click Generate Plan with Checked Procedures.

   The Plans editing page appears. From this page, you can modify the XML to include more complex steps, like those shown in Example 2–5.

Using Native Commands in Plans and Components (<execNative> Step)

The <execNative> XML step enables you to run native commands from within your plans and components. For example, if you need to verify that a process has started, you might use <execNative> to call the UNIX ps command. For more information about the <execNative> schema, attributes, and child elements, see <execNative> Step in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide.

Before <execNative> executes the specified command, the N1 Grid Service Provisioning System software verifies that the command exists and that the specified user has permission to run the command. If either of these checks fail, <execNative> exits with an error.

Example 2–6 Using <execNative> to Invoke a Simple Command

The following <execNative> example performs the equivalent of the UNIX ps -ef command.

<execNative>
    <exec cmd="ps">
        <arg value="-ef" />
    </exec>
</execNative>

Example 2–7 Using <execNative> to Start an Application

The following <execNative> example starts a web server instance.

<execNative
  dir="/opt/ns/https-admserv"                Set working directory
  userToRunAs="webadmin"                     Equates to "su -webadmin"
  timeout="5">
    <inputText>
        start.sh                             Input parameters to command
    </inputText>
    <exec cmd="sh />                         Command to run
    <successCriteria status="0" />           execNative succeeds only if exit code is "0"
</execNative>

Calling Java-based Objects in Plans and Components (<execJava>)

The <execJava> mechanism enables agent-side, in-process execution of client-provided Java code within a plan or component definition. <execJava> is similar to <execNative>, but is specifically intended to enable execution of Java code.

The <execJava> feature is provided as an XML step and as a Java-based API. For information about the XML schema, attributes, and child elements, see <execJava> Step in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide. For more information about the execJava API, including examples, see execJava API.

The <execJava> XML step has one required and two optional attributes:

• className – A required attribute that provides the Java class to be executed on the target host.

• classPath – An optional attribute that provides the path to the class identified by the className attribute; If this attribute is not used, the system class path of the remote agent is used

• timeout – An optional attribute that specifies the number of seconds to wait for the Java class to execute before timing out

The <execJava> mechanism can pass arguments to the Java Executor using the <argList> child element.

Example 2–8 Using <execJava> in Component XML

<varList>
   <var name="installPath" default="/opt/util"/>
</varList>
<resourceList defaultInstallPath=":[installPath]">
   <resource resourceName="util/propPrint.jar" installName="propPrint.jar"/>
</resourceList>
   ...
<controlList>
   <control name="showProp"/>
   <paramList>
       <param name="propName">
   </paramList>
   <execJava
       className="com.raplix.util.PropertyPrinterFactory"
       classPath="$[installPath]/propPrint.jar">
       <argList>
           <arg name="propertyName" value=":[propName]"/>
       </argList>
       <successCriteria outputMatches="<undefined>" inverse="true"/>
   </execJava>

Example 2–9 Using <execJava> in Plan XML

<executionPlan xmlns="http://www.sun.com/schema/SPS" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   xsi:schemaLocation="http://www.sun.com/schema/SPSplan.xsd" 
   name="execJavaExample" version="5.0">
   <paramList>
       <param name="name"></param>
       <param name="value"></param>
   </paramList>
   <varList>
       <var name="classpath" 
           default=":[target:sys.raDataDir]:[/]systemcomps:[/]plugin-com.sun.sample.jar"/>
   </varList>
   <simpleSteps>
       <execJava className="com.sun.n1.sps.pluginimpl.sample.executor.SampleExecutorFactory"
           classPath=":[classpath]">
           <argList nameParam=":[name]" valueParam=":[value]" />
       </execJava>
   </simpleSteps>
</executionPlan>

Conditional Elements

Within a plan or a component, you can use the <if> element to conditionally perform a block of steps. Similar to traditional programming if-then-else constructs, the statement within the <if> element is evaluated. If that statement is true, then the steps of the <then> element are performed. Otherwise, the steps of the <else> element are performed. If no <else> element exists, then no action is taken.

Example 2–10 XML for <if> Element

The following example uses the <if> element to allow users to decide at deployment time whether to take a snapshot.

<if>
    <condition>
        <istrue value=:[createSnapshot]"></istrue>
    </condition>
    <then>
        <createSnapshot blockName="default"></createSnapshot>
    </then>
</if>

Error Handling

The XML schemas provides a set of elements for handling possible errors . The parent of this set of elements is the <try> element. You might use these elements for situations similar to the following examples:

• To suppress errors during deployment. For example, if installation of a component consists of deploying some files or other resources followed by a restart and the restart fails, then the installation itself does not fail.

• To control whether a step that depends on another step should be performed. For example, if you need to perform both useradd and groupadd functions, the groupadd should only be performed if the useradd is successful.

• To determine which install path to take. For example, if you are installing version 1.1 of an application, the install path might be different depending on whether version 1.0 of that application is on the target host.

The <try> element includes a block of steps that are executed in order until either all complete successfully or a step fails. If a step fails and a <catch> element exists, then the steps in the <catch> element are executed in order until they succeed or a step fails. If a <finally> element is defined, the steps in the <finally> element are executed in order until all steps complete or a step fails regardless of whether the <try> and <catch> elements succeeded. Typically, the <finally> element is used to perform clean-up functions or release resources.

The <raise> element is used to indicate a failure condition without having to create a step to do so. The <raise> step always fails. Although the <raise> element can be used by itself, it is often contained within a <catch> element block.

Example 2–11 XML for <try> Element

The following XML example uses the <try> element to determine whether a fresh install or an upgrade install should be performed.

<installSteps blockName="default">
    <try>
        <block>
            <checkDependency>
                <installedComponent name="foo" version="1.0" />
            </checkDependency>
        </block>
        <catch>
        </catch>
    </try>
</installSteps>

Limiting Hosts for a Plug-In

The N1 Grid Service Provisioning System enables you to limit plug-in behavior to hosts that match certain criteria. There are three mechanisms that you can use to limit your hosts:

• Define a specific host type. The host type defines a base class of servers that is bound by a set of common attributes. For example, you might define a host type that identifies servers that are considered to be Solaris 10 global zones.

• Define a host set. The host set is a logical grouping of hosts that share one or more common attributes, such as physical location or functional group. Use a host set to quickly and easily update all hosts in the set. You can also use host sets to perform install-to-install comparisons.

• Define a host search. A host search queries the host database to provide a list of hosts whose attributes match those that the query specifies. You might use the host search to find all hosts that match a given host type or that run a certain application.

You define all three host limiters in the plug-in descriptor file, as shown in the following examples.

Example 2–12 Host Type Definition in plugin-descriptor.xml File

The following example defines two host types for use with Solaris containers: one for a global zone and one for a local zone. The plug-in name is appended to the actual hostType name. When a user creates a host of type com.sun.solaris#global_zone, four attributes are provided, each attribute of which has a default value. The com.sun.solaris#local_zone host type, on the other hand, has no user-defined attributes associated with it.

<hostType name="global_zone" 
    description="a physical host from which partitioned local zones can be created"> 
  <varList>
    <var name="local_zone_base_path" default="/export/zones"/>
    <var name="local_zone_connection_type" default="RAW"/>
    <var name="local_zone_port" default="1131"/>
    <var name="local_zone_advanced_params" default=" "/>
  </varList>
    </hostType>
    <hostType name="local_zone" 
      description="a physical host that is created out of the larger global_zone"/>

Example 2–13 Host Set Definition in plugin-descriptor.xml File

The following example defines a host set that contains global zones. The actual contents of the host set are provided when the referenced host search is performed.

<hostSet name="global_zones"
     description="Solaris global zones">
<hostSearchRef name="global_zones"/>

Example 2–14 Host Search Definition in plugin-descriptor.xml File

The following example defines a host search to find all global zones. The search returns a result for any host that matches the following criteria:

• Is running the Solaris 10 operating system

• Has a host type of com.sun.solaris#global_zone

• Is running a remote agent

• Is a physical host, rather than a virtual host

<hostSearch name="global_zones" description="Solaris global zones">
  <criteriaList>
    <criteria name="sys.OS" pattern="SunOS"/>
    <criteria name="sys.OSVersion" pattern="5.10"/>
    <criteria name="sys.hostType" pattern="com.sun.solaris#global_zone"/>
  </criteriaList>
  <appTypeCriteria ra="true"/>
  <physicalCriteria physical="true"/>
</hostSearch>

Enabling Users to Browse and Export Files

The N1 Grid Service Provisioning System provides capabilities for you to enable users to include specific resources in their components. The browsing feature consists of two primary functions:

• Browse – Enables the user to traverse arbitrary, tree-like, filtered object hierarchies on the remote agent machines and to select an object in that tree.

• Export – Enables the user to check into the master server the selected object or collection of objects, possibly in a modified form.

For example, you could enable a user to traverse a file system, select a file, and check in the file through a component.

Browsing and exporting functionality are provided through the com.sun.n1.sps.plugin.browse and com.sun.n1.sps.plugin.export packages, as described in Component APIs.

Browsing and Exporting: Process Overview

From an external view, the browsing and exporting process is similar to the following sequence:

1. The user selects a component type to create a component. If the backing component of the selected type has exporterClassName defined, the browse and export user interface is launched.

2. The provisioning software obtains all the browser information in the BrowserInfo class. To obtain this information, the software calls the getAvailableBrowsers method of the ComponentExporter interface.

3. The provisioning software obtains the information about the BrowserFactory from BrowserInfo and instantiates it. From there, the provisioning software gets the Browser object.

4. From the Browser object, the software finds the root node by calling the getNode() method of Browser.

5. When the user selects a node and continues with the check-in process, the provisioning software calls into the constructComponent method of the ComponentExporter class which finally exports and checks-in the resource.

From the plug-in development perspective, a more detailed view of this process is similar to the following sequence:

1. The backing component of a component type defines a component variable named exporterClassName. The value of exporterClassName is the class that implements com.sun.n1.sps.plugin.export.ComponentExporter.

2. The ComponentExporter class method getAvailableBrowsers returns an array of BrowserInfo objects. These BrowserInfo objects have the following information about the browser:

   • Name of the system service

   • Variable name in the above system service. This variable will have the BrowserFactory class as its value

   • Variable name in the above system service. This variable will have the class path for the browser as its value.

   • The actual class path, if system service is not used for class path.

3. The BrowserFactory class has a method to get the browser which implements the Browser interface.

4. The Browser method getNode(...) finds the nodes of a tree. When used with a null argument, getNode(...) should give the root node.

5. The ComponentExporter class has another method to construct the component. This method is used once the actual browsing is done. The constructComponent method is passed a ComponentMonitor which is used to finally export and check-in the selected resource into the master server as part of the component.

Browse Function

BrowserNode is the class which implements the entire hierarchy tree functionality. This functionality is segmented into four key areas:

• Providing all the children of the node

• Providing the parent if the node

• Describing whether the node is a leaf node

• Providing other descriptions and properties related to the node

For more information about the classes and methods that you use to implement a browser for your plug-in, see Browsing Function.

Export Function

ComponentExporter is the class which enables a user to export a file to the master server, once he has browsed to it. For more information about the classes and methods that you use to implement the export feature for your plug-in, see Exporting Function.

Defining the Plug-In

To make the solution available for others to use, you wrap the plans, components, and component type definitions into a plug-in. To define the plug–in, you create an XML file that uses the <plugin> element and its children. For information about the <plugin> element, see Chapter 5, Plug-in Description Schema, in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide.

Example 2–15 Sample Plug-In Descriptor File

The following sample descriptor file is for the Solaris Zones plug-in.

<?xml version="1.0" encoding="UTF-8"?>
<plugin name="com.sun.solaris"
   description="Solaris plugin"   version="1.0"
   vendor="Sun Microsystems Inc"
   xmlns="http://www.sun.com/schema/SPS"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.sun.com/schema/SPS plugin.xsd"
   schemaVersion="5.0">
   <gui jarPath="gui/pluginUI.xml"/>
   <memberList>
       <folder name="/com/sun/solaris" description="Solaris plugin folder"/>
       <hostType name="global_zone"
            description="a physical host from which partitioned local zones can be created">
          <varList>
            <var name="local_zone_base_path" default="/export/zones"/>
            <var name="local_zone_connection_type" default="RAW"/>
            <var name="local_zone_port" default="1131"/>
            <var name="local_zone_advanced_params" default=" "/>
         </varList>       </hostType>
       <hostType name="local_zone" 
            description="a physical host that is created out of the larger global_zone"/> 
       <hostSearch name="global_zones" description="Solaris global zones">
         <criteriaList>
            <criteria name="sys.OS" pattern="SunOS"/>
            <criteria name="sys.OSVersion" pattern="5.10"/>
            <criteria name="sys.hostType" pattern="com.sun.solaris#global_zone"/>
         </criteriaList>
         <appTypeCriteria ra="true"/>
         <physicalCriteria physical="true"/>
       </hostSearch>
       <hostSet name="global_zones" description="Solaris global zones">
         <hostSearchRef name="global_zones"/>
       </hostSet>
       <component jarPath="fiji/components/com/sun/solaris/zone_util.tar.xml">
         <resource jarPath="fiji/resources/com/sun/solaris/zone_util.tar"
             name="/com/sun/solaris/zone_util.tar"/>
       </component>
       <component jarPath="fiji/components/com/sun/solaris/N1GridContainer.xml" 
         majorVersion="true">
       </component>
       <component jarPath="fiji/components/com/sun/solaris/ZoneSS.xml">
         <systemService name="zoneSS"
           description="the Solaris zone system service"/>
       </component>   </memberList>
</plugin>

Defining an Interface to the Plug-In

One of the key activities in creating a solution that you can provide to others or distribute across your environment is defining an interface to your solution within the N1 Grid Service Provisioning System browser interface. To define the interface, you create an XML file that uses the <plguinUI> element and its children. For information about the <pluginUI> element, see Chapter 6, Plug-in User Interface Schema, in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide.

Example 2–16 Sample Plug-In Interface File

The following sample plug-in interface file pluginUI.xml is for the Solaris Zones plug-in.

<?xml version="1.0" encoding="UTF-8"?>
<pluginUI menuItem="Solaris"   xmlns="http://www.sun.com/schema/SPS"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.sun.com/schema/SPS pluginUI.xsd"
   schemaVersion="5.0">
   <icon jarPath="gui/solaris.gif"/>
   <customPage name="Solaris"> 
    <section title="Solaris specific tasks"
       description="create and manage Solaris specific components...">
       <entry title="Solaris Zones" description="create and manage zones">
         <action text="list" toolTip="list of installed zones">
           <compWhereInstalled path="/com/sun/solaris" name="N1GridContainer"/>
         </action>
         <action text="create and manage" toolTip="create and manage zones">
           <compDetails path="/com/sun/solaris" name="N1GridContainer" />
         </action>
       </entry>
     </section>
   </customPage>
</pluginUI>

Packaging the Solution

To enable others to use your solution or to make it available for easy distribution within your own environment, you package your solution in a Java Archive (JAR) file. The contents and instructions for interpreting the contents of the JAR file are contained in an optionally signed plugin-descriptor.xml file located in the top level directory of the JAR. The syntax of the plug-in descriptor is specified using XML Schema as per the May 2, 2001 W3C Recommendation (http://www.w3.org/TR/2001/xmlschema-0-20010502/). The schema can be used in conjunction with a validating parser to determine the syntactical validity of a plug-in. For information about the plug-in descriptor file, see Defining the Plug-In.

To create the JAR file, you use the JAR utility. The JAR utility uses similar options to the standard UNIX tar utility.

To create a JAR file, use the following command from the root directory that contains all the plug-in files: jar cf jarfile inputfiles

where:

• The c option creates a new archive named jarfile that contains the files and directories specified by inputfiles.

• The f jarfile option specifies the name of the file to be created.

• inputfiles identifies the files or directories to be included in the JAR file. You can provide a list of file and directory names separated by spaces, or you can use the asterisk (*) character to include all the files in the current directory. All directories are processed recursively.

Example 2–17 Creating a JAR File That Contains Subdirectories

If you have subdirectories, you can combine them into a single JAR file, as shown in the following example command:

% jar cvf myplugin.jar *
added manifest
ignoring entry META-INF/
ignoring entry META-INF/MANIFEST.MF
adding: components/(in = 0) (out= 0)(stored 0%)
adding: components/com/(in = 0) (out= 0)(stored 0%)
adding: components/com/sun/(in = 0) (out= 0)(stored 0%)
adding: components/com/sun/myplugin/(in = 0) (out= 0)(stored 0%)
adding: components/com/sun/myplugin/mycomponent.xml(in = 6224) (out= 1182)(deflated 81%)
adding: components/com/sun/myplugin/myothercomponent.xml(in = 1291) (out= 507)(deflated 60%)
adding: components/com/sun/myplugin/mycomponenttype.xml(in = 940) (out= 470)(deflated 50%)
adding: resources/(in = 0) (out= 0)(stored 0%)
adding: resources/com/(in = 0) (out= 0)(stored 0%)
adding: resources/com/sun/(in = 0) (out= 0)(stored 0%)
adding: resources/com/sun/solaris/(in = 0) (out= 0)(stored 0%)
adding: resources/com/sun/solaris/zone_util.tar(in = 20480) (out= 4232)(deflated 79%)
adding: gui/(in = 0) (out= 0)(stored 0%)
adding: gui/pluginUI.xml(in = 861) (out= 407)(deflated 52%)
adding: gui/solaris.gif(in = 1622) (out= 1627)(deflated 0%)
adding: plugin-descriptor.xml(in = 1990) (out= 707)(deflated 64%)
% 

To verify the files in the JAR file, use the following command:

% jar tf mypluin.jar
META-INF/MANIFEST.MF
fiji/
fiji/components/
fiji/components/com/
fiji/components/com/sun/
fiji/components/com/sun/solaris/
fiji/components/com/sun/solaris/N1GridContainer.xml
fiji/components/com/sun/solaris/ZoneSS.xml
fiji/components/com/sun/solaris/zone_util.tar.xml
fiji/resources/
fiji/resources/com/
fiji/resources/com/sun/
fiji/resources/com/sun/solaris/
fiji/resources/com/sun/solaris/zone_util.tar
gui/
gui/pluginUI.xml
gui/solaris.gif
plugin-descriptor.xml

Testing the Solution

Before you make your solution available across your environment or for others to use, you should test the solution. The following ideas might help you decide what to test:

• Use an XML parser to validate the plugin-descriptor.xml file against the plugin.xsd schema.

• Use an XML parser to validate the pluginUI.xml file against the pluginUI.xsd schema.

• Make sure that any Java code that you use builds cleanly and works as expected.

• Import your finished plug-in to the N1 Grid Service Provisioning System product. Check for errors and make sure that the customized user interface, if it exists, renders as expected, and that all links on the customized page work as expected.

• Verify that you can delete your plug-in after a successful import.