Document Properties
Kbid
2573Q2
Last Modified
02-Feb-2023
Added to KB
17-Apr-2014
Public Access
Everyone
Status
Online
Doc Type
References
Product
  • Gradle Tools
  • ICM 7.10
Reference - Gradle Deployment Tools

Table of Contents


Introduction

This reference covers Intershop's DSL for the Gradle based deployment. It targets developers that need to configure or extend the deployment.

This reference assumes that you are familiar with:

Useful entry points of this document are:


Deep Links and Gradle Versions

This document describes Intershop's Deployment Tools in different versions. Information that applies only to a certain version of the tools is clearly marked as such.

Also the document contains deep links into the Gradle's documentation. For technical reasons they always point to Gradle version 1.8. For Deployment Tools version >= 2.0, please refer to the Gradle Build Language Reference and Javadoc for Gradle version 2.0 instead. Mostly it is enough to substitute the version number in the URL, e.g., change:

http://www.gradle.org/docs/1.8/dsl/org.gradle.api.Task.html

into

http://www.gradle.org/docs/2.0/dsl/org.gradle.api.Task.html

Glossary


PhraseMeaning
Version Control System (VCS)

Also known as source control, source code management systems (SCM), or revision control systems (RCS). VCS is a mechanism for keeping multiple versions of your files, so that when you modify a file you can still access the previous revisions.

Artifact Repository

Place, where build and package software components are located. Provide a common interface to a dependency management system.

Code AnalysisProcess to analyze source code to calculate metrics, find bugs, etc.
Continuous Delivery PipelineSometimes called Deployment Pipeline, describes the stages, which code artifacts runs through source to production system.
System ComponentA software package of different code artifacts and files, that have to be deployed together.
System Component SetIs a container for system components, that needs to be build and branched together.
AssemblyAn assembly references one or more system components residing in the same or a configured artifact repository in order to deploy or deliver them together.
Build ProcessCompiles and packages files and code artifacts from a source project to deployable artifacts.
Publish ProcessThe process which transfers the deployable artifacts to a configured artifact repository.
Assembly ProcessThis process combines several system components to an assembly.
Deployment ProcessThis process extracts files and code artifacts from an artifact repository and applies the configuration.
Project Gradle DistributionThis is a customized Gradle distribution with the preconfigured artifact repositories and Gradle plugins.
Gradle PluginA Gradle plugin packages up reusable pieces of build logic, which can be used across many different projects and builds.
Project Gradle PluginThis is a Gradle plugin which contains special corporate respectively project settings.
Corporate PluginThe term is used as a synonym for Project Gradle Plugin.
Gradle Extension ObjectJava Bean compliant class holding configurations for Gradle plugins.
Gradle WrapperThe Gradle Wrapper is the preferred way of starting a Gradle build. The wrapper is a batch script on Windows, and a shell script for other operating systems. When you start a Gradle build via the wrapper, Gradle will be automatically downloaded and used to run the build. See for more information The Gradle Wrapper in the Gradle documentation (2.11, 2.7, 2.3, 2.0, 1.8)
Intershop ClusterA number of hosts of different types serving an Intershop 7.
Cluster NodeOne separately deployable part of an Intershop cluster. A host can run multiple nodes of one Intershop cluster.

Settings Plugins

Settings, not a Project plugin

Note that these classes are Settings plugins, not Project plugins, because subsequently loaded scripts/plugins may influence Gradle's multiproject structure.

Plugin com.intershop.deploy.bootstrap.DeploymentBootstrapPlugin  

Applied in a settings.gradle script to turn a Gradle multi-project build into a deployment based on a given assembly.

The plugin attaches the  DeploymentBootstrapExtension as property deploymentBootstrap to the Settings object.

The DeploymentBootstrapPlugin only performs a minimal initialization (bootstrap), necessary to load 'deploy-settings-gradle' script of an assembly. It then hands over to this script for the actual deployment process.

See DeploymentBootstrapExtension for details.

Plugin com.intershop.deploy.bootstrap.AssemblyDeploymentSettingsPlugin

Declare subprojects of the deployment based on the dependencies of the assembly and loads assembly and component deployment scripts. Typically applied in a 'deploy-settings-gradle' script of an assembly.

This plugin adds the configurations property and several methods to the DeploymentBootstrapExtension when applied. See its listing of methods and properties.

When applied the plugin:

  1. Calculates all components contained as dependencies in these configurations of the assembly.
  2. For each component:
    1. Creates a subproject with the name of the component.
    2. If the component has an artifact of type 'deploy-gradle', assigns this script as Gradle build script.
    3. Adds an extra property self to the Project containing the resolved component version as ModuleVersionIdentifier.
  3. Assigns the assembly's artifact of type 'deploy-gradle' as Gradle build script to the root project.

Plugin com.intershop.deploy.settings.HostTypeSettingsPlugin

Determines assembly configurations to be deployed based on host type and environment. Typically applied in a 'deploy-settings-gradle' script of an assembly.

The HostTypeSettingsPlugin automatically applies the AssemblyDeploymentSettingsPlugin. It augments the the DeploymentBootstrapExtension (property deploymentBootstrap on the Settings object):

  • It attaches the HostTypeExtension as property hostType.
  • It sets the property configurations based on the selected host type and environment.

Also it propagates the flags includeLocal, includeShare and includeCartridges from the selected HostType to the TargetExtension of the root project (if the TargetPlugin is applied to the root project).

Project Plugins

Plugin com.intershop.deploy.resources.ResourceDeploymentPlugin

The ResourceDeploymentPlugin is the core plugin of the deployment. Most other deployment plugins uses its DSL to fulfill their purpose.

Allows to deploy files, links, directories and permissions (resources). The plugin keeps an index over all deployed resources, so it can determine which files have changed compared to the previously deployed version and can also remove obsolete files. It also allows to modify the content of deployed files through content filters and handle modifications outside the deployment. 

The ResourceDeploymentPlugin attaches the ResourceDeploymentExtension as property deployment to the Project. Based on the declarations made in the ResourceDeploymentExtension, tasks for deploying resources is created. See ResourceDeploymentExtension for details.

Plugin com.intershop.deploy.intershop.AppserverDeploymentPlugin

Allows to provide Intershop 7 nodemanager or appserver configuration for the project it is applied to. It attaches the AppserverExtension as property appserver to the Project and provides sensible defaults for this extension, see there.

If you apply this plugin to the root project and to a child project, all values of the root project's AppserverExtension are propagated to the AppserverExtension of the child project by default. You can still overwrite them for the child project only.

Plugin com.intershop.deploy.intershop.AssemblyShareDeploymentPlugin

Extracts all artifacts of the assembly of Ivy artifact type 'share' to IS_SHARE. To do so it creates a FileDeployment with name share in the ResourceDeploymentExtension.

Plugin com.intershop.deploy.intershop.CartridgeListDeploymentPlugin

Generates the <IS_SHARE>/system/cartridges/cartridgelist.properties file. It sets three properties:

The cartridges are sorted in the same order as they appear in the assembly's ivy.xml file.

Plugin com.intershop.deploy.intershop.ConfigureCartridgesPlugin

Applies the CartridgeDeploymentPlugin to all projects representing a cartridge. This way the great majority of cartridges doesn't have to ship with a deployment script.

Cartridges are all components of the environment selected at the HostTypeExtension plus all init-only-cartridges (see Concept - Gradle Assembly Tools ).

A component that is contained in this set, but has a custom deploy script (as found by the AssemblyDeploymentSettingsPlugin), the CartridgeDeploymentPlugin is not applied.

Plugin com.intershop.deploy.intershop.DatabaseDeploymentPlugin

Modifies <IS_SHARE>/system/config/cluster/orm.properties and <IS_SHARE>/system/config/oracle/tnsnames.ora to match the database settings provided in the DatabaseExtension.

Applies the DatabasePlugin.

Plugin com.intershop.deploy.intershop.DatabasePlugin

Allows to provide database connection configuration for the project it is applied to. It attaches the DatabaseExtension as property database to the Project.

If you apply this plugin to the root project and to a child project, all values of the root project's DatabaseExtension are propagated to the DatabaseExtension of the child project by default. You can still overwrite them for the child project only.

Plugin com.intershop.deploy.intershop.DeployDatabaseDumpPlugin

Deploys an an artifact of type Ivy artifact type 'dump' to IS_HOME/tools/misc/database.dmp. To do so it creates a FileDeployment with name databaseDump in the ResourceDeploymentExtension.

Plugin com.intershop.deploy.intershop.DeveloperDeploymentPlugin

Adds a task 'deployCartridges', which allows to selectively deploy a set of cartridges.

If the extra project property cartridges is set, it is expected to contain a white-space separated list of cartridge names. If set, only these cartridges are redeployed.

If the property is not set, all cartridges specified in the property sourceCartridges of the DeveloperExtension are deployed.

Plugin com.intershop.deploy.intershop.DeveloperPlugin

Allows to provide configuration only needed at development time. It attaches the DeveloperExtension as property developer to the Project and provides sensible defaults for this extension, see there.

If you apply this plugin to the root project and to a child project, all values of the root project's DeveloperExtension are propagated to the DeveloperExtension of the child project by default. You can still overwrite them for the child project only.

Plugin com.intershop.deploy.intershop.EnvironmentConfigurationPlugin

Copies the value of property environment of the HostTypeExtension to <IS_SHARE>/system/config/cluster/environment.properties. This way the configuration framework uses the same name for the current environment as the deployment.

Plugin com.intershop.deploy.intershop.IntershopPlugins

Applies a set of standard Intershop plugins. (Does nothing except for applying other plugins.) Applying IntershopPlugins has the same effect as the following code fragment:

import com.intershop.deploy.intershop.*
import com.intershop.deploy.assembly.AssemblyDeploymentPlugin
apply plugin: AssemblyDeploymentPlugin
apply plugin: AssemblyShareDeploymentPlugin
apply plugin: AppserverDeploymentPlugin
apply plugin: DatabaseDeploymentPlugin
apply plugin: ConfigureCartridgesPlugin
apply plugin: CartridgeListDeploymentPlugin
apply plugin: IvyDeploymentDatePlugin
apply plugin: DeployDatabaseDumpPlugin
apply plugin: LicenseDeploymentPlugin
apply plugin: EnvironmentConfigurationPlugin
apply plugin: MulticastDeploymentPlugin
apply plugin: WebAdapterDeploymentPlugin
apply plugin: DeveloperPlugin
apply plugin: DeveloperDeploymentPlugin
apply plugin: StagingDeploymentPlugin
// additionally in Gradle tools >= 2.0
apply plugin: com.intershop.deploy.encryption.EncryptionAdminPlugin
apply plugin: com.intershop.deploy.encryption.EncryptionDeploymentPlugin
apply plugin: SSLBoxDeploymentPlugin
apply plugin: WebAdapterConfigurationPlugin

To apply only a subset of these plugins, do not apply IntershopPlugins, but instead use this code fragment and modify it accordingly.

Plugin com.intershop.deploy.intershop.IvyDeploymentDatePlugin

Deploys the assembly's ivy.xml file to <IS_SHARE>/ivy.xml and <IS_HOME>/ivy.xml and writes the current date into the deployment attribute of the info element. To do so it creates FileDeployment with the name <name of IS_SHARE directory>Ivy and <name of IS_SHARE directory>Ivy in the ResourceDeploymentExtension.

Note that the deployment-date in the ivy.xml files is only updated on full deployments or if the task deploy <name of IS_SHARE directory>IvyFiles, resp. deploy <name of IS_HOME directory>IvyFiles is executed.

Plugin com.intershop.deploy.intershop.LicenseDeploymentPlugin

Deploys a license file to <IS_SHARE>/system/license/license.xml. Declare the source of the license in the LicenseExtension. Applies the LicensePlugin.

Plugin com.intershop.deploy.intershop.LicensePlugin

Allows to configure the source of a license file. It attaches the LicenseExtension as property license to the Project.

Plugin com.intershop.deploy.intershop.MulticastDeploymentPlugin

Applies multicast configuration provided in the MulticastExtension to configuration files in <IS_SHARE>/system/config/cluster.

Applies the MulticastPlugin.

Plugin com.intershop.deploy.intershop.MulticastPlugin

Allows to provide multicast configuration for the project it is applied to. It attaches the MulticastExtension as property multicast to the Project.

If you apply this plugin to the root project and to a child project, all values of the root project's MulticastExtension are propagated to the MulticastExtension of the child project by default. You can still overwrite them for the child project only.

Plugin com.intershop.deploy.intershop.SolrPlugin

This plugin is newly introduced with Gradle Tools 2.0.

The plugin allows to provide a solr cluster configuration for the project it is applied to. It attaches the  SolrExtension as property solr to the Project.

Plugin com.intershop.deploy.intershop.SolrDeploymentPlugin

Since Gradle Tools 2.0, this plugin also applies SolrPlugin.

Configures ac_search_solr to connect to a Solr server deployed in the outer tomcat of an Intershop 7 application server. It also disables the creation of search indices during DBInit.

Plugin com.intershop.deploy.intershop.StagingDeploymentPlugin

Sets the staging type in <IS_SHARE>/system/config/cluster/staging.properties and deploys a provided replication-clusters.xml for edit systems. Provide the configuration for this plugin in the StagingExtension.

Applies the StagingPlugin.

Since Gradle Tools 2.0, this plugin will perform additional configuration for live systems:

  • Stageable content from <IS_SHARE>/sites/*/1 will also be deployed to <IS_SHARE>/sites/*/2.
  • A modification handling strategy for both <IS_SHARE>/sites/*/[1,2], as well as the associated *.active file will be created to keep the deployment from overwriting replicated content.

Plugin com.intershop.deploy.intershop.StagingPlugin

Allows to provide staging configuration for the project it is applied to. It attaches the StagingExtension as property staging to the Project.

If you apply this plugin to the root project and to a child project, all values of the root project's StagingExtension  are propagated to the StagingExtension of the child project by default. You can still overwrite them for the child project only.


Plugin com.intershop.deploy.intershop.WebAdapterDeploymentPlugin

Allows to provide Apache and Web Adapter configuration for the project it is applied to. It attaches the WebadapterDeploymentExtension as property webadapter to the Project.

If you apply this plugin to the root project and to a child project, all values of the root project's WebAdapterDeploymentExtension are propagated to the WebAdapterDeploymentExtension  of the child project by default. You can still overwrite them for the child project only.

Plugin com.intershop.deploy.intershop.WebAdapterConfigurationPlugin

This plugin is newly introduced with Gradle Tools 2.0.

This plugin applies the WebAdapterDeploymentPlugin and filters the IS_SHARE/system/config/cluster/webadapter.properties according to the settings in WebadapterDeploymentExtension.

Plugin com.intershop.deploy.intershop.SSLBoxDeploymentPlugin

This plugin is newly introduced with Gradle Tools 2.0.

In case the property useSSLBox has been set on WebadapterDeploymentExtension, this plugin modifies the webserver's httpd.conf and the Web Adapter's webadapter.properties files to configure usage of an external SSL box for transport security. SSL box specific webserver configuration is deployed as a new file httpd-sslbox.conf.

Plugin com.intershop.deploy.intershop.TomcatPlugin

This plugin is newly introduced with Gradle Tools 2.0.

The plugin allows to provide configuration about the tomcat servlet containers. It attaches the  TomcatExtension as property tomcat to the Project.

Plugin com.intershop.deploy.assembly.AssemblyDeploymentPlugin

Provides overall deployment tasks and configurations. It attaches the AssemblyDeploymentExtension  as property assemblyDeployment to the Project. See chapter Task Instances.

The AssemblyDeploymentPlugin also creates Javadoc index page and provides stylesheets, based on the values configured at the DeveloperExtension.

Plugin com.intershop.deploy.assembly.TargetPlugin

Allows to provide configuration about the target system and locations. It attaches the TargetExtension as property target to the Project.

If you apply this plugin to the root project and to a child project, all values of the root project's TargetExtension are propagated to the TargetExtension of the child project by default. You can still overwrite them for the child project only.

Plugin com.intershop.deploy.cartridge.CartridgeDeploymentPlugin

Deploys a cartridge. It attaches the CartridgeDeploymentExtension as property cartridgeDeployment to the Project.

The CartridgeDeploymentPlugin adds the following FileDeployment objects using the ResourceDeploymentExtension:

NameContentsDestination
jarall artifacts of Ivy artifact type 'jar'<property cartridgesDirectory of CartridgeDeploymentExtension>/<cartridge>/release/lib
shareall artifacts of Ivy artifact type 'share'

<property shareDirectory of CartridgeDeploymentExtension>

ivythe ivy.xml file of the cartridge<property cartridgesDirectory of CartridgeDeploymentExtension> <cartridge>/release/lib
cartridgeall artifacts of Ivy artifact type 'cartridge'<property cartridgesDirectory of CartridgeDeploymentExtension>
javadocall artifacts of Ivy artifact type 'javadoc'<property javadocDirectory of CartridgeDeploymentExtension>

Plugin com.intershop.deploy.infrastructure.InfrastructureDeploymentPlugin

Deploys an infrastructure component. It adds the following FileDeployment objects using the ResourceDeploymentExtension:

NameContentsDestination
localall artifacts of Ivy artifact type 'local' whose Ivy classifier matches the property platform of the TargetExtension <property localDirectory of TargetExtension>
shareall artifacts of Ivy artifact type 'share'

<property shareDirectory of TargetExtension>

Plugin com.intershop.deploy.encryption.EncryptionAdminPlugin

This plugin is newly introduced with Gradle Tools 2.0.

This plugin can be used within a deployment, but also in a pre-deployment stage outside in separate Gradle script. See the Recipe: Configure Encryption in Cookbook - Gradle Deployment Tools.

Applies the EncryptionPlugin.

Plugin com.intershop.deploy.encryption.EncryptionDeploymentPlugin

This plugin is newly introduced with Gradle Tools 2.0.

Deploys encryption configuration files into IS_SHARE. To do so it creates FileDeployment with the name encryptionConfig in the ResourceDeploymentExtension. See EncryptionExtension on how to configure it.

Applies the EncryptionPlugin.

Plugin com.intershop.deploy.encryption.EncryptionPlugin

This plugin is newly introduced with Gradle Tools 2.0.

Allows to provide database connection configuration for the project it is applied to. It attaches the EncryptionExtension as property encryption to the Project.

Extensions

Extension com.intershop.deploy.bootstrap.DeploymentBootstrapExtension

Extension to configure which assembly gets deployed. Attached by the DeploymentBootstrapPlugin as property deploymentBootstrap to Gradle's Settings object.

The DeploymentBootstrapExtension needs to be configured by:

  1. Calling the repositories method to specify repositories for finding the assembly.
  2. Calling the assembly method to specify which assembly to deploy and trigger the rest of the deployment process (see details below).

Configuring Repositories outside a Gradle Project

Since - differing from Gradle's Project objects - the Gradle's Settings object has no RepositoryHandler , ConfigurationContainer and DependencyHandler associated with it, there is no easy way to resolve dependencies from the repositories in Gradle's initialization phase. The DeploymentBootstrapExtension has properties of these types that can be used for this purpose. (The DeploymentBootstrapExtension makes use of these properties itself to resolve the assembly.)

Example extension usage in settings.gradle script
deploymentBootstrap {
	repositories {
		ivy {
			url "http://repo.mycompany.com/repo"
		}
	}

	assembly('com.mycompany.assembly:shop') {
		hostType {
			hostType 'appserver'
			environment 'production'
		}
	}

	config {
		// configure the root project in any way
		ext.someInstallationMetaData = 'text'
	}
}

During Gradle's configuration phase the DeploymentBootstrapExtension is also available as an extra property deploymentBootstrap of the root project. This allows to access information specified in the initialization phase, e.g., the assembly to be deployed or the host type and environment, in the configuration phase, e.g., in the assembly's or the component's deploy scripts.

Example extension usage in 'deploy-gradle' script of assembly
if (deploymentBootstrap.hostType.hostType.name == 'appserver') {
	// configure something specific to appserver deployment
}

Properties

TypeProperty NameDescriptionDefault value
RepositoryHandler
repositoryHandlerRepository handler for declaring repositories to be used during deployment (read-only)
ConfigurationContainer configurationContainerConfiguration container that can be used to resolve dependencies during deployment in Gradle's initialization phase (read-only)
DependencyHandler dependencyHandlerDependency handler that can be used to resolve dependencies during deployment in Gradle's initialization phase (read-only)
ModuleVersionIdentifier assemblyModuleIdResolved version of the assembly to be deployed. Only set after the calling the assembly method or after the initialization phase (read-only)

Properties added by the AssemblyDeploymentSettingsPlugin

TypeProperty NameDescriptionDefault value
List<String> or Closure configurations

Ivy configurations of the assembly. All components inside these configurations are deployed. If a closure it must yield a List<String>.

Set it in the closure passed to the assembly method. Set by the HostTypeSettingsPlugin if applied.

['default']

Properties added by the HostTypeSettingsPlugin

TypeProperty NameDescriptionDefault value
HostTypeExtension hostTypeExtension for selecting host type and environment to deploy (read-only)

Methods

Return TypeMethod NameDescription
voidrepositories(Action<? super RepositoryHandler> configure)

Declares the repositories for finding the assembly. These repository declarations are also propagated further to find components to be deployed and deployment plugins.

Parameters:

configure- Configures a RepositoryHandler. See Gradle user guide on Dependency Management or Gradle DSL documentation on RepositoryHandler for details on how to declare repositories inside this closure.

voidassembly(dependencyNotation, Closure closure = null)

Loads a given assembly for deployment. Call only once per Gradle execution. Declare Repositories via the  repositories method first.  

This includes the following steps:

  1. Resolve the assembly from the repository and set the property assemblyModuleId to the resolved version
  2. Validate that the JDK and Gradle  are compatible to the assembly if declared
  3. Load an artifact of type  deploy-settings-gradle from the assembly and execute it against the  Settings object. This script controls the rest of the deployment process - typically by applying the  AssemblyDeploymentSettingsPlugin.
  4. Configure the "deploymentBootstrap" extension with the given closure if given

Resolves the ivy.xml file of a given assembly and creates a subprojects in the Gradle multi-project build according to it.

Parameters:

dependencyNotation- An object that is a valid Gradle dependency notation, see DependencyHandler. Only external dependencies are supported.

closure- Configures this instance of the DeploymentBootstrapExtension, i.e. the scope does not change. That you can pass in a closure here is just a matter of timing: It is executed after the assembly's deploy-settings-gradle script was executed, which may extend the  DeploymentBootstrapExtension to allow specification of subsets. (Like by applying the AssemblyDeploymentSettingsPlugin.) Optional

voidconfig(Closure closure)

Configures the root projectof the multi-project build. The closure is evaluated in Gradle's afterProject hook. This is triggered immediately after the 'deploy-gradle' script of the assembly, but before the 'deploy-gradle' scripts of components have been evaluated.

This is a convenience method typically used inside settings.gradle deployment scripts to configure the deployment.

Parameters:

closure- Configures the root project.

Methods added by the AssemblyDeploymentSettingsPlugin

Return TypeMethod NameDescription
List<Project> projectsInConfigurations(Collection<String> configurationsToSelect, Closure<?> configureClosure = null)

Retrieves a list of projects that were created from dependencies in given configurations of the deployed assembly by the AssemblyDeploymentSettingsPlugin.

Since these are projects this – differing from the componentsInConfigurations method – only includes components also selected for deployment.

The order in the returned list is the order as declared in the assembly's ivy.xml file.

Parameters:

configurationsToSelect - Names of configurations of the assembly to select dependencies from.

configureClosure- An optional closure to configure the retrieved projects.

List<Project> projectsInConfiguration(String configurationToSelect, Closure<?> configureClosure = null)Shortcut for calling projectsInConfigurations method with a single configuration.
List<ModuleVersionIdentifier>

componentsInConfigurations(Collection<String> configurationsToSelect)

Retrieves a list of components contained as dependencies in given configurations of the deployed assembly.

Differing from the  projectsInConfigurations method, components are returned even if they were not selected for deployment.

The order in the returned list is the order as declared in the assembly's ivy.xml file.

Parameters:

configurationsToSelect - Names of configurations of the assembly to select dependencies from. 

List<ModuleVersionIdentifier> componentsInConfiguration(String configurationToSelect)Shortcut for calling componentsInConfigurations method with a single configuration.

Extension com.intershop.deploy.settings.HostTypeExtension

Extension object to select host type and environment to be deployed. Can also be used to query host types and environments available in the assembly.

It is created by the HostTypeSettingsPlugin and attached to the DeploymentBootstrapExtension (property deploymentBootstrap) on the Settings object as property  hostType.

Properties

TypeProperty NameDescriptionDefault value
HostType hostTypeSelected host type.
Environment environmentSelected environment.

Map<String, Environment>

environmentsAll environments available in the assembly, keyed by their name. (read-only and immutable)
Map<String, HostType> hostTypesAll host types available in the assembly, keyed by their name. (read-only and immutable)
List<String>configurationsConfigurations of the assembly that are selected for deployment based on the selected host type and assembly. (read-only and immutable)

Methods

Return TypeMethod NameDescription
HostType hostType(String hostTypeName)

Selects the host type by the given name for deployment and returns it. Only existing host types are allowed.

Parameters:

hostTypeName - Name of the host type to select.

Environment

environment(String environmentName)

Selects the environment by the given name for deployment and returns it. Only existing environments are allowed.  

Parameters:

environmentName - Name of the environment to select.

Extension com.intershop.deploy.resources.ResourceDeploymentExtension

Extension to configure deployment of resources. Resources are files, links, directories, services and permissions. Attached to the Project by the ResourceDeploymentPlugin as property deployment.

For each type of resources the  ResourceDeploymentExtension has a NamedDomainObjectContainer to configure which resources should be deployed and how. Each of the contained domain objects may represent one ore more resources (like a set of files extracted from the same archive). The names of the contained domain objects can be chosen freely (there are no strict connections, like between the name of a file to deploy and the name of the FileDeployment declaring its deployment).

Example extension usage in settings.gradle file
...
deploymentBootstrap {...
	config {...
		deployment {
			files {     
				// set of additional script files to be deployed
		        additionalScripts {
                   from new File('/opt/install/additional-scripts')         
                   into new File(target.localDirectory, 'bin')
                }
            }
			
			filters {
				// inside the script files replace all occurences of @ADDITIONAL_RESOURCE_DIRECTORY@ by some directory
				replacePlaceholders('scriptFilePlaceholders') {
		        	dir = new File(target.localDirectory, 'bin')
		            include '*.sh'
		            placeholders['ADDITIONAL_RESOURCE_DIRECTORY'] = '/opt/resources'
		        }
			}	
		}
	}
}

Properties

TypeProperty NameDescriptionDefault value
NamedDomainObjectContainer<FileDeployment>files

Sets of files to be created and filled by the deployment (read-only)

For each FileDeployment in this container a corresponding DeployFiles task is created, using the naming convention  deploy<name of FileDeployment>Files. Also there is an overall task deployFiles per project depending on all those single tasks.


NamedDomainObjectContainer<LinkDeployment>links

Symbolic links to be created by the deployment (read-only)

A single task deployLinks per project creates all symbolic links.


NamedDomainObjectContainer<DirectoryDeployment>directories

Directories to be created by the deployment (read-only)

A single task deployDirectories per project creates all directories.


NamedDomainObjectContainer<PermissionDeployment>permissions

POSIX file modes to be applied to a file or directory (read-only)

A single task deployPermissions per project applies all permissions. The task does nothing, if the file or operating system does not support POSIX permissions (like the ACL based NTFS on Windows).


ServiceDeploymentContainer services

Windows services and linux init.d-scripts to be deployed (read-only)

The ServiceDeploymentContainer contains two containers, one for WindowServiceDeployment and one for LinuxServiceDeployment domain objects.

For each service a corresponding DeployWindowsServiceTask resp. DeployLinuxServiceTask is created, using the naming convention deploy<name of the WindowServiceDeployment/LinuxServiceDeployment>. Tasks are only created for services matching the current platform. Also there is a an overall task deployServices per project depending on all those single tasks.

Services won't be created during the deployment itself, because this requires administrator/root privileges. Instead the tasks DeployWindowsServiceTask   and DeployLinuxServiceTask  just create a batch/shell script to be executed after the deployment with administrator/root privileges.


ExtensiblePolymorphicDomainObjectContainer<ModificationHandler>modification

Determines how to handle modification of deployed files by non-deployment processes (read-only)

See section Methods of the modification Property for additional methods that are available inside the modification handler container.


ExtensiblePolymorphicDomainObjectContainer<DeploymentContentFilter>filters

Content filters to be applied during the deployment of files (e.g., replace placeholder, overwrite properties etc.) (read-only)

See section Methods of the filters Property for additional methods that are available inside the filters container.


Stringuser

Name of the user that should own the resulting files. The deployment must be executed with this user.


String userGroup Name of a user group of that user. Used for processes (like the Apache) that allow to configure a group for execution.n.a.
FilepostInstallDirectoryPost install directory to collect files and shell/batch scripts for post install process.<directory of settings.gradle>/postinstall
List<String>modificationPriorities

An ordered list of priority levels for modification handling. Levels that are listed later are preferred over levels listed earlier.

['default']

Methods

Return TypeMethod NameDescription
ArtifactFileTree artifacts(Map<String, Object> params = null, Closure<?> closure = null)

Creates a Gradle FileTree containing Ivy artifacts of the component associated with the current project (resp. their content if the artifacts are archives). The resulting ArtifactFileTree can be configured further by passing in a Map and/or a closure.

The return value is typically passed to the from method of a FileDeployment to deploy these files.

Parameters:

params – Entries of this map are set as properties on the resulting ArtifactFileTree. Optional.

closure – Closure used to configure the resulting ArtifactFileTree. Optional.

Methods of the filters Property

The filters property has the following additional methods for easy creation of common filters:

Return TypeMethod NameDescription
OverridePropertiesFilter overrideProperties(String name, Closure configureClosure)

Creates a filter for overriding properties and adds it to the filters container.

Parameters:

name – Name of the filter. 

configureClosure – Closure used to configure the resulting OverridePropertiesFilter.

PlaceholderReplacementFilter replacePlaceholders(String name, Closure configureClosure)

Creates a filter for replacing placeholders and adds it to the filters container.

Parameters:

name – Name of the filter.

configureClosure – Closure used to configure the resulting PlaceholderReplacementFilter.

XmlContentFilter xmlContent(String name, Closure configureClosure)

Creates a filter for manipulating XML files and adds it to the filters container.

Parameters:

name – Name of the filter.

configureClosure – Closure used to configure the resulting XmlContentFilter.

EditLinesFilter editLines(String name, Closure configureClosure)

Creates a filter which can perform arbitrary manipulation on a line-by-line basis and adds it to the filters container.

Parameters:

name – Name of the filter.

configureClosure – Closure used to configure the resulting EditLinesFilter.

FullContentFilter fullContent(String name, Closure configureClosure)

Creates a filter which can perform arbitrary manipulation on the full text content of a file and adds it the the filters container.

Parameters:

name – Name of the filter.

configureClosure – Closure used to configure the resulting FullContentFilter.

Methods of the modification Property

The modification property has the following additional methods for easy creation of common modification handlers:

Return TypeMethod NameDescription
OverwriteModificationHandler overwrite(String name, Closure configureClosure)

Creates a modification handler that overwrites modified files and issues a warning.

Parameters:

name – Name of the handler. 

configureClosure – Closure used to configure the resulting OverwriteModificationHandler.

KeepModificationHandler keep (String name, Closure configureClosure)

Creates a modification handler that keeps modified files and ignores new content/state to be deployed and issues a warning.

Parameters:

name – Name of the handler. 

configureClosure – Closure used to configure the resulting KeepModificationHandler.

AbortModificationHandler abort(String name, Closure configureClosure)

Creates a modification handler that aborts the deployment process in case of a modified files without altering it.

Parameters:

name – Name of the handler. 

configureClosure – Closure used to configure the resulting AbortModificationHandler.

BackupModificationHandler backup(String name, Closure configureClosure)

Creates a modification handler that renames modified files by appending -backup, -backup1-backup2 etc.

Parameters:

name – Name of the handler. 

configureClosure – Closure used to configure the resulting BackupModificationHandler.

Extension com.intershop.deploy.intershop.AppserverExtension

Extension to configure Intershop 7 nodemanager and appserver instances. Attached to the Project by the AppserverDeploymentPlugin as property appserver.

Properties

TypeProperty NameDescriptionDefault value
String configPath

Parent directory to the appserver specific property file appserver<n>.properties. The value may contain the following placeholders:

    • ${IS_HOME} – replaced by the the value of property localDirectory of the TargetExtension
    • ${IS_SHARE}– replaced by the the value of property shareDirectory of the TargetExtension
    • ${IS_NET_ADRESS} – replaced by the resolved host name of the host specified by property hostname
    • ${IS_INSTALLATION} – replaced by "ES" followed by the value of property instanceId of the TargetExtension

The <IS_SHARE>/system/config/cluster/configuration.xml is adapted, so the configuration framework reads the appserver specific property files from this location.

The new default value places the appserver specific property file on the host of the appserver node itself, making it possible to add an appserver without touching the shared file system.

You may revert to the legacy location on the shared filesystem of this file by using the value:

${IS_SHARE}/system/config/servers/${IS_NET_ADDRESS}/${IS_INSTALLATION}

${IS_HOME}/config
StringhostnameHost name of the appserver.'localhost' if property hostType of the HostTypeExtension is 'all', otherwise no default.
StringwebserverHostHost name of the front end webserver (a Web Adapter or a load balancer). Used for generating URLs in response pages.Value of property hostname of WebadapterExtension
IntegerwebserverPortTCP port of the front end webserver for HTTP communication. Used for generating URLs in response pages.Value of property port of WebadapterExtension
IntegerwebserverSecurePortTCP port of the front end webserver for HTTPS communication. Used for generating URLs in response pages.Value of property securePort of WebadapterExtension
StringnodemanagerNetworkInterface

IP4-Address of network interface for the nodemanager to listen for JMX communication.

Deprecated since Gradle Tools 2.0: use TomcatExtension.nodemanagerNetworkInterface instead.

127.0.0.1
IntegernodemanagerJmxPort

TCP port for the nodemanager to listen for JMX communication.

Deprecated since Gradle Tools 2.0: use TomcatExtension.nodemanagerJmxPort instead.

n.a.
NamedDomainObjectContainer <Appserver>instances

Collection of Appserver objects to declare appserver instance specific configuration. An appserver instance is created for each object in this collection (read-only)

Since Gradle Tools 2.0 this collection will automatically create appropriate objects for TomcatExtension.instances with the extension AppserverTomcatExtension attached.


Extension com.intershop.deploy.intershop.TomcatExtension

This extension is newly introduced with Gradle Tools 2.0.

Extension to configure tomcat instances for Intershop 7. Attached to the Project by the TomcatPlugin as property  tomcat.

Properties

TypeProperty NameDescriptionDefault value
StringnodemanagerNetworkInterfaceIP4-Address of network interface for the nodemanager to listen for JMX communication127.0.0.1
intnodemanagerJmxPortTCP port for the nodemanager to listen for JMX communicationn.a.
NamedDomainObjectContainer< TomcatServer> instances Collection of TomcatServer objects to declare tomcat server instancesn.a.

Extension com.intershop.deploy.intershop.DatabaseExtension

Extension to configure database connection. Attached to the Project by the DatabasePlugin as property database.

Properties

TypeProperty NameDescriptionDefault value

String

host Host of the database server.n.a.
intportTCP port of the database server.n.a.
StringsidOracle System ID. Prefer to use the Service Name instead since Gradle tools version 2.0
n.a.
StringserviceNameOracle Service Name. Available since Gradle tools version 2.0.n.a.
StringtnsAliasAddress name for this connection used in Oracle's tnsnames.ora file.n.a.
StringuserDatabase user account.n.a.
Stringpassword

Database user password.

In plain text, in Gradle tools version < 2.0, or if passwordIsEncrypted is false. In encrypted form if Gradle tools version >= 2.0 and with passwordIsEncrypted set to true.

n.a.
booleanpasswordIsEncryptedDetermines whether the password is encrypted. Available since Gradle tools version 2.0.false
FileoracleClientDir

Path to oracle client. The path is checked for an existing directory.

n.a.

Extension com.intershop.deploy.intershop.DeveloperExtension

Extension to provide configuration only needed in a development environment. Attached to the Project by the DeveloperPlugin as property  developer.

Properties

TypeProperty NameDescriptionDefault value

List<File>

sourceDirectories List of IS_SOURCE directories to look up source cartridges (component set directories).Empty list.
List<String> sourceCartridges List of cartridges to be treated as source cartridges by the application server.Empty list.
booleanincludeJavadocIn order to deploy Javadoc at all.

true if the selected host type includes Javadoc (e.g., hostType property of the HostTypeExtension is 'javadoc' or 'all') and the selected environment is 'development'

false, otherwise

FilejavadocDirectoryRoot directory to deploy Javadoc into.<IS_SHARE>/javadoc

Extension com.intershop.deploy.intershop.LicenseExtension

Extension to provide a license file. Attached to the Project by the LicensePlugin as property  license.

Properties

TypeProperty NameDescriptionDefault value
FilelicenseFile

Path to the license.xml file. The path is checked for an existing file.

n.a.

Extension com.intershop.deploy.intershop.MulticastExtension

Extension to configure multicast connections required by Intershop 7 clusters. Attached to the Project by the MulticastPlugin as property  multicast.

Until Gradle tools version 1.0:

The properties in this extension reflect properties read by the configuration framework:

  • Extension properties with the prefix appserver result in Intershop 7 properties with the prefix 'intershop.event'. See   Cookbook - Messaging for details.
  • Extension properties with the prefix cache result in Intershop 7 properties with the prefix 'intershop.cacheengine.wrapped'.
  • Extension properties with the prefix tcm result in Intershop 7 properties with the prefix 'intershop.tcm.event'. See Reference - Configuration (ES6 and IS7), file tcm.properties.

Gradle tools version >= 1.1:

Every multicast channel used is represented by a separate property of type MulticastMessenger. See section 'properties' below.

Properties

Until Gradle tools version 1.0:

TypeProperty NameDescriptionDefault value
String appserverMulticastAddress IP address for broadcasting appserver events.n.a.
int appserverMulticastPort Private port for broadcasting appserver events.n.a.
String appserverMulticastInterface IP adress of network interface to use for broadcasting appserver events. (Only required if multiple interfaces are available.) null
String cacheMulticastAddress IP address for broadcasting cache events.n.a.
int cacheMulticastPort Private port for broadcasting cache events.n.a.
String cacheMulticastInterface IP adress of network interface to use for broadcasting cache events. (Only required if multiple interfaces are available.) null
String tcmMulticastAddress IP address for broadcasting events between TCCs and nodemanagers.n.a.
int tcmMulticastPort Private port for broadcasting events between TCCs and nodemanagers.n.a.
String tcmMulticastInterface IP adress of network interface to use for broadcasting events between TCCs and nodemanagers. (Only required if multiple interfaces are available.) null

Gradle tools version >= 1.1:

TypeProperty NameDescriptionDefault value
MulticastMessenger tcm

Multicast configuration for Tomcat Cluster Manager + node manager (read-only)

Results in properties with the prefix 'intershop.tcm.event'. See Reference - Configuration (ES6 and IS7), file tcm.properties


MulticastMessenger appserver

Multicast configuration for appserver events (read-only)

Results in Intershop 7 properties with the prefix 'intershop.cacheengine.wrapped. See  Cookbook - Messaging for details.


MulticastMessenger cache

Multicast configuration for cache events using the Intershop 7 Cache Management API (read-only)

Results in Intershop 7 properties with the prefix 'intershop.cacheengine.wrapped'.


MulticastMessenger orm

Multicast configuration for ORM cache synchronization (read-only)

Results in Intershop 7 properties with the prefix 'intershop.cacheSync'.


Methods

Gradle tools version >= 1.1:

Return TypeMethod NameDescription
voidall(Closure<?> closure = null)

Configures all MulticastMessenger objects at once. Is called once for each property of this extension of type MulticastMessenger.

Parameters:

closure – Closure used to configure each MulticastMessenger (optional).

Extension com.intershop.deploy.intershop.SolrExtension

This extension is newly introduced with Gradle Tools 2.0.

This extension allows to configure the solr cluster used by Intershop 7. Attached to the  Project by the SolrPlugin as property solr.

Properties

TypeProperty NameDescriptionDefault value
Set<String>clusterNodes

Server URLs for the all Solr server nodes which belong to the Solr cluster in the form http://<HOST>:<PORT>

empty set
StringserverServer URL of the primary Solr server (or a load balancer) used by Intershop 7 in the form http://<HOST>:<PORT>n.a.
String contextPathThe context path where the Solr Server Web Application is installed at the server.not required

Extension com.intershop.deploy.intershop.StagingExtension

Extension to configure staging (data replication). Attached to the  Project by the MulticastPlugin as property staging.

Properties

TypeProperty NameDescriptionDefault value
StringsystemType

Type of staging system. Possible values are:

  • editing – The deployed cluster is an editing cluster.
  • live – The deployed cluster is a live cluster.
  • none – The deployed cluster does not use the staging feature.
none
FilereplicationClustersFile

Source of the replication-clusters.xml file to deploy. Required if systemType is 'editing'.

When set, the path is checked to denote an existing file.

n.a.

Extension com.intershop.deploy.intershop.WebAdapterDeploymentExtension

Extension to configure the Web Adapter. Attached to the  Project by the WebAdapterDeploymentPlugin as property webadapter.

Properties

TypeProperty NameDescriptionDefault value
String sharedMemoryKey Unique identifier for the shared memory used by the Apache. Use the form '0x<4-digit hexadecimal number>' e.g., '0x2001'.n.a.
List<String> configurationServices List of appserver to connect to for configuration servlets. Each entry of the list must have the form '<hostname>:<port>', e.g., 'localhost:8080'If property hostType of HostTypeExtension is 'all', all local appserver instances from the AppserverExtension. No default, otherwise.
String hostname Server name for the Apache.If property hostType of HostTypeExtension is 'all' or 'webserver', the default is 'localhost'. No default, otherwise.
int portTCP/IP port to bind Apache to for HTTP communication.80
int securePortTCP/IP port to bind Apache to for HTTPS communication.443
booleanuseSSLBoxSpecifies whether or not an external SSL box is being used. (Only available since Gradle Tools 2.0.)false
intsslBoxSecuredPort

The internal port, the webserver should listen to for accepting connections, that have been encrypted by the SSL box. (Only available since Gradle Tools 2.0.)

n.a.
Set<String>serverGroupsAll server groups known to the Web Adapter.

If property hostType of HostTypeExtension is 'all': union of all appservers' server groups in AppserverExtension. Otherwise: ['WFS', 'BOS', 'JOB']

Extension com.intershop.deploy.assembly.AssemblyDeploymentExtension

Extension for providing configuration common to the assembly and all components. Attached to the  Project by the AssemblyDeploymentPlugin as property assemblyDeployment. Some of the properties are propagated to the ResourceDeploymentExtensionResourceDeploymentExtension of this and all child projects.

Properties

TypeProperty NameDescriptionDefault value

File

indexLocation Location and name of index file. Used for loading the index upon start up (if it exists) and storing in the IndexingFinalizerTask.index.idx in the directory of the settings.gradle file
String user Name of the user that should own the resulting files and run deployed applications. The deployment must be executed with this user. Propagated to property user of the ResourceDeploymentExtension of this and all child projects.n.a.
String userGroup Name of a user group of that user. Used for processes (like the Apache) that allow to configure a group for execution. Propagated to property userGroup of the ResourceDeploymentExtension of this and all child projects.n.a.
boolean purgeUnknownFilesIf true, files created by non-deployment-processes inside directories created by the deployment are deleted if these directories are no longer required by the deployment. (Example: Log-files.) If false, the deployment will keep all files not created by it. See DirectoryDeployment for details.false
File postInstallDirectory Parent directory of post-install directory. Post-install scripts - if any - will be created inside the subdirectory 'postinstall' of this directory.directory of the settings.gradle file
List<String> modificationPriorities An ordered list of priority levels for modification handling. Levels that are listed later are preferred over levels listed earlier. Propagated to property modificationPriorities of the ResourceDeploymentExtension of this and all child projects..['default']
String defaultModificationHandler Default ModificationHandler used if no other modification handler matches a modified file. Specify the name of a method available on the modifications property of the ResourceDeploymentExtension. 'overwrite'

Extension com.intershop.deploy.assembly.TargetExtension

Extension for describing target location and system of the deployment. Attached to the  Project by the TargetPlugin as property  target.

Properties

TypeProperty NameDescriptionDefault value
 Stringplatform

Platform of the system. Used to select platform specific artifacts. Allowed values are:

  • 'linux.rhel.x86_64'
  • 'linux.sles.x86_64'
  • 'win.x86_64'
n.a. 
StringinstanceIdInstance ID of the Intershop 7 installation. Used to distinguish global resources like service names. Please use an integer (despite the type).n.a.
FileshareDirectory

Location of IS_SHARE. When deploying host-types other than 'share', this is the location of the mount point.

Cannot be the directory of the settings.gradle file or one of its parent directories.

n.a.
BooleanincludeShareIf true, all deployed components also deploy their share-artifacts. If false, the share-artifacts are excluded.value of includeShare of selected host type
FilelocalDirectory

Main deployment directory. Location of IS_HOME.

Cannot be the directory of the settings.gradle file or one of its parent directories

n.a.
BooleanincludeLocalIf true, all deployed components also deploy their non-share-artifacts. If false, the non-share-artifacts are excluded.

value of includeLocal of selected host type

Additional properties are newly introduced with Gradle Tools 2.0:

TypeProperty NameDescriptionDefault value
File javaHome This JDK location is used in scripts, e.g., to execute the server-startup.value of java.home of the current gradle-process
StringcartridgesPathThe location of cartridges relative to the local or share root directories designated by the placeholders ${IS_HOME} and ${IS_SHARE}.

includeCartridges=trueincludeCartridges=false
includeShare=true ${IS_SHARE}/system/cartridges ${IS_HOME}/cartridges
includeLocal=true ${IS_HOME}/cartridges ${IS_SHARE}/system/cartridges

If both includeShare and includeLocal are true, the includeShare variant wins per default.

FilecartridgesDirectory

Resolved location of cartridges (read-only property generated from cartridgesPath)

This folder contains the cartridge part of all cartridges, as well as the cartridgelist.properties file.


BooleanincludeCartridges

If true, the cartridge part of all cartridges will be deployed. If false, the cartridge part of cartridges is excluded.

Note: This does not affect the share or Javadoc artifacts of cartridges.

value of includeCartridges of selected host type

Extension com.intershop.deploy.cartridge.CartridgeDeploymentExtension

Extension for configuring the deployment of a cartridge. Attached to the Project by the CartridgeDeploymentPlugin as property  cartridgeDeployment.

Properties

TypeProperty NameDescriptionDefault value

File

cartridgesDirectoryDirectory to contain all cartridges.property cartridgesDirectory of TargetExtension
boolean includeShare If true, all contributions of the cartridge to the share are deployed. If false they are omitted.property includeShare of TargetExtension
FileshareDirectoryDirectory to contain share-artifacts of the cartridge.property shareDirectory of TargetExtension
boolean includeJavadocIf true, the javadoc of the cartridge is deployed. If false it is omitted.true if property includeJavadoc of DeveloperExtension is true and the cartridge is not contained in the property sourceCartridges. Otherwise, false.
File javadocDirectory Directory to contain the Javadoc of all cartridges.property javadocDirectory of DeveloperExtension

Extension com.intershop.deploy.encryption.EncryptionExtension

This extension is newly introduced with Gradle Tools 2.0.

Extension for providing location of encryption configuration files and algorithm to use. Attached to the  Project by the EncryptionPlugin as property encryption.

Properties

TypeProperty NameDescriptionDefault value
File

propertiesFile

Location where the encryption properties file should be generated/administered at resp. deployed from.

Contains encryption configurations. Each encryption configuration has an (automatically generated) ID and an algorithm. Also exactly one encryption configuration is marked as default configuration. The default configuration is used for all encryption processes. Non-default configurations are used to decrypt data encrypted when those configurations where marked as default.

<directory of settings.gradle>/encryption.properties if AssemblyDeploymentPlugin is applied

FilekeystoreFile

Location where the Java Cryptography Extension keystore file should be generated/administered at resp. deployed from.

Contains a Java Cryptography Extension key for each encryption configuration in the encryption properties file. The keystore is protected against unwanted reading and writing by a password. The password is calculated from several different pieces of data. One of them is contained in the properties file, another is the content of the random file.

<directory of settings.gradle>/intershop.keystore if AssemblyDeploymentPlugin is applied
FilerandomFile

Location where the random file should be generated/administered at resp. deployed from.

Used to provide a large, high entropy piece of data for the keystore password.

<directory of settings.gradle>/random if AssemblyDeploymentPlugin is applied
Stringalgorithm

Algorithm that should be used for encryption.

Must be of the form PBEWith<digest>And<encryption>, see http://docs.oracle.com/javase/7/docs/technotes/guides/security/StandardNames.html#Cipher.

If the algorithm of the default encryption in the encryption properties differs from this algorithm, a new default encryption will be created by the generateEncryptionConfig task to match this.

PBEWithMD5AndTripleDES
StringpropertiesTargetPathPath relative to IS_SHARE that the encryption properties file should be deployed to and read from by the deployed Intershop 7.system/config/cluster/encryption.properties
StringkeystoreTargetPath Path relative to IS_SHARE that the keystore file should be deployed to and read from by the deployed Intershop 7.system/config/cluster/intershop.keystore
StringrandomTargetPath Path relative to IS_SHARE that the random file should be deployed to and read from by the deployed Intershop 7.system/config/cluster/random

Task Instances

The following table gives an overview over all tasks created by deployment plugins, if they are applied to a Gradle Project.

TypeNameDescriptionDepends onAdded by Plugin
DeployFiles deploy<name>FilesAdded for each FileDeployment in the ResourceDeploymentExtension , <name> being the name of the FileDeployment. Deploys the files of that FileDeployment declaration.
ResourceDeploymentPlugin
DefaultTask deployFilesOverall task that does nothing by itself, but has dependencies to all deploy<name>Files tasks of the project.deploy<name>FilesResourceDeploymentPlugin  
DeployLinksTask deployLinksDeploys all symbolic links declared by LinkDeployment objects in the ResourceDeploymentExtension.
ResourceDeploymentPlugin
DeployDirectoriesTask deployDirectoriesDeploys all directories declared by DirectoryDeployment objects in the ResourceDeploymentExtension.
ResourceDeploymentPlugin
DeployP ermissionsTask deployPermissionsApplies all POSIX permissions PermissionDeployment objects in the ResourceDeploymentExtension.
ResourceDeploymentPlugin
DeployWindowsServiceTask deploy<name>

Added for each   WindowsServiceDeployment in the ResourceDeploymentExtension , <name> being the name of the WindowsServiceDeployment. Creates a post-install batch script for registering the service.

These tasks are only created when running the deployment on Windows.


ResourceDeploymentPlugin
DeployLinuxServiceTask deploy<name>

Added for each LinuxServiceDeployment in the ResourceDeploymentExtension , <name> being the name of the LinuxServiceDeployment. Creates a post-install shell script for deploying and registering the /etc/init.d-script.

These tasks are only created when running the deployment on Linux.


ResourceDeploymentPlugin
PostInstallInformationTask postInstallMessageInstructs the user to run post-install-scripts generated by all tasks extending from PostInstallProducer.

DefaultTask deployCartridges

Deploys multiple cartridges. By default all cartridges specified in property sourceCartridges of the DeveloperExtension are deployed.

You can also specify a whitespace-delimited list of cartridge names in extra project property cartridges, e.g., passing in -Pcartridges="core bc_foundation".

deployFiles of selected cartridges

Gradle Tools version >= 2.0:
deployCartridgeListFiles

DeveloperDeploymentPlugin
IndexingFinalizerTask persistIndexStores the in-memory index into a file and removes obsolete resources.Finalizer for all tasks marked with IndexedTask AssemblyDeploymentPlugin
DefaultTask
deployExecute the whole deployment. Overall task that does nothing by itself, but has dependencies to all deployment tasks of all projects.deployFiles, deployLinks, deployDirectories, deployPermissions of all projects AssemblyDeploymentPlugin
DefaultTask
undeployUndeploys all existing resources. During upgrades/downgrades/restoring there is no need to call undeploy, as obsolete resources will automatically be removed by the persistIndex task.
AssemblyDeploymentPlugin
DefaultTask undeployServicesGenerates post-install scripts for undeployment of services. You can call this explicitly if you want to stop and unregister the services before undeploying their files. Post-install scripts for undeployment of services will also be generated by the persistIndex task whenever a service becomes obsolete.
AssemblyDeploymentPlugin

Gradle tools version >= 2.0:

TypeNameDescriptionDepends onAdded by Plugin
DefaultTask generateEncryptionConfigCreates the encryption configuration files as specified in the  EncryptionExtension if they don't exist. Also adds a new default encryption configuration if the algorithm property of the EncryptionExtension does not match the algorithm of the current default encryption configuration. Otherwise does nothing.
EncryptionAdminPlugin
DefaultTask newKeyCreates a new encryption configuration with a new key.
EncryptionAdminPlugin
DefaultTask newPasswordGenerates a new random file and password data in the encryption properties file and rewrites the keystore to be protected by the resulting new password.
EncryptionAdminPlugin
DefaultTask encrypt

Encrypts text using the default encryption configuration, found in encryption configuration files as specified by EncryptionExtension.

Expects the plain text to encrypt in the project property plainText, e.g., passing in -PplainText=somethingToEncrypt.

generateEncryptionConfig EncryptionAdminPlugin
DefaultTask decrypt

Decrypts text previously encrypted by Intershop 7 or the encrypt task.

Expects the encrypted text to decrypt in the project property encryptedText, e.g., passing in -PencryptedText=

encryption1 @PBEWithMD5AndTripleDes :5FY97GDnsvU=|3viFU8xFc1XmMhLnPXeWcVWDGgX/WUta.
 generateEncryptionConfig EncryptionAdminPlugin

Tasks Types

All types in this chapter extend from Task, see its methods and properties.

Task com.intershop.deploy.resources.DeployFiles

Copies files and adds them to an index. It handles files modified since last deployment using a given set of modification handlers. Also it applies a set of content filters during copying.

The task collects all errors occurring during processing and displays them at the end.

Extends Copy and IndexedTask, see their methods and properties.

Properties

TypeProperty NameDescriptionDefault value
FilterRegistry filtersContent filters to apply.
ModificationHandlerRegistry modificationHandlersModification handlers for deciding how to treat files that have been modified since last deployment.
TaskResources resourcesIndex used to register file resources and for checking for modifications.

Task com.intershop.deploy.resources.DeployDirectoriesTask

Creates all directories declared as DirectoryDeployment in a ResourceDeploymentExtension and adds them to an index.

Extends IndexedTask, see its methods and properties.

Properties

TypeProperty NameDescriptionDefault value
Collection<DirectoryDeployment>directoriesDirectories to be deployed.
TaskResources resourcesIndex used to register directory resources.

Task com.intershop.deploy.resources.DeployLinksTask

Creates a set of symbolic links and adds them to an index. It handles links modified since last deployment using a given set of modification handlers.

Extends IndexedTask, see its methods and properties.

Properties

TypeProperty NameDescriptionDefault value
Collection<LinkDeployment>linksLinks to deploy.
TaskResources resourcesIndex used to register link resources.
ModificationHandlerRegistry modificationHandlers Modification handlers for deciding how to treat links that have been modified since last deployment.

Task com.intershop.deploy.resources.DeployPermissionsTask

Applies all POSIX file permissions declared by PermissionDeployment objects in a ResourceDeploymentExtension. Applied permissions are not added to an index.

Properties

TypeProperty NameDescriptionDefault value
R esourceDeploymentExtension deploymentConfigContainer for permissions to be deployed.

Task com.intershop.deploy.services.linux.DeployLinuxServiceTask

Creates post-install shell scripts for deploying and registering a script in /etc/init.d.

Extends PostInstallProducer, IndexedTask, see their methods and properties.

Properties

TypeProperty NameDescriptionDefault value
LinuxServiceDeployment serviceDeploymentService for which to create the post-install script.

Task com.intershop.deploy.services.linux.DeployWindowsServiceTask

Creates post-install batch scripts for registering a Windows service.

Extends PostInstallProducer, IndexedTask, see their methods and properties.

Properties

TypeProperty NameDescriptionDefault value
WindowsServiceDeployment serviceDeploymentService for which to create the post-install script.

Task com.intershop.deploy.postinstall.PostInstallInformationTask

Displays a message about all post-install scripts created.

Properties

TypeProperty NameDescriptionDefault value
Collection<PostInstallProducer>postInstallProducerProviders of post-install scripts.

Task com.intershop.deploy.index.IndexingFinalizerTask

Removes obsolete resources (files, directories, links) and writes the in-memory index to an index file. The AssemblyDeploymentPlugin creates an instance of this task and adds it as a Gradle finalizer to all tasks marked with IndexedTask.

The IndexingFinalizerTask undeploys a Resource if:

  • the task that created the resource no longer exists (e.g., because a component is no longer contained in the assembly) or
  • the task was executed successfully, but did not set the property desired of this resource to true (e.g., the file is no longer contained in the share-artifact of a component) or
  • the task undeploy was called

The IndexingFinalizerTask does not undeploy a resource if:

  • the task that created the resource was not executed (e.g., if you execute only the deployFiles task of one component, the files of other components are kept) or
  • the task was executed, but failed or
  • the resource was created in this deployment (e.g., a file was deployed the first time)

Also it is possible to move a Resource between different tasks (e.g., a file was deployed by one component in the last run, but is now deployed by another). This also keeps the file.

A resource is undeployed by calling a registered UndeploymentHandler matching its type. The UndeploymentHandler provided by the AssemblyDeploymentPlugin handle all predefined resource types. If a file is removed and the parent directory becomes empty, this directory will also be removed. For further details on removing directories and files created by non-deployment processes, see DirectoryDeployment.

Properties

TypeProperty NameDescriptionDefault value

Index

indexIn-memory index.
FilelocationFile to store index in.

Methods

Return TypeMethod NameDescription
void registerUndeploymentHandler(Class<? extends Resource> forType, UndeploymentHandler handler)

Adds an undeployment handler for a special type of resource.

Types

Type org.gradle.api.initialization.Settings 

This is a standard Gradle type. See Gradle's DSL Reference on it.

The type is listed here because Intershop Deployment plugins add custom methods/properties, see below.

Properties

Properties Added by the DeploymentBootstrapPlugin

TypeProperty NameDescriptionDefault value
DeploymentBootstrapExtension
deploymentBootstrapExtension to configure loading of an assembly for deployment (read-only)

Type org.gradle.api.Project

This is a standard Gradle type. See Gradle's DSL Reference on it.

The type is listed here because Intershop Deployment plugins add custom methods/properties, see below.

Properties added by Plugins

Added byTypeProperty NameDescriptionDefault value

DeploymentBootstrapPlugin

DeploymentBootstrapExtension
deploymentBootstrapExtension to configure loading of an assembly for deployment. Added to the root project, so it is possible to query selected host type/environment/assembly etc (read-only)

AssemblyDeploymentSettingsPlugin

ModuleVersionIdentifier self Component and version from which this project was created (read-only)
ResourceDeploymentPlugin ResourceDeploymentExtension deploymentExtension for configuring deployment of files, directories, links, services (read-only)
Appserver DeploymentPlugin   AppserverExtension
appserverExtension for configuring Intershop 7 nodemanager and appserver instances (read-only)
DatabasePlugin DatabaseExtension   databaseExtension for configuring database connection (read-only)
DeveloperPlugin DeveloperExtension developerExtension for providing configuration only needed during development (read-only)
LicensePlugin LicenseExtension licenseExtension for providing a license.xml file (read-only)
MulticastPlugin MulticastExtension multicastExtension for providing multicast configuration (read-only)
StagingPlugin StagingExtension stagingExtension for providing staging configuration (read-only)
WebAdapterDeploymentPlugin WebAdapterDeployment Extension webadapterExtension for configuring Apache and Web Adapter (read-only)
AssemblyDeploymentPlugin AssemblyDeploymentExtension assemblyDeploymentExtension for providing configuration common to the assembly and all components (read-only)
TargetPlugin TargetExtension targetExtension for configuring target system and locations of the deployment (read-only)
CartridgeDeploymentPlugin CartridgeDeploymentExtension cartridgeDeploymentExtension for configuring the deployment of a cartridge (read-only)
EncryptionPlugin EncryptionExtension encryption

Only for Gradle tools version >= 2.0

Extension for providing locations of encryption configuration files during administration and in the application server (read-only)


Type com.intershop.deploy.settings.HostType 

A host type of the deployed assembly. Instances are created by the HostTypeSettingsPlugin.

Properties

TypeProperty NameDescriptionDefault value
StringnameName of the host type (read-only)

boolean

includeCartridgesFlag that indicates whether cartridge subsets should be deployed if this host type is selected (read-only)
booleanincludeShareFlag that indicates whether deployed components should deploy their share specific parts (read-only)
booleanincludeLocalFlag that indicates whether deployed components should deploy their local specific parts (read-only)
booleanincludeJavadocFlag that indicates whether Javadoc should be deployed if this host type is selected (read-only)
List<String>configurationsNames of assembly configurations that are associated with this host type (read-only)

Type com.intershop.deploy.settings.Environment 

An environment of the deployed assembly. Instances are created by the  HostTypeSettingsPlugin.

Properties

TypeProperty NameDescriptionDefault value
StringnameName of the environment (read-only)

String

cartridgeConfigurationName of the assembly configuration that contains the cartridges associated with this environment (read-only)

Type com.intershop.deploy.resources.FileDeployment

A set of files to be deployed. Instances are created in the container  files of the ResourceDeploymentExtension.

FileDeployment is a Gradle CopySpec. Use the methods/properties of the CopySpec to describe which files/file trees to deploy and where to deploy them to. See also Gradle's user guide on Working With Files.

A source to copy from that is especially useful during deployment are ArtifactFileTree objects returned by the  artifacts method of the ResourceDeploymentExtension. You are not limited to using these as source though and may deploy from any source that CopySpec supports.

No Warning for empty FileDeployments

Like a Gradle CopySpec, a FileDeployment that does not contain any files to copy (e.g., because includes are defined but match no source file) does not lead to an error. Instead the corresponding DeployFiles task always displays as 'UP-TO-DATE' when executed. This is especially confusing if you add a File object with the from method and the file is missing. In this case also no error is thrown.

Properties

TypeProperty NameDescriptionDefault value
StringnameName of the set of files to deploy. Only used for identification of the declaration (read-only)

Type com.intershop.deploy.resources.LinkDeployment

A single symbolic link to be deployed. The actual physical form of the link is operating and file system dependent, see documentation of Java NIO, which is used for managing links.

Properties

TypeProperty NameDescriptionDefault value
StringnameName of the the link deployment. Only used for identification of the declaration (read-only)
FilefromLocation of the link
FiletoTarget of the link

Type com.intershop.deploy.resources.DirectoryDeployment

A single directory that should be created during deployment. While parent directories for deployed files are created automatically, this allows to ensure the existence of empty directories.

To allow purging of files created by the deployed application (like log files) a DirectoryDeployment must be declared. When a directory created through a DirectoryDeployment is no longer desired, like because the component that declared it is no longer deployed, all files unknown to the deployment are purged from that directory. (Ultimately when all deployed files have been deleted from the directory, the directory itself is deleted.) You can enable/disable this behavior by settings the property purgeUnknownFiles of the AssemblyDeploymentExtension. The purging itself is taking place in the IndexingFinalizerTask.

The folders IS_SHARE and IS_HOME are declared as DirectoryDeployment. So is the cartridge folder of each cartridge. This way unknown files inside the cartridge folder are already purged when the cartridge is undeployed, not only with undeployment of the complete IS_SHARE.

Properties

TypeProperty NameDescriptionDefault value
StringnameName of the directory deployment. Only used for identification of the declaration (read-only)
FilepathLocation of the directory

Type com.intershop.deploy.resources.PermissionDeployment

A POSIX file mode applied to a file or directory.

The use of PermissionDeployment has the following limitations:

  • If the file or operating system does not support POSIX permissions, PermissionDeployment objects are ignored.
  • Since the deployment is executed by a non-root user, the user owner ship of files stay untouched. The same applies to the group owner ship.
  • If multiple PermissionDeployment declarations apply different permissions to the same files, the behavior is undefined. This especially occurs if one PermissionDeployment applies to a directory and other PermissionDeployment declarations apply to files/directories nested in that directory.

If you need more control over permissions, please use configuration management/admin tools (like Chef or puppet) or automate calls to OS commands like chown/chmod resp. CACLS.

Properties

TypeProperty NameDescriptionDefault value
StringnameName of the permission deployment. Only used for identification of the declaration (read-only)
FiletoFile or directory to apply permissions to. If a directory, permissions applied recursively to all files and directories.
StringmodeString of 9 characters ('x', 'r', 'w', '-') representing permissions for the file owner, group and others. For details see fromString-method of java.nio.file.attribute.PosixFilePermissions.

Type com.intershop.deploy.resources.ServiceDeploymentContainer

A container for declaring windows and linux services.

Properties

TypeProperty NameDescriptionDefault value
NamedDomainObjectContainer <WindowsServiceDeployment> windowsServices to deployed on Windows. Ignored if the deployment is run on Linux (read-only)

NamedDomainObjectContainer<LinuxServiceDeployment>

linux Services to deployed on Linux. Ignored if the deployment is run on Windows (read-only)

Type com.intershop.deploy.resources.WindowsServiceDeployment

A windows service to be deployed.

Properties

TypeProperty NameDescriptionDefault value
StringnameName of the service deployment. Only used for identification of the declaration (read-only)
String serviceName Name of the service (ID).
String displayName Display name of the service.
List<String> command Executable and arguments for starting the service.
String user User to execute the service with. May be the name of a local user or a domain user of the form '<DOMAIN>\<USER>'
WindowsServiceDeployment.StartupTypestartupType

When to start the service. WindowsServiceDeployment.StartupType is an enum with the following values:

  • AUTOMATIC
  • ENABLED
  • DISABLED
DISABLED

Type com.intershop.deploy.resources.LinuxServiceDeployment

A linux service (init.d script) to be deployed.

Properties

TypeProperty NameDescriptionDefault value
StringnameName of the service deployment. Only used for identification of the declaration (read-only)
StringserviceNameFile name used inside /etc/init.d.Name of file serviceScript
FileserviceScriptFile to copy the script from. This may be a file deployed through a FileDeployment or any non-deployed file.
Collection<Integer>runLevelsRun levels to add the service too via chkconfig.(empty collection) 

Type com.intershop.deploy.resources.ArtifactFileTree

A FileTree resulting from downloading an Ivy artifact (or the ivy.xml file) from a repository and optionally extracting it. Create it using the method artifacts of the ResourceDeploymentExtension.

To compute the resulting FileTree:

  1. A set of matching Ivy artifacts is computed based on the property metaData, type and closures passed to the matchingArtifacts method. 
  2. Based on the property extract either these artifacts are returned as files or – assuming that they are zip-archives – their contents.

Extends Gradle's File Tree, see its methods and properties.

Properties

TypeProperty NameDescriptionDefault value
booleanextract

If true all matching artifacts must be zip-archives. The resulting FileTree then is the result of extracting all those ZIP-archives the contents of all these zip-archives into a common root folder.

If false the resulting FileTree contains all matching artifacts as files. The file name for each artifact is <artifact name>.<artifact extension>. (Artifact name and extension are defined in the ivy.xml file.)

false
booleanmetaData

If true only the ivy.xml file itself (also called 'meta artifact' in Ivy terms) is a matching artifact.

If false all Ivy artifacts mentioned in the ivy.xml match, but not the ivy.xml itself.

false
StringtypeIf set, only artifacts with this artifact type match. (The artifact type is defined in the ivy.xml file.)null

Methods

Return TypeMethod NameDescription
voidartifactsMatching(Closure closure)

Adds a closure to filter artifacts. The closure is called for each artifact and passed a ResolvedArtifact. The closure must return a boolean indicating whether the artifact should be included.


If multiple closures are added using artifactsMatching, all closures must return true to include the artifact. 

Type com.intershop.deploy.filters.DeploymentContentFilter

An instruction for a set of deployed files to deploy a content that is changed compared to the content of the source files.

To create a custom deployment content filter, extend AbstractDeploymentContentFilter.

Extends FileSpec, see its methods and properties.

Properties

TypeProperty NameDescriptionDefault value
StringnameName of the filter. Only used for identification of the declaration (read-only)

Type com.intershop.deploy.filters.AbstractDeploymentContentFilter

Abstract base class for creating deployment content filters. The only method required to be implemented is configureNormalizedFilter.

Implements DeploymentContentFilter, see its methods and properties.

Methods

Return TypeMethod NameDescription
voidconfigureNormalizedFilter(ContentFilterable filterable)

Called to transform the DeploymentContentFilter and all its properties into a general, executable filter. Abstract.

The implementation should call the provided ContentFilterable to add concrete filtering on the file.

Type com.intershop.deploy.utils.FileSpec

A file matcher. The set of files matched is determined by a directory dir and an arbitrary number of includes and excludes.

Includes and excludes can be provided by:

  • Ant style patterns to match files path relative to the directory dir,
  • A closure passed in a Java File object and returning true or false (the represented file may not exist, yet, for initial deployments)

If a file is matched by a FileSpec if:

  • it is located in the directory dir or one of its subdirectories and
  • is matched by at least one include (if any include is given) and
  • is matched by no exclude

Properties

TypeProperty NameDescriptionDefault value
FiledirDirectory that files must be located in to match the FileSpec.

Methods

Return TypeMethod NameDescription
void

dir(File dir)

   

Alias for setting the dir property.

Parameters:

dir – New value of property dir.

void include(Iterable<String> includes)

Includes files based on Ant style patterns.

Parameters:

includes – List of include patterns.

void include(String... includes)

Includes files based on Ant style patterns.

Parameters:

includes – List of include patterns.

voidinclude(Closure<?> include)

Includes files based on a closure. The closure is passed a File object and must return a boolean to indicate matching.

Parameters:

include – Closure to evaluate.

voidexclude(Iterable<String> excludes)

Excludes files based on Ant style patterns.

Parameters:

excludes – List of exclude patterns.

voidexclude(String... excludes)

Excludes files based on Ant style patterns.

Parameters:

includes – List of exclude patterns.

voidexclude(Closure<?> exclude)

Excludes files based on a closure. The closure is passed a File object and must return a boolean to indicate matching.

Parameters:

exclude – Closure to evaluate.

Type com.intershop.deploy.filters.OverridePropertiesFilter

Filter that modifies properties-files based on a Map. The filter overwrites properties that already exists in the properties-file, otherwise adds a new property to the file.

Extends DeploymentContentFilter, see its methods and properties.

Properties

TypeProperty NameDescriptionDefault value
Map<String, Object>properties

Map with each key being a property name and the corresponding value its property value. If the value is not a string, it is converted using the toString method.

(empty map)

Type com.intershop.deploy.filters.PlaceholderReplacementFilter

Filter that replaces placeholders. The filter treats all substrings of the file that start and end with specific tokens as a placeholder and takes the string in between for its name (placeholders never span across lines). If the Map placeholders contains a value for a placeholder, the filter replaces the placeholders, otherwise leaves the placeholder untouched.

Extends DeploymentContentFilter, see its methods and properties.

Properties

TypeProperty NameDescriptionDefault value
Map<String, Object>placeholdersMap with each key being a placeholder name and the corresponding value its replacement. If the value is not a string, it is converted using the toString method.
(empty map)
StringbeginTokenString that marks the start of a placeholder.'<@'
StringendTokenString that marks the end of a placeholder.'@>'

Type com.intershop.deploy.filters.XmlContentFilter

Filter that modifies matching xml-files using a given list of closures.

Extends DeploymentContentFilter, see its methods and properties.  

Methods

Return TypeMethod NameDescription
void

withXml(Closure closure)

   

Adds a closure to modify matching files. The filter passes in an XmlProvider to the closure, which can be used to read and modify the files contents.

Multiple closures are executed in the order of calls to withXml.

Parameters:

closure – Closure that modifies the matching files.

Type com.intershop.deploy.filters.EditLinesFilter

Filter that modifies matching files by running a given closure on each line.

Extends DeploymentContentFilter, see its methods and properties.

Methods

Return TypeMethod NameDescription
void

action(Closure closure)

   

Adds a closure to modify matching files. The filter calls the closure for each line of each matching file. The closure is passed the line (stripped of line endings) and should return a String to replace the line.

Multiple closures are executed in the order of calls to action.

Parameters:

closure – Closure that modifies the matching files.

Type com.intershop.deploy.intershop.OpenDebugPortFilter

Filter that uncomments lines containing '-XDebug' in bash and shell scripts and sets a debug port.

Extends DeploymentContentFilter, see its methods and properties.

Properties

TypeProperty NameDescriptionDefault value
intdebugPortPort to use for the address parameter of the '-XDebug' directive.n.a.

Type com.intershop.deploy.filters.FullContentFilter

Filter that reads the whole file content into a StringBuilder and passes this to a given closure, which may modify the contents arbitrarily. Use it only for text files and files that have reasonable sizes, since the full file content will be loaded into memory at once.

Extends DeploymentContentFilter, see its methods and properties.

Methods

Return TypeMethod NameDescription
void

action(Closure closure)

   

Adds a closure to modify matching files. The filter calls the closure passing in a StringBuilder containing the full content of the file.

Changes to the content of the StringBuilder are reflected in the deployed file content.

Multiple closures are executed in the order of calls to action.

Parameters:

closure – Closure that modifies the matching files.

Type com.intershop.deploy.modification.ModificationHandlerRegistry

Container for modification handlers. Use for implementing custom resource tasks that should take the registered modification handlers into account.

Methods

Return TypeMethod NameDescription

ModificationHandler

getModificationHandler(File file)

Finds the matching ModificationHandler defined for the given file.

Parameters:

file – File that was modified.

void

addModificationHandlers(Collection<ModificationHandler> newHandlers)

Adds the given modification handlers to the registry.

Parameters:

newHandlers– Handlers to add.

Type com.intershop.deploy.modification.ModificationHandler

Strategy that declares how to proceed during deployment if a non-deployed content/state would be overwritten. Modification handlers work with all physical resources that can be represented by a Java File object, e.g., files, directories and links.

The modification handler is called if:

  • The target File was deployed previously, but its contents has since been changed by non-deployment processes.
  • The target File was created previously by a non-deployment process.
  • The target File was deployed previously, but was deleted by a non-deployment process.

A ModificationHandler d efines a file matcher to specify which files this strategy applies to (see FileSpec).

Each ModificationHandler is assigned to a priority (an arbitrary name). Priorities are sorted using property modificationPriorities of the ResourceDeploymentExtension. If multiple modification handlers match the same file, the modification handler with the highest priority is executed.

To create a custom modification handler, extend AbstractModificationHandler.

Extends FileSpec, see its methods and properties.

Properties

TypeProperty NameDescriptionDefault value
StringnameName of the modification handler. Only used for identification of the declaration (read-only)
StringpriorityPriority to assign modification handler to

Methods

Return TypeMethod NameDescription
Stringpriority(String name)

Alias for setting property priority.

Parameters:

name – New value of priority.

Type com.intershop.deploy.modification.AbstractModificationHandler

Abstract base class for creating modification handlers. The only method required to be implemented is handle.

Implements  ModificationHandler , see its methods and properties.

Methods

Return TypeMethod NameDescription
booleanhandle(File modifiedFile)

The implementation of this method determines the actual strategy. The handle method is called for each modified File before a deployment to that File is made.

Returns true if the deployment should overwrite the modifications and false if the modified File should be kept. Throws a DeploymentException if the deployment should be aborted.

Optionally performs additional actions (e.g., backup the modified file) before returning.

Parameters:

modifiedFile – File that has non-deployment content/state and is about to be touched by the deployment.

Type com.intershop.deploy.modification.OverwriteModificationHandler

Issues a warning and overwrites the modified file. Using this may result in loss of data. Extends ModificationHandler, see its methods and properties.

If the file was not modified, but deleted, the file is restored by the deployment.

Type com.intershop.deploy.modification.KeepModificationHandler

Issues a warning and keeps the modified file. The content that should be deployed is ignored, which may result in updates being ineffective. Extends  ModificationHandler, see its methods and properties.

If the file was not modified, but deleted, the file is not restored by the deployment.

Type com.intershop.deploy.modification.AbortModificationHandler

Aborts the deployment if a deployed file has been modified or deleted. This prevents alteration of the modified file. This is the safest way to handle modifications. However it may prevent an unattended deployment. Extends  ModificationHandler, see its methods and properties.

Type com.intershop.deploy.modification.BackupModificationHandler

Creates a backup copy of the modified file first, then overwrites it.

The backup file is created in the same directory like the modified file. The file name of the backup file is the original file name, plus a configurable suffix. If the backup file already exists, a counter is appended.

If the file was not modified, but deleted, no backup is created, but the file is restored.

Extends ModificationHandler, see its methods and properties.

Properties

TypeProperty NameDescriptionDefault value
StringsuffixSuffix used for naming backup files.'-backup'

Type com.intershop.deploy.postinstall.PostInstallProducer

Interface to mark tasks that create a post-install script to be executed after the deployment with root/administrator privileges. The marked task needs to implement getPostInstallScripts method or in Groovy classes provide a property postInstallScripts.

The AssemblyDeploymentPlugin adds a PostInstallInformationTask as Gradle finalizer to all tasks implementing PostInstallProducer.

Methods

Return TypeMethod NameDescription
Collection<File> getPostInstallScripts()

Called after execution of the task to find the post-install scripts.

Type com.intershop.deploy.index.IndexedTask

Interface to mark tasks that create index entries and/or use the index to check for modifications. The marked task needs to implement setResources method or in Groovy classes provide a property resources.

The AssemblyDeploymentPlugin adds an IndexingFinalizerTask as Gradle finalizer to all tasks implementing IndexedTask.

Methods

Return TypeMethod NameDescription
voidsetResources(TaskResources resources)

Called before the execution of the task to provide the task with access to the index.

Type com.intershop.deploy.index.Index

Structure to store Resource objects, e.g., files, links, directories, that have been created by the deployment. The resources created by each Gradle task are stored separately in a TaskResources object.

Properties

TypeProperty NameDescriptionDefault value
Collection< TaskResources> tasksAll task resources objects contained in the index (read-only and immutable)

Methods

Return TypeMethod NameDescription
TaskResources

getAt(String path)

Returns the TaskResources object for a given task or null if none exists.

Parameters:

path– Path of the Gradle task.

TaskResources create(String path)

Creates a new TaskResources  object for a given task.

Parameters:

path– Path of the Gradle task.

TaskResources reverseLookup(String resourceName)

Finds the task that created a resource and returns its TaskResources object. Return null if none is found.

Parameters:

name– Name of the resource. For resources representable by a Java File object (files, directories, links), this is the absolute path.


Type com.intershop.deploy.index.TaskResources

Structure to store Resource objects, e.g., files, links, directories, created by a single task.

Properties

TypeProperty NameDescriptionDefault value
StringnamePath of the Gradle task that this object belongs to (read-only)
Collection< R esource> resourcesAll indexed resources of this specific task (read-only and immutable)

Methods

Return TypeMethod NameDescription
Resource getAt(String resourceName)

Returns the Resource for a given name or null if none exists.

Parameters:

resourceName– Name of the resource. For resources representable by a Java File object (files, directories, links), this is the absolute path.

<Textends Resource> T

create(String resourceName, Class<T> resourceType)

Creates a new Resource object.

Parameters:

resourceName– Name of the resource. For resources representable by a Java File object (files, directories, links), this is the absolute path.

resourceType-  One of the predefined interfaces extending Resource : FileResource, LinkResource, DirectoryResource, WindowsServiceResource, LinuxServiceResource.

Type com.intershop.deploy.index.Resource

Index entry for some physical system resource created by the deployment. See sub-types F ileResourceLinkResource, DirectoryResource, WindowsServiceResource, LinuxServiceResource.

Properties

TypeProperty NameDescriptionDefault value
Stringname

Name of the resource. For resources representable by a Java File object (files, directories, links), this is the absolute path (read-only)

The name must be unique among all resources contained in the index.


booleandesired

Determines whether the resource is still part of the desired state.

If false and the task that created this resource was executed in this deployment, the index entry and the physical system resource are purged by the IndexingFinalizerTask.

false

Type com.intershop.deploy.index.FileResource

Index entry for a file created by the deployment.

Extends Resource , see its methods and properties.

Properties

TypeProperty NameDescriptionDefault value
longlastModified

The "last modified"-timestamp of the file after last deployment. If the index entry was just created lastModified is -1 (read-only)


longsizeThe size of the file (in bytes) after last deployment. If the index entry was just created size is -1 (read-only)
byte[]sha1SumChecksum of the file content after last deployment using the sha-1 algorithm.   If the index entry was just created sha1Sum is null (read-only)

Type com.intershop.deploy.index.DirectoryResource

Index entry for a directory created by the deployment. Note that most directories created by the deployment are not listed as an index entry. See DirectoryDeployment.

Extends  Resource, see its methods and properties.

Type com.intershop.deploy.index.LinkResource

Index entry for a symbolic link created by the deployment.

Extends Resource, see its methods and properties.

Type com.intershop.deploy.index.LinuxServiceResource

Index entry for a Linux service (/etc/init.d script) created by the deployment.

Extends Resource, see its methods and properties.

Type com.intershop.deploy.index.WindowsServiceResource

Index entry for a Windows service created by the deployment.

Extends Resource, see its methods and properties.

Type com.intershop.deploy.intershop.Appserver

Intershop 7 appserver (runtime) instance.

Properties

TypeProperty NameDescriptionDefault value
 Stringname Name of the appserver instance. Convention is to use appserver<n> (read-only)
inttomcatShutdownPortTCP port used to trigger a shutdown of the tomcat.n.a.
int tomcatHttpPort TCP port of the tomcat for HTTP communication.n.a.
inttomcatHttpsPortTCP port of the tomcat for HTTPS communication.n.a.
intappserverPortServlet engine connector port.n.a.
Collection<String>serverGroups

Server groups the appserver should be assigned to.

If empty, the default server groups 'WFS', 'BOS', 'JOB' are assigned.

empty collection

Type com.intershop.deploy.intershop.TomcatServer

This type is newly introduced with Gradle Tools 2.0.

Descriptor for a Tomcat servlet container instance.

This object is extensible and may be extended via the TomcatServer.ext extension. By default, JvmArgsExtension is added as ext.jvmArgs.

Properties

TypeProperty NameDescriptionDefault value
Stringname Name of the servlet container instance (read-only)
int port TCP port of the tomcat for HTTP communication.n.a.
intsecurePortTCP port of the tomcat for HTTPS communication.n.a.
int shutdownPort TCP port used to trigger a shutdown of the tomcat.n.a.

Type com.intershop.deploy.intershop.JvmArgsExtension

This type is newly introduced with Gradle Tools 2.0.

Configures start parameters of a JVM instance. May be used as extension for TomcatServer.

Properties

TypeProperty NameDescriptionDefault value
intminHeapSizeInitial size of the Java heap in MBnot required
intmaxHeapSize

Maximum size to which the Java heap can grow in MB

not required

List<String>additionalJvmArgsAdditional command line parameters for the JVMempty List
String jvmArgs Compound String for all JVM arguments (read-only)

Type com.intershop.deploy.intershop.AppserverTomcatExtension

This extension is newly introduced with Gradle Tools 2.0.

This is an extension to TomcatServer and configures the given instance to be an Intershop 7 application server.

Properties

TypeProperty NameDescriptionDefault value
intportServlet engine connector port.n.a.
Set<String>serverGroups

Server groups the appserver should be assigned to.

If empty, the default server groups 'WFS', 'BOS', 'JOB' are assigned.

empty set

Type com.intershop.deploy.intershop.MulticastMessenger

Configuration for a single multicast channel. (Available since Gradle tools version 1.1)

Properties

TypeProperty NameDescriptionDefault value
 Stringname Name of the multicast channel (read-only)
Stringaddress

TCP/IP address for broadcasting multicast events.

Cluster-wide configuration – needs to be specified in deployment of host type 'share'.

n.a.
intport

Private port to bind multicast connection.

Cluster-wide configuration – needs to be specified in deployment of host type 'share'.

n.a.
StringnetworkInterface

TCP/IP address of network interface.

If none set, the multicast connection will be bound to all interfaces.

Host-specific configuration – needs to be specified in deployment of host type 'appserver'.

null
Disclaimer
The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.
The Intershop Knowledge Portal uses only technically necessary cookies. We do not track visitors or have visitors tracked by 3rd parties. Please find further information on privacy in the Intershop Privacy Policy and Legal Notice.
Home
Knowledge Base
Product Releases
Log on to continue
This Knowledge Base document is reserved for registered customers.
Log on with your Intershop Entra ID to continue.
Write an email to supportadmin@intershop.de if you experience login issues,
or if you want to register as customer.