File Plugin Manual 4.0.x

Preface

This document describes the functionality provided by the File Plugin.

Refer to the XL Deploy Reference Manual for background information on XL Deploy and deployment concepts.

Overview

In many cases, an application depends on external resources for its configuration. The application accesses these resources from a predefined location or using a predefined mechanism.

In the simplest of forms, a resource can be described as a file, an archive (ZIP)or a folder (collection of files). The File Plugin enables the definition of such resources in a deployment package and subsequently managing them on a target host.

The resources can contain placeholders that the plugin will replace when targeting to the specific host, thus allowing resources to be defined independent of their environment.

Features

Deploy, upgrade, and undeploy of a file based resource on a Host.

Requirements

This plugin requires:

  • XL Deploy: version 4.0+

Usage in Deployment Packages

Please refer to Packaging Manual for more details about the DAR packaging format.

Sample DAR manifest entries defining a file, folder and archive resource

<udm.DeploymentPackage version="1.0" application="FilePluginSample">
    <file.File name="sampleFile" file="sampleFile.txt"/>
    <file.Archive name="sampleArchive" file="sampleArchive.zip" />
    <file.Folder name="sampleFolder" file="sampleFolder" />
</udm.DeploymentPackage>

Using the deployables and deployeds

Deployable vs. Container Table

The following table describes which deployable / container combinations are possible. Note that the CIs can only be targeted to containers derived from Host.

Deployables Containers Generated Deployed
file.File
file.Archive
overthere.Host file.DeployedFile
file.DeployedArchive
file.Folder overthere.Host file.DeployedFolder

Deployed Actions Table

The following table describes the effect a deployed has on its container.

DeployedCreate Destroy Modify
file.DeployedFile
file.DeployedArchive
  • Create target path on host, if needed
  • Copy file to target path on host
  • Delete file from host
  • Delete old file from host
  • Copy modified file to target path on host
file.DeployedFolder
  • Create target folder on host, if needed
  • Copy folder content to target folder on host
  • Delete folder content from host
  • If folder is not a shared folder, the folder itself is deleted from host
  • Perform actions as described by Destroy for old folder
  • Perform actions as described by Create for modified folder

CI Reference

Configuration Item Overview

Deployables

CI Description
file.Archive An archive artifact that can be packaged in a Deployment Package
file.File A single file artifact that can be packaged in a Deployment Package
file.Folder A folder artifact that can be packaged in a Deployment Package

Deployeds

CI Description
file.DeployedArchive The archive as deployed on the Host
file.DeployedArtifactOnHost Abstract deployed that can target any DeployableArtifact to a Host
file.DeployedFile The file as deployed on the Host
file.DeployedFolder The folder as deployed on the Host

Other Configuration Items

CI Description
file.Archive An archive artifact that can be packaged in a Deployment Package
file.DeployedArchive The archive as deployed on the Host
file.DeployedArtifactOnHost Abstract deployed that can target any DeployableArtifact to a Host
file.DeployedFile The file as deployed on the Host
file.DeployedFolder The folder as deployed on the Host
file.File A single file artifact that can be packaged in a Deployment Package
file.Folder A folder artifact that can be packaged in a Deployment Package

Configuration Item Details

file.Archive

Type Hierarchy udm.BaseDeployableArchiveArtifact >> udm.BaseDeployableFileArtifact >> udm.BaseDeployableArtifact >> udm.BaseDeployable >> udm.BaseConfigurationItem
Interfaces udm.Taggable, udm.Deployable, udm.SourceArtifact, udm.ArchiveArtifact, udm.Artifact, udm.DeployableArtifact, udm.ConfigurationItem, udm.FileArtifact

An archive artifact that can be packaged in a Deployment Package

Public Properties
 
 
checksum : STRING
The checksum used to detect differences on the artifact. If not provided, it will be calculated by XL Deploy.
 
 
createTargetPath : STRING
Create the targetPath on the host if it does not exist.
 
 
excludeFileNamesRegex : STRING
Regular expression that matches file names that must be excluded from scanning
 
 
placeholders : SET_OF_STRING
Placeholders detected in this artifact
 
 
scanPlaceholders : BOOLEAN  = false
Whether to scan this artifact for placeholders when it is imported
 
 
tags : SET_OF_STRING
If set, this deployable will only be mapped automatically to containers with the same tag.
 
 
targetFileName : STRING
Name of the artifact on the host.
 
 
targetPath : STRING
Path to which artifact must be copied to when being deployed.
 
 
targetPathShared : STRING
Is the targetPath shared by others on the host. When true, the targetPath is not deleted during undeployment; only the artifacts copied to it.
Hidden Properties
 
 
textFileNamesRegex : STRING  = .+\.(cfg | conf | config | ini | properties | props | txt | asp | aspx | htm | html | jsf | jsp | xht | xhtml | sql | xml | xsd | xsl | xslt)
Regular expression that matches file names of text files
 
 
delimiters : STRING  = {{ }}
The delimiters used indicate placeholders, defaults to '{{ }}'. This is a 5 character string with a space in the middle, the first two are the leading delimiter, the last two are the closing delimiter
 
 
fileEncodings : MAP_STRING_STRING  = {.+\.properties=ISO-8859-1}
A map that maps regular expressions matching the full path of file(s) in the artifact to character set encodings

file.DeployedArchive

Type Hierarchy file.DeployedArtifactOnHost >> udm.BaseDeployedArtifact >> udm.BaseDeployed >> udm.BaseConfigurationItem
Interfaces udm.EmbeddedDeployedContainer, udm.Artifact, udm.Deployed, udm.ConfigurationItem, udm.DerivedArtifact

The archive as deployed on the Host.

Parent
 
 
container : CI<udm.Container>
The container on which this deployed runs.
Public Properties
 
 
targetPath : STRING
Path to which artifact must be copied to on the host.
 
 
createTargetPath : BOOLEAN  = false
Create the targetPath on the host if it does not exist.
 
 
deployable : CI<udm.Deployable>
The deployable that this deployed is derived from.
 
 
placeholders : MAP_STRING_STRING
A Map containing all the placeholders mapped to their values. Special values are <ignore> or <empty>
 
 
targetFileName : STRING
Name of the artifact on the host.
 
 
targetPathShared : BOOLEAN  = true
Is the targetPath shared by others on the host. When true, the targetPath is not deleted during undeployment; only the artifacts copied to it.
Hidden Properties
 
 
copyDirectlyToTargetPath : BOOLEAN  = false
If set to true, files are directly copied to the target directory without first being uploaded to the staging or temporary directory (like versions of XL Deploy prior to 4.0.0)
 
 
targetPathSharedSubDirectories : BOOLEAN  = false
The sub directories on the target machine are not deleted if files other than that copied by XL Deploy are present.

file.DeployedArtifactOnHost

Virtual Type
Type Hierarchy udm.BaseDeployedArtifact >> udm.BaseDeployed >> udm.BaseConfigurationItem
Interfaces udm.EmbeddedDeployedContainer, udm.Artifact, udm.Deployed, udm.ConfigurationItem, udm.DerivedArtifact

Abstract deployed that can target any DeployableArtifact to a Host.

Parent
 
 
container : CI<udm.Container>
The container on which this deployed runs.
Public Properties
 
 
targetPath : STRING
Path to which artifact must be copied to on the host.
 
 
createTargetPath : BOOLEAN  = false
Create the targetPath on the host if it does not exist.
 
 
deployable : CI<udm.Deployable>
The deployable that this deployed is derived from.
 
 
placeholders : MAP_STRING_STRING
A Map containing all the placeholders mapped to their values. Special values are <ignore> or <empty>
 
 
targetFileName : STRING
Name of the artifact on the host.
 
 
targetPathShared : BOOLEAN  = true
Is the targetPath shared by others on the host. When true, the targetPath is not deleted during undeployment; only the artifacts copied to it.
Hidden Properties
 
 
copyDirectlyToTargetPath : BOOLEAN  = false
If set to true, files are directly copied to the target directory without first being uploaded to the staging or temporary directory (like versions of XL Deploy prior to 4.0.0)
 
 
targetPathSharedSubDirectories : BOOLEAN  = false
The sub directories on the target machine are not deleted if files other than that copied by XL Deploy are present.

file.DeployedFile

Type Hierarchy file.DeployedArtifactOnHost >> udm.BaseDeployedArtifact >> udm.BaseDeployed >> udm.BaseConfigurationItem
Interfaces udm.EmbeddedDeployedContainer, udm.Artifact, udm.Deployed, udm.ConfigurationItem, udm.DerivedArtifact

The file as deployed on the Host.

Parent
 
 
container : CI<udm.Container>
The container on which this deployed runs.
Public Properties
 
 
targetPath : STRING
Path to which artifact must be copied to on the host.
 
 
createTargetPath : BOOLEAN  = false
Create the targetPath on the host if it does not exist.
 
 
deployable : CI<udm.Deployable>
The deployable that this deployed is derived from.
 
 
placeholders : MAP_STRING_STRING
A Map containing all the placeholders mapped to their values. Special values are <ignore> or <empty>
 
 
targetFileName : STRING
Name of the artifact on the host.
 
 
targetPathShared : BOOLEAN  = true
Is the targetPath shared by others on the host. When true, the targetPath is not deleted during undeployment; only the artifacts copied to it.
Hidden Properties
 
 
copyDirectlyToTargetPath : BOOLEAN  = false
If set to true, files are directly copied to the target directory without first being uploaded to the staging or temporary directory (like versions of XL Deploy prior to 4.0.0)
 
 
targetPathSharedSubDirectories : BOOLEAN  = false
The sub directories on the target machine are not deleted if files other than that copied by XL Deploy are present.

file.DeployedFolder

Type Hierarchy file.DeployedArtifactOnHost >> udm.BaseDeployedArtifact >> udm.BaseDeployed >> udm.BaseConfigurationItem
Interfaces udm.EmbeddedDeployedContainer, udm.Artifact, udm.Deployed, udm.ConfigurationItem, udm.DerivedArtifact

The folder as deployed on the Host.

Parent
 
 
container : CI<udm.Container>
The container on which this deployed runs.
Public Properties
 
 
targetPath : STRING
Path to which artifact must be copied to on the host.
 
 
createTargetPath : BOOLEAN  = false
Create the targetPath on the host if it does not exist.
 
 
deployable : CI<udm.Deployable>
The deployable that this deployed is derived from.
 
 
placeholders : MAP_STRING_STRING
A Map containing all the placeholders mapped to their values. Special values are <ignore> or <empty>
 
 
targetPathShared : BOOLEAN  = true
Is the targetPath shared by others on the host. When true, the targetPath is not deleted during undeployment; only the artifacts copied to it.
Hidden Properties
 
 
copyDirectlyToTargetPath : BOOLEAN  = false
If set to true, files are directly copied to the target directory without first being uploaded to the staging or temporary directory (like versions of XL Deploy prior to 4.0.0)
 
 
targetFileName : STRING
Not applicable for this type.
 
 
targetPathSharedSubDirectories : BOOLEAN  = false
The sub directories on the target machine are not deleted if files other than that copied by XL Deploy are present.

file.File

Type Hierarchy udm.BaseDeployableFileArtifact >> udm.BaseDeployableArtifact >> udm.BaseDeployable >> udm.BaseConfigurationItem
Interfaces udm.Taggable, udm.Deployable, udm.SourceArtifact, udm.Artifact, udm.DeployableArtifact, udm.ConfigurationItem, udm.FileArtifact

A single file artifact that can be packaged in a Deployment Package

Public Properties
 
 
checksum : STRING
The checksum used to detect differences on the artifact. If not provided, it will be calculated by XL Deploy.
 
 
createTargetPath : STRING
Create the targetPath on the host if it does not exist.
 
 
excludeFileNamesRegex : STRING
Regular expression that matches file names that must be excluded from scanning
 
 
placeholders : SET_OF_STRING
Placeholders detected in this artifact
 
 
scanPlaceholders : BOOLEAN  = true
Whether to scan this artifact for placeholders when it is imported
 
 
tags : SET_OF_STRING
If set, this deployable will only be mapped automatically to containers with the same tag.
 
 
targetFileName : STRING
Name of the artifact on the host.
 
 
targetPath : STRING
Path to which artifact must be copied to when being deployed.
 
 
targetPathShared : STRING
Is the targetPath shared by others on the host. When true, the targetPath is not deleted during undeployment; only the artifacts copied to it.
Hidden Properties
 
 
textFileNamesRegex : STRING  = .+\.(cfg | conf | config | ini | properties | props | txt | asp | aspx | htm | html | jsf | jsp | xht | xhtml | sql | xml | xsd | xsl | xslt)
Regular expression that matches file names of text files
 
 
delimiters : STRING  = {{ }}
The delimiters used indicate placeholders, defaults to '{{ }}'. This is a 5 character string with a space in the middle, the first two are the leading delimiter, the last two are the closing delimiter
 
 
fileEncodings : MAP_STRING_STRING  = {.+\.properties=ISO-8859-1}
A map that maps regular expressions matching the full path of file(s) in the artifact to character set encodings

file.Folder

Type Hierarchy udm.BaseDeployableFolderArtifact >> udm.BaseDeployableArtifact >> udm.BaseDeployable >> udm.BaseConfigurationItem
Interfaces udm.Taggable, udm.Deployable, udm.SourceArtifact, udm.Artifact, udm.DeployableArtifact, udm.ConfigurationItem, udm.FolderArtifact

A folder artifact that can be packaged in a Deployment Package

Public Properties
 
 
checksum : STRING
The checksum used to detect differences on the artifact. If not provided, it will be calculated by XL Deploy.
 
 
createTargetPath : STRING
Create the targetPath on the host if it does not exist.
 
 
excludeFileNamesRegex : STRING
Regular expression that matches file names that must be excluded from scanning
 
 
placeholders : SET_OF_STRING
Placeholders detected in this artifact
 
 
scanPlaceholders : BOOLEAN  = true
Whether to scan this artifact for placeholders when it is imported
 
 
tags : SET_OF_STRING
If set, this deployable will only be mapped automatically to containers with the same tag.
 
 
targetPath : STRING
Path to which artifact must be copied to when being deployed.
 
 
targetPathShared : STRING
Is the targetPath shared by others on the host. When true, the targetPath is not deleted during undeployment; only the artifacts copied to it.
Hidden Properties
 
 
textFileNamesRegex : STRING  = .+\.(cfg | conf | config | ini | properties | props | txt | asp | aspx | htm | html | jsf | jsp | xht | xhtml | sql | xml | xsd | xsl | xslt)
Regular expression that matches file names of text files
 
 
delimiters : STRING  = {{ }}
The delimiters used indicate placeholders, defaults to '{{ }}'. This is a 5 character string with a space in the middle, the first two are the leading delimiter, the last two are the closing delimiter
 
 
fileEncodings : MAP_STRING_STRING  = {.+\.properties=ISO-8859-1}
A map that maps regular expressions matching the full path of file(s) in the artifact to character set encodings
 
 
targetFileName : STRING
Not applicable for this type (deprecated).