<transform> Step

The <transform> step is used to perform a text-based transformation to a file on the target host. Currently, the provisioning system supports Perl-type and XSLT-based transformations.

If the output file exists on the target host before the transformation, the permissions and ownership of the file are preserved. However, if the output file is new, it inherits the default RA permissions.

The <transform> child elements specify the transformation to be applied to the input file. The child elements can be any one of the following elements:

• A single <stylesheet> element that defines the XSLT transformation to apply to the input source

• One or more <subst> elements that define Perl-like substitution patterns to apply sequentially to the input source

• A single <source> element that names the external file that contains the transformation

• Empty, which means that the contents of the input file are copied directly to the output file

  You might use an empty element to extract from or write to zip archive files.

Attributes for the <transform> Step

The <transform> step has the following attributes:

• input – An optional attribute that is the generalized path of the file on the target host on which to apply the transformation. If this attribute is omitted, input is read from the output file. This attribute can reference simple substitution variables.

• output – A required attribute that is the generalized path of the file on the target host to which to write the result of the transformation. This attribute can reference simple substitution variables.

The input and output attributes can reference the same or distinct files. The value of these attributes is a generalized path that can include zip archives or zip derivatives, such as JAR, as directory elements. For example, a path might be webapp/myapp.jar/config.xml.

<stylesheet> Element

The <stylesheet> element is a child of the <transform> step. This element specifies an XSLT transformation to apply to the input source. At most one <stylesheet> element can appear as a child of a particular <transform> element. You cannot use the <stylesheet> element in conjunction with other child elements.

The <stylesheet> element is an XSLT Version 1.0 element as defined by the http://www.w3.org/1999/XSL/Transform name space. For more information, see Version 1.0 of the XSL Transformations (XSLT) specification at http://www.w3.org/TR/xslt.html. Only the XSLT <stylesheet> element is accepted as a child of the <transform> element. In particular, neither the XSLT synonym <transform> nor the simplified XSLT transform syntax described in Section 2.3 of the XSLT specification is supported as a child of the <transform> element.

The <stylesheet> element body can include substitution variable references if the body is still a valid XSLT without first undergoing variable substitution.

When a <stylesheet> element is used as a transformation, the input file must be written in XML. For more information, see Version 1.0 of the XSL Transformations (XSLT) specification.

Example 2–4 Using the <stylesheet> Element

This transformation changes each a to a b in the /etc/hosts file. The hosts file is overwritten with these changes.

<transform output="/etc/hosts">
    <xsl:stylesheet version="1.0"
      xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
        <xsl:template match="/">
            <xsl:for-each select="a">
                <xsl:value-of select="b"/>
            </xsl:for-each>
        </xsl:template>
    </xsl:stylesheet>
</transform>

<subst> Element

The <subst> element is a child of the <transform> step. This element specifies a Perl-like substitution pattern to apply as a transformation. One or more <subst> elements can appear as children of the <transform> element, but they cannot be used in conjunction with other child elements. When more than one <subst> element appears, they are applied sequentially.

All occurrences of the pattern in the input file are replaced, including multiple occurrences on a line.

For information about the supported syntax, see Java documentation (class java.util.regex.Pattern).

Attributes for the <subst> Element

The <subst> element has the following attributes:

• match – A required attribute that is a case-sensitive Perl-like regular expression that is sought after in the input. This attribute can reference simple substitution variables.

• replace – A required attribute that is a Perl-like replacement value that is substituted for each occurrence of the pattern given by match. This value is not interpreted verbatim: the $n construct is interpreted as the nth parenthetical expression inside the matching expression. This attribute can reference simple substitution variables.

Example 2–5 Using the <subst> Element

The following transformation converts all occurrences of the string 127.0.0.xxx to 10.10.0.xxx in the /etc/hosts file:

<transform output=”/etc/hosts”>
    <subst match="127\.0\.0\.(\d+)"
    replace="10.10.0.$1"/>
</transform>

<source> Element

The <source> element is a child of the <transform> step. This element specifies an external file on the target host that contains the transformation to be applied to the input file. At most one <source> element can appear as a child of a particular <transform> element. You cannot use the <source> element in conjunction with other child elements.

Configuration generation is not performed on the specified source file as part of the <transform> step. However, the specified source file can be a config-type resource file that is deployed as part of a component installation. In such as case, substitution variables that are contained in the source file would have been substituted when the file was deployed.

Attributes for the <source> Element

The <source> element has the following attributes:

• type – A required element that is the type of transformation that is contained in the specified file. The following values are permitted:

  • PERL – A Perl-like transformation that is similar to that of the <subst> element. In this case, the format of the specified file should be similar to the following format:

    <?xml version='1.0'?> <transform> <subst match="127\.0\.0\.(\d+)" replace="10.10.0.$1"/> </transform>

    Perl-type external transformation files can contain any number of <subst> elements.

  • XSLT – An XSLT transformation. In this case, the specified file contains a standard XSLT Version 1.0 transformation as defined by the name space http://www.w3.org/1999/XSL/Transform. Unlike inline transformations, which only permit the XSLT <stylesheet> element, XSLT transformations that are contained in external source files can include any valid top-level XSLT transformation element. Such elements are <stylesheet>, <transform>, and simplified XSLT syntax. The simplified XSLT syntax is described in Section 2.3 of the XSLT specification.

• name – A required attribute that is the name of the file on the target host that contains the transformation. The contents of the file must correspond to the type defined by the type attribute. The name cannot include zip archives as directory elements. This attribute can reference simple substitution variables.