Tips and tricks for deployment packages

This topic provides some helpful tips and tricks to use when managing deployment packages.

Overriding default artifact comparison

When XL Deploy imports a package, it creates a checksum for each artifact in the package. The checksum property on an artifact is a string property and can contain any string value. It is used during an upgrade to determine whether the content of an artifact CI in the new package differs from the artifact CI in the previous package. If you include information in an artifact that changes on every build, such as a build number or build timestamp, the checksum will be different when the contents of the artifact has not changed.

In this scenario, it can be useful to override the XL Deploy-generated checksum and provide your own inside your package. Here is an example of an artifact CI with its own checksum:

<jee.Ear name="AnimalZooBE" file="AnimalZooBE-1.0.ear">
  <checksum>1.0</checksum>
</jee.Ear>

Using the above artifact definition, if the EAR file itself is different, XL Deploy will consider the EAR file unchanged as long as it has value 1.0 for the checksum property.

Specifying encoding for files in artifacts

By default, if a Byte Order Mark (BOM) is present, XL Deploy will try to detect the encoding for files. If it is not, XL Deploy will fallback to the platform encoding of Java. To ensure that these files are kept in their correct encoding while running them through the placeholder replacement, you can specify the encoding in the fileEncodings artifact property. This property maps regular expressions matching the full path of the file in the artifact to a target encoding.

For example, the following files are in a file.Folder artifact:

  • web-content/en-US/index.html
  • web-content/nl-NL/index.html
  • web-content/zh-CN/index.html
  • web-content/ja-JP/index.html

If you want the Chinese and Japanese index pages to be treated as UTF-16BE, and the others to be treated as UTF-8, you can specify this in the manifest as follows:

<file.Folder name="webContent" file="web-content">
  <fileEncodings>
    <entry key=".+(en-US|nl-NL).+">UTF-8</entry>
    <entry key=".+(zh-CN|ja-JP).+">UTF-16BE</entry>
  </fileEncodings>
</file.Folder>

XL Deploy will use these encodings when replacing placeholders in these files.

Important: To support this functionality, you must first update the synthetic.xml to make the hidden property <fileEncodings> not hidden.

<type-modification type="udm.BaseDeployableArtifact">
<property name="fileEncodings" hidden="false" kind="map_string_string"/>
</type-modification>

Note: By changing this property for udm.BaseDeployableArtifact, it will appear for all artifacts. For example, you can choose to only make it visible to file.File types by changing the first line to <type-modification type="file.File">:

<type-modification type="file.File">
<property name="fileEncodings" hidden="false" kind="map_string_string"/>
</type-modification>

Specifying encoding for files in artifacts using the UI

As of version 9.5.3, you can also specify the encoding from the UI using a key/value pair. The keys are regular expressions that are matched against file names in the deployable. If there is a match, then the value belonging to that key tells you which character encoding such as UTF-8, ISO-8859-1, should be used for the file.

To specify the type of encoding to the deployable using the CI Explorer:

  1. Import the DAR file
  2. Go to Placeholders section in the file properties
  3. Under File Encoding, there are two columns, viz. key and value
  4. In key field, specify the file type. For example .+\.xml for XML files
  5. In the value field, specify the type of encoding for the file after the deployment

The image below uses the ISO-8859-1 encoding as an example:

Encoding

See Placeholders for using placeholders in deployment.

See alsoEnabling placeholder scanning and Disabling placeholder scanning