Chapter 5 Plug-in Description Schema

This chapter describes the XML schema that you use to define a plug-in. The chapter contains the following topics:

• <plugin> Element Overview

• <readme> Element

• <serverPluginJAR> Element

• <gui> Element

• <dependencyList> Element

• <memberList> Element

• Sample XML for <plugin> Element

<plugin> Element Overview

The <plugin> element is the top-level element in the plug-in schema. The <plugin> element identifies the parts of the plug-in.

Attributes for the <plugin> Element

The <plugin> element has the following attributes:

• name – The name of the plug-in. The name attribute has a maximum length of 64. Plug-in names follow a structure similar to com.sun.solaris.

• description (optional) – The description of the plug-in.

• vendor – The provider of the plug-in.

• version – The version of the plug-in. Version numbers follow the standard x.y (major.minor) format.

• previousversion (optional) – The version of this plug-in expected to be on the system. If not specified, an initial install is assumed. If specified, the value represents the version from which the plug-in is to be upgraded.

• xmlns – Required value: http://www.sun.com/schema/SPS.

• xmlns:xsi – Required value: http://www.w3.org/2001/XMLSchema-instance.

• xsi:schemaLocation (optional) – Recommended value: http://www.sun.com/schema/SPS plugin.xsd.

• schemaVersion – The version of the plug-in XML schema being used. The only value currently permitted is 5.0.

<plugin> Element Children

The <plugin> element may include the following child elements:

• <readme> (optional) – Path to readme file written by the plug-in author

• <serverPluginJAR> (optional) – Path to JAR file that contains server-side plug-in code to run on the master server

• <gui> (optional) – Optional GUI extensions for the plug-in.

• <dependencyList> (optional) – List of external plug-ins on which this plug-in depends.

• <memberList> (optional) – List of member objects to create as part of the plug-in. These member objects can include any number of folder, host type, host set, host search, component, and plan objects. These member objects can appear in any order.

<readme> Element

The <readme> element is a child of the <plugin> element and is used to declare the location of a readme.txt file in the plug-in JAR. This readme.txt file is expected to be a Unicode-encoded text file. The byte order mark (BOM) is used to specify the Unicode encoding. If no BOM is present, UTF-8 encoding will be used by default.

The <readme> element has one attribute, jarPath, that contains the path name to the readme file. The path name of the readme file is relative to the root of the plug-in JAR file. Leading slash (/) or period (.) characters are not permitted in the jarPath.

<serverPluginJAR> Element

The <serverPluginJAR> element is a child of the <plugin> element and is used to declare the location of a server side plug-in JAR file that contains code to run on the Master Server. The location of this JAR file is relative to the root of the plug-in JAR file. This JAR file will typically contain component exporter implementations for the component types defined by the plug-in. Externally written code that is to run in the Master Server (for example, exporter classes) need not be in the same JAR file as the code that runs on the agent for the plug-in, though it is permissible.

The <serverPluginJAR> element has one attribute, jarPath, that contains the path name to the server-side plug-in JAR file. The path name is relative to the root of the plug-in JAR file. Leading slash (/) or period (.) characters are not permitted in the jarPath.

<gui> Element

The <gui> element is an optional child of the <plugin> element and is used to declare the location of a separate plug-in UI descriptor file for a set of GUI extensions in support of this plug-in. The syntax of this plug-in UI descriptor file is described in Chapter 6, Plug-in User Interface Schema.

The <gui> element has one attribute, jarPath, that contains the path name to the plug-in UI descriptor file. The path name is relative to the root of the plug-in JAR file. Leading slash (/) or period (.) characters are not permitted in the jarPath.

<dependencyList> Element

The <dependencyList> element is a child of the <plugin> element and is used to declare a list of other plug-ins on which this plug-in depends. It has no attributes and contains one or more <pluginRef> elements that identify a dependency for this plug-in. When the plug-in is deployed, N1 Grid Service Provisioning System checks against these dependencies.

<pluginRef> Element

The <pluginRef> element is a child of the <dependencyList> element and is used to declare a reference to another plug-in. The <pluginRef> element has two required attributes:

• name – The name of the referenced plug-in. The name attribute has a maximum length of 64. Plug-in names follow a structure similar to com.sun.solaris.

• version – The minimum version of the referenced plug-in. The referenced plug-in must be installed on the system with this version or higher.

The <pluginRef> element contains no child elements.

<memberList> Element

The <memberList> element is a child of the <plugin> element and is used to declare a list of system objects that are part of this plug-in. These objects can appear in any order.

The <memberList> element has no attributes and contains at least one of the following child elements:

• <folder> – A folder declaration.

• <hostType> – A host type declaration.

• <hostSet> – A host set declaration.

• <hostSearch> – A host search declaration.

• <component> – A component declaration.

• <plan> – A plan declaration.

<folder> Element

The <folder> element is a child of the <memberList> element and is used to declare a folder to be referenced by the plug-in.

A plug-in can specify a folder to be created in the form of a full path name. For example, /a/b/c. In this example, a and b are interior folders, and c is a leaf folder. The plug-in owns the leaf folder. The admin group is listed as the folder owner group, and the folder is identified as being owned by the plug-in. A plug-in may only create components and plans in a folder that it owns. Users cannot create components, plans or subfolders in a plug-in owned folder.

If an interior folder does not exist when a plug-in is loaded, it is implicitly created. Interior folders may not be owned by a plug-in. The owner group for a plug-in created interior folder is the admin group, but the folder is not identified as belonging to any plug-in. If a plug-in author intends for interior folders to be explicitly owned by a plug-in, the folders should be created individually. In the above example, folder /a would be created first, followed by folder /a/b, then folder /a/b/c.

Unowned interior folders may not be created under an owned interior folder. This requirement prevents plug-in authors from creating components and plans in a folder between owned folders in the folder hierarchy, which would complicate the deletion semantics.

If an interior folder exists and is unowned when a plug-in is loaded, the interior folder is used directly. If an interior folder exists and is owned by a plug-in, the interior folder must be owned either by the current plug-in or by a plug-in on which the current plug-in has a direct dependency. This requirement enables multiple cooperative plug-ins to be distributed separately by a plug-in vendor. By obeying Java package style naming conventions when creating folders, vendors can avoid folder name space collisions.

<folder> Element Attributes

The <folder> element has two attributes:

• name – The path name of the folder.

• description (optional) – The description of the folder.

<hostType> Element

The <hostType> element is a child of the <memberList> element and is used to declare a host type to be referenced by the plug-in. The name of the host type will be implicitly prefixed with the plug-in name when the host type is created in the system.

<hostType> Element Attributes

The <hostType> element has two attributes:

• name – The name of the host type. The name attribute has a maximum length of 32. The name must begin with either a Unicode letter or an underscore character (_), followed by either Unicode letters, number, or an underscore character (_), dot (.), or dash (-).

• description (optional) – The description of the host type

<varlist> Element

The <hostType> element contains an optional <varlist> child element. The <varlist> element specifies a list of variables to be added to the <hostType> element and later used by hosts in configuration.

The <varlist> child element contains one or more <var> child elements. The <var> element provides <hostType> element variable declaration through two required attributes:

• name – The name of the variable

• default – The default value of the variable

<hostSet> Element

The <hostSet> element is a child of the <memberList> element and is used to declare a host set to be referenced by the plug-in. The <hostSet> element cannot contain hosts, since plug-ins cannot define hosts. Platform host sets cannot be defined by any plug-in other than the system plug-in. The name of the host set will be implicitly prefixed with the plug-in name when the host set is created in the system.

<hostSet> Element Attributes

The <hostSet> element has three attributes:

• name – The name of the host set. The name attribute has a maximum length of 32. The name must begin with either a Unicode letter or an underscore character (_), followed by either Unicode letters, number, or an underscore character (_), dot (.), or dash (-).

• description (optional) – The description of the host set.

• unsupported (optional) – If true, the host set is not supported. The default is false.

<hostSet> Element Child Elements

The <hostSet> element contains two optional child elements:

• <hostSetRef>

• <hostSearchRef>

<hostSetRef> Element

The <hostSetRef> element is a child of the <hostSet> element. It specifies a sub-host set. This host set must have been previously defined either in this plug-in or in a plug-in on which this plug-in directly depends. References to host sets defined in another plug-in must include the plug-in name, for example, com.foo.other#hostSetName. Unqualified references are assumed to be objects created by this plug-in.

The <hostSetRef> element has one attribute, name. This attribute provides the name of the host set reference. The name attribute has an optional pluginName that has a maximum length of 64, followed by a # separator, followed by a hostEntityName that has a maximum length of 32.

<hostSearchRef> Element

The <hostSearchRef> element is a child of the <hostSet> element. It specifies a sub-host search. This host search must have been previously defined either in this plug-in or in a plug-in on which this plug-in directly depends. References to host searches defined in another plug-in must include the plug-in name, for example, com.foo.other#hostSearchName. Unqualified references are assumed to be objects created by this plug-in.

The <hostSearchRef> element has one attribute, name. This attribute provides the name of the host search reference. The name attribute has an optional pluginName that has a maximum length of 64, followed by a # separator, followed by a hostEntityName that has a maximum length of 32.

<hostSearch> Element

The plug-in <hostSearch> element is a child of the <memberList> element and is used to declare a host search to be referenced by the plug-in. The name of the host search will be implicitly prefixed with the plug-in name when the host search is created in the system.

<hostSearch> Element Attributes

The <hostSearch> element has two attributes:

• name – The name of the host search. The name attribute has a maximum length of 32. The name must begin with either a Unicode letter or an underscore character (_), followed by either Unicode letters, numbers, or an underscore character (_), dot (.), or dash (-).

• description (optional) – The description of the host search

<hostSearch> Element Child Elements

The <hostSearch> element contains at least one of the following child elements:

• <criteriaList>

• <appTypeCriteria>

• <physicalCriteria>

---

Note –

Although the <criteriaList>, <appTypeCriteria>, and <physicalCriteria> elements are each optional, one of the three must be provided.

---

<criteriaList> Element

The <criteriaList> element is a child of the <hostSearch> element. It specifies a list of criteria to be added to the <hostSearch> element. The <criteriaList> element must be specified if <appTypeCriteria> and <physicalCriteria> are not specified.

The <criteriaList> element contains one or more <criteria> elements. The <criteria> element specifies a search criteria, including name, match type, and pattern. This element has three attributes:

• name – The name of the host variable to match.

• pattern – The pattern to match.

• match – The match type of the criteria. Valid values are EQUALS or CONTAINS. The default is EQUALS.

<appTypeCriteria> Element

The <appTypeCriteria> element is a child of the <hostSearch> element. It specifies a list of application type criteria to be added to the <hostSearch> element. The arguments of the <appTypeCriteria> element are expressed as attributes, and order is not important. If all values are false or the element is empty or unspecified, the search disregards this criteria when performing the search. The <appTypeCriteria> element must be specified if <criteriaList> and <physicalCriteria> are not.

The <appTypeCriteria> element has three optional attributes:

• ms – If true, match MasterServer application type in host search. The default is false.

• ld – If true, match LocalDistributor application type in host search. The default is false.

• ra –If true, match RemoteAgent application type in host search. The default is false.

<physicalCriteria> Element

The <physicalCriteria> element is a child of the <hostSearch> element. It specifies a list of physical type criteria to be added to the <hostSearch> element. The arguments of the <physicalCriteria> element are expressed as attributes, and order is not important. If all values are false or the element is empty or unspecified, the search disregards this criteria when performing the search. The <physicalCriteria> element must be specified if <criteriaList> and <appTypeCriteria> are not.

The <physicalCriteria> element has two optional attributes:

• physical – If true, match physical host types in host search. The default is false.

• virtual – If true, match virtual host types in host search. The default is false.

<component> Element

The <component> element is a child of the <memberList> element and is used to declare a component in the plug-in JAR file. All objects referenced by this component must have been previously defined either in this plug-in or in a plug-in on which this plug-in directly depends.

<component> Element Attributes

The <component> element has two attributes:

• jarPath – The location of the component XML file, relative to the root of the plug-in JAR (leading / or . characters are not permitted). The format of the component XML is specified by the Plan and Component Language specification. See Chapter 3, Component Schema for more information.

• majorVersion (optional) – Determines whether to check in the component as a new major version. The default is false.

<component> Element Child Elements

The <component> element contains three optional child elements:

• <systemService>

• <componentType>

• <resource>

<systemService> Element

The <systemService> element is a child of the <component> element and is used to declare a system service backed by the containing component. This element may not be used with the <componentType> element. When the <systemService> element is used in a <component> element, a component is loaded and a <systemServiceRef> that references that component is created. The name of the system service is prefixed with the plug-in name when the system service is created in the system.

The <systemService> element has two attributes:

• name – The name of the system service

• description (optional) – The description of the system service

<componentType> Element

The <componentType> element is a child of the <component> element and is used to declare a component type backed by the containing component. The <componentType> element may not be used with the <systemService> element. When the <componentType> element used in a <component> element, a component is loaded and a component type that is backed by that component is created. The name of the component type is prefixed with the plug-in name when the component type is created in the system.

Component types are grouped by plug-in, and ordered by the component type order within these groupings. Groupings are ordered according to the plug-in order. Within a particular plug-in, the component types are indented under distinct group names as defined by the component types.

The <componentType> element has five attributes:

• name – The name of the component type.

  A 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.

• description (optional) – The description of the component type.

• group – The group name of the component type, if this component type is part of a hierarchy of component types.

  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 displaying in the component type drop down list on the component list page.

• order – A number that identifies where to put this component type in the drop-down list of component types in the browser interface.

  The 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.

• indentlevel – A number between 0 and 10 that identifies the level to which to indent this component type in a hierarchy of component types in the browser interface.

<resource> Element

The <resource> element is a child of the <component> element. It specifies a resource file name and location in the JAR file. A resource is always checked in as a simple file-typed resource. The component that contains the <resource> element must be a simple component whose <resourceRef> element refers to the resource created by the <resource> element.

The <resource> element has three attributes:

• jarPath – The location of the resource file, relative to the root of the plug-in JAR file. Leading / or . characters are not permitted.

• majorVersion (optional) – Determines whether to check in the resource as a new major version. The default is false.

• name (optional) – The name of the resource. If not specified, the name will default to the absolute jarPath, which is converted to absolute if specified as relative

<plan> Element

The <plan> element is a child of the <memberList> element and is used to declare a plan in the plug-in JAR. All objects referenced by this plan must have been previously defined either in this plug-in or in a plug-in on which this plug-in directly depends.

<plan> Element Attributes

The <plan> element has two attributes:

• jarPath – The location of the plan XML, relative to the root of the plug-in JAR file. Leading / or . characters are not permitted. The format of the plan XML is specified by the Plan and Component Language specification. See Chapter 4, Plan Schema for more information.

• majorVersion (optional) – Determines whether to check in the plan as a new major version. The default is false.

Sample XML for <plugin> Element

---

Example 5–1 Sample Plug-in Descriptor File

<?xml version="1.0" encoding="UTF-8"?>
<plugin name="com.bigCo.logic.pluginName" 
        description="imitation WL plugin" 
        vendor="bigCo" 
        version="1.3"
        previousVersion="1.2"
        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">
     <readme jarPath="docs/readme.txt"/>
     <serverPluginJAR jarPath="lib/appserver/serverCode.jar"/>
     <gui jarPath="custom/weblogic/gui/pluginUI.xml"/>
     <dependencyList>
        <pluginRef name="webLogicUtils" version="1.0"/>
        <pluginRef name="otherPlugin" version="1.3"/>
     </dependencyList>
     <memberList>
        <folder name="/com/bea/weblogic/6.0" description="Weblogic 6.0 plugin folder"/>
        <folder name="/folder2" description="second place sees dust"/>
        <hostType name="WL Admin Server" description="Host Type for Weblogic Admin Servers">
           <varList>
               <var name="adminPort" default="7001"/>
               <var name="adminUser" default="weblogic"/>
               <var name="secureConnect" default="false"/>
           </varList>
        </hostType>
        <hostSet name="Weblogic Admin Servers" description="The Weblogic Admin Servers">
           <hostSetRef name="WL boxes"/>
           <hostSearchRef name="WL Admin Search"/>
        </hostSet>
        <hostSearch name="WL box search" description="matches Weblogic boxes">
           <criteriaList>
               <criteria name="sys.OS" match="CONTAINS" pattern="SunOS"/>
               <criteria name="sys.OSVersion" pattern="5.9"/>
           </criteriaList>
           <appTypeCriteria ms="false" ld="false" ra="true"/>
           <physicalCriteria physical="true" virtual="true"/>
        </hostSearch>
        <hostSet name="Weblogic Servers" description="All Weblogic Servers">
           <hostSetRef name="Weblogic Admin Servers"/>
           <hostSetRef name="com.bigCo.logic.cluster#Weblogic Clusters"/>
        </hostSet>
        <component jarPath="comps/system/weblogic/foo.xml" majorVersion="true">
           <componentType name="contained EJB CT" 
                     description="contained ejb comp type ref" 
                     group="hidden" 
                     order="001-003-002" 
                     indentLevel="2"/>
        </component>
        <component jarPath="weblogic/system/comps/bar.xml">
           <systemService name="WebLogic SS" description="WL service ref"/>
        </component>
        <component jarPath="weblogic/system/comps/baz.xml"/>
        <plan jarPath="weblogic/system/plans/bar.xml" majorVersion="false"/>
        <component jarPath="weblogic/system/comps/dee.xml">
           <resource jarPath="weblogic/system/plugin-core.jar" majorVersion="true"/>
        </component>
  </memberList>
</plugin>

---