Component level sdd.xml file

The install-paa task parses the PAA directory tree, and for each component directory, verifies there is an sdd.xml file. If not found, one is generated using the information gathered from the directory parsing step.

The Solution Installer uses the data gathered about the resource types included in the Portal Application Archive (PAA) file. It also uses the component directory name to generate the sdd.xml file.

For many situations, this automated step is enough to allow the PAA files to be deployed successfully. There are situations where the developer needs to overwrite the functionality of Solution Installer as the auto-generated code does not meet their requirements for a specific resource type.

In addition, there might be configuration steps that are not covered directly by the Solution Installer code generation that need to be included in the PAA file for the application to be successfully deployed and configured on the server. This article outlines the different pieces of the component level sdd.xml file in terms of their usage by the Solution Installer. In addition, steps on how to create our own custom sdd.xml file and where to include relevant information on the component for successful deployment are also included.

If we are providing a component level sdd.xml file, you do not need to provide information for all the resources included in the PAA file. Provide information where we are not using the Solution Installer generated code. Also include information for steps that are not covered by the Solution Installer. If resources in the PAA file are still relying on the default code, the Solution Installer adds the relevant pieces to the sdd.xml file in addition to the elements included by the developer.

Example component level sdd.xml file...

<?xml version="1.0" encoding="UTF-8"?>

<iudd:iudd
 xmlns:iudd="http://www.ibm.com/xmlns/prod/autonomic/solutioninstall/IUDD"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:OSRT="http://www.ibm.com/xmlns/prod/autonomic/resourcemodel/OS/resourcetypes"
 xmlns:OSAT="http://www.ibm.com/xmlns/prod/autonomic/resourcemodel/OS/artifacttypes"
 xmlns:J2EERT="http://www.ibm.com/xmlns/prod/autonomic/resourcemodel/J2EE/resourcetypes"
 xsi:schemaLocation="http://www.ibm.com/xmlns/prod/autonomic/solutioninstall/IUDD ../iudd/iudd.xsd"
 schemaVersion="2.0.0" buildID="112220" buildDate="2006-01-19T12:00:00">

 <packageIdentity contentType="Component">
  <name>components/componentN</name>
  <version>8.0.0.0</version>
  <displayName key="d0001" default="components/componentN" />
  <manufacturer>
   <displayName key="AC_01" default="IBM" />
  </manufacturer>
 </packageIdentity>

 <topology>
  <resource type="OSRT:OperatingSystem" id="OS" />
 </topology>

 <content xsi:type="iudd:RootIUContent">
  <rootIU id="components/componentN">
   <variables>
    <parameters>
     <parameter name="installLocation" defaultValue="/usr/dummy.offr.1" />
    </parameters>
   </variables>

   <SCU id="deploy-portlets-applySIFeaturePack" targetRef="OS">
    <identity>
     <name>Do Configuration Task</name>
     <version>8.0.0.0</version>
     <displayName key="keyInBundle"
      default="Executes Configuration for this component" />
     <description key="keyInBundle"
      default="This section runs configuration for this component" />
    </identity>
    <unit>
     <configArtifact type="ConfigEngine">
      <parameters>
       <parameter name="targetName" value="deploy-portlets-applySIFeaturePack" />
      </parameters>
     </configArtifact>
    </unit>
   </SCU>
   <SCU id="remove-portlets-applySIFeaturePack" targetRef="OS">
    <identity>
     <name>Do Configuration Task</name>
     <version>1.0.0.0</version>
     <displayName key="keyInBundle"
      default="Executes Configuration for this component" />
     <description key="keyInBundle"
      default="This section runs configuration for this component" />
    </identity>
    <unit>
     <configArtifact type="ConfigEngine">
      <parameters>
       <parameter name="targetName" value="remove-portlets-applySIFeaturePack" />
      </parameters>
     </configArtifact>
    </unit>
   </SCU>
  </rootIU>
 </content>

</iudd:iudd>

Inside the root <iudd:iudd> element the following three important sub-elements are required for installation with the Solution Installer:

• The first element is the <packageIdentity> element; for example:

   <packageIdentity contentType="Component">
    <name>components/componentN</name>
    <version>8.1.0.0</version>
    <displayName key="d0001" default="components/componentN" />
    <manufacturer>
     <displayName key="AC_01" default="IBM" />
    </manufacturer>
   </packageIdentity>
  

  The <packageIdentity> element informs Solution Installer and the ConfigEngine of the type of application to be installed. In this case, the contentType attribute equals "component". A component is the lowest level of granularity used by the ConfigEngine and thus Solution Installer for grouping application resources. One or more components are grouped together in an assembly. This grouping is the next level of granularity for grouping resources recognized by the ConfigEngine or the Solution Installer. Each PAA file is considered by Solution Installer as an assembly, even though it might only contain one component. In the case of the PAA file, a component must have a higher level assembly associated with it. See "The assembly level sdd.xml file" for additional information.

  If you look at the <packageIdentity> element there are a number of sub elements that provide information on the content being installed. The <name> and <version> element need to be altered to suit the application being installed. The <displayName> element can also be edited to include the component name but is not required.

  It is importand that the <name> element must equal the path of the component relative to the assembly level sdd.xml file.

  For example, as the PAA file puts all components in the ‘components’ directory, a component name needs to also include the ‘components/’.

  For example a component called ‘componentN’ would have a component name of ‘components/componentN’.

• The next subelement is the <topology> element. This element does not require any alterations.

  For example:

   <topology>
    <resource type="OSRT:OperatingSystem" id="OS" />
   </topology>
  

• The final element block is the <content> element. This element provides the Solution Installer and the ConfigEngine with the information on what is being installed and on which servers the package can be installed on. The <rootIU> element is where the actual information is included. You should set the id attribute of the <rootIU> element to the name of the component as used in the <name> element of the <packageIdentity> element.

  For example:

   <content xsi:type="iudd:RootIUContent">
    <rootIU id="components/componentN">
     <variables>
      <parameters>
       <parameter name="installLocation" defaultValue="/usr/dummy.offr.1" />
      </parameters>
     </variables>
  
     <SCU id="deploy-portlets-applySIFeaturePack" targetRef="OS">
      <identity>
       <name>Do Configuration Task</name>
       <version>1.0.0.0</version>
       <displayName key="keyInBundle"
        default="Executes Configuration for this component" />
       <description key="keyInBundle"
        default="This section runs configuration for this component" />
      </identity>
      <unit>
       <configArtifact type="ConfigEngine">
        <parameters>
         <parameter name="targetName" value="deploy-portlets-applySIFeaturePack" />
        </parameters>
       </configArtifact>
      </unit>
     </SCU>
    </rootIU>
   </content>
  

  The ConfigEngine requires the <variables> element for processing the content. You should not need to edit this section. Just include it in the component level sdd.xml file per the previous example.

  The <scu> element is the element of the file which is of most relevance to adding custom code to the PAA file. Each <scu> element represents a ConfigEngine extension point. These extension points govern how and when resources are installed or uninstalled on the server during the deploy-paa task. Each extension point has an equivalent implementation task which needs to be added to a .xml file in the components/componentN/config/includes directory. See ConfigEngine extension points for the Solution Installer for a list of exported extensions and how they map to directories. For details on extension points and how they are used, see Component level sdd.xml file overview.

  In the previous example, there are two places where you should make changes. The first place is the id attribute of the <scu> element. The ID should be set to the name of the required extension point with the applySIFeaturePack appended to the end.

  For example: deploy-apps-applySIFeaturePack. The second to change is the nested <parameter> element. The value attribute of this element should also be set to the extension point string. In this case set it to deploy-apps-applySIFeaturePack.

  For each extension point to implement, provide a separate <scu> element. Therefore an additional <scu> element would be required to provide an equivalent remove-apps-removeSIFeaturePack extension.

  There is a second and rather important role assigned to the <scu> element. These elements also influence the order in which components are installed. You might have a PAA file with two components, where the second component is installed prior to the first component. A mechanism is necessary to ensure that the correct order is imposed on the deployment. This action can be done by adding a <requirements> element to the <scu> element :

  <SCU id="deploy-portlets-applySIFeaturePack" targetRef="OS">
    <identity>
      <name>Do Configuration Task</name>
      <version>1.0.0.0</version>
      <displayName key="keyInBundle" default="Executes Configuration for this component" />
      <description key="keyInBundle" default="This section runs configuration for this component" />
    </identity>
    <unit>
      <configArtifact type="ConfigEngine">
        <parameters>
          <parameter name="targetName" value="deploy-portlets-applySIFeaturePack" />
        </parameters>
      </configArtifact>
    </unit>
  <!—register a dependency on a previous component-->
  <requirements>
  <requirement name=" deploy-portlets-applySIFeaturePack">
  <alternative name="dependentComponent"/>
  </requirement>
  </requirements>
  </SCU>
  

  The <requirements> element can contain one or more <requirement> elements, each one representing a component on which the current component depends on being previously installed. The name attribute of the <requirement> element can be set to whatever value the developer chooses. The name attribute of the <alternative> element must equal the full name of the component on which the current extension point depends. The dependency link is between extension points. If we add the <requirements> element to the <scu> element for the 'deploy-apps-applySIFeaturePack', register an equivalent 'deploy-apps-applySIFeaturePack' extension point for the dependent component.

Parent: Develop advanced solution applications