# File Plugin Manual 4.0.3

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

- File
- Folder
- Archive

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

Deployed | Create | 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

### Deployeds

### Other Configuration Items

## 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).