com.ibm.websphere.ant.tasks
Class ServiceDeployTask

java.lang.Object
  extended byorg.apache.tools.ant.ProjectComponent
      extended byorg.apache.tools.ant.Task
          extended bycom.ibm.websphere.ant.tasks.ServiceDeployTask

public final class ServiceDeployTask
extends org.apache.tools.ant.Task

The serviceDeploy task enables you to generate J2EE application ear files from Service Component Architecture (SCA) compliant modules so that they may be installed on a WebSphere Process Server. The SCA modules may be project interchange zip files exported from a WebSphere Integration Developer workspace or may be simple jar files that contain an sca module file and other supporting artifacts. The structure of the serviceDeploy task is shown below:

<servicedeploy scaModule="archive file to deploy" wasHome="location of the WebSphere Process Server install location" workingDirectory="a directory in which to create a temporary workspace" outputApplication="the path and name of the generated ear" noJ2EEDeploy="whether the j2ee deployers, including ejbdeploy, should be skipped" freeForm="whether jsp and htmo files in a j2ee subdirectory in the service jar should be copied to the generated web module" cleanStagingModules="whether the staging modules in an imported archive should be deleted and recreated during deploy" keep="whether the temporary workspace in the working directory should be preserved after deployment completes" ignoreErrors="whether an ear file should be exported despite compile or validation errors" classPath="a semi-colon delimited list of jar, rar, and zip files that are required on the deploy classpath" progressMeter="whether and how progress should be monitored to the console" fileEncoding="the default file encoding for the workspace root" vmArgs="A space-delimited list of arguments to pass to the deploy jvm" debugOptions="an options file that enables eclipse trace" clean="whether eclipse should remove stored configuration information because an eclipse update was applied to the server's installed deployer"/> The scaModule attribute is required and is a qualified name to the archive that is to be deployed.
The wasHome attribute is optional if WAS_HOME/bin/ws_ant is used to run ANT. It is required if ws_ant is not used to run ANT. This attribute is the location of a WebSphere Process Server installation that provides the serviceDeploy capabilities.
The workingDirectory attribute is optional and controls where the directory in which serviceDeploy will generate a temporary workspace.
The outputApplication attribute is optional and controls the name and location of the generated J2EE ear file. If this attribute is not specified, then the ear file will be named according to the sca module name and will be generated in the location from which the ANT process was launched.
The noJ2EEDeploy attribute is optional and controls whether the J2EE deployers, including ejbDeploy, should be skipped during deployment. The J2EE deployers will execute by default.
The freeForm attribute is optional and controls whether jsp and html files will be copied from the optional j2ee folder of an sca jar file and copied to the generated war file. By default, jsp and html files are not copied into the war file.
The cleanStagingModules attribute is optional and controls whether imported staging modules should be deleted before running the deployer. By default, imported staging modules are not deleted.
The keep attribute is optional and controls whether the generated eclipse workspace should be preserved when the deployer task is complete. By default, the generated eclipse workspace is deleted after deployment.
The ignoreErrors attribute is optional and controls whether an ear file should be generated despite validation errors. By default, an ear file will not be generated if validation errors were flagged during deployment.
The classPath attribute is optional and controls which external archives (jar, rar, and zip) should be appended to the classpath. By default, no external archives are used during deployment.
The progressMeter attribute is optional and controls how progress should be displayed to the console. Legal values include none, meter, or message. The default progressMeter is none.
The fileEncoding attribute is optional and specifies the default file encoding that should be used by eclipse.
The vmArgs attribute is optional and may be used to specify jvm arguments for the deploy process.
The debugOptions attribute is optional and may be used to specify a trace .options file to enable eclipse-based tracing.
The clean attribute attribute is optional and is passed to eclipse so that eclipse will regenerate its stored plugin configuration.

To use this task, add the following to your ANT build.xml <taskdef name="servicedeploy" classname="com.ibm.websphere.ant.tasks.ServiceDeployTask"/> If this serviceDeploy task is not run from an ANT process launched by $WAS_HOME/bin/ws_ant, then ${WAS_HOME}/lib/wpsanttasks.jar must be on the CLASSPATH and the wasHome attribute must be set.
Copyright IBM Corp. 2006


Field Summary
static java.lang.String[] excluded_props
          The jvm launched by the serviceDeploy task is initialized with the ANT process's system properties except for those properties listed in the excluded_props field:
java.assistive, java.runtime.name, sun.boot.library.path, java.vm.version, java.vm.vendor, java.vendor.url, path.separator, java.vm.name, user.country, sun.os.patch.level, java.vm.specification.name, user.dir, java.runtime.version, java.fullversion, java.awt.graphicsenv, java.endorsed.dirs, os.arch, com.ibm.vm.bitmode, java.io.tmpdir, line.separator, java.vm.specification.vendor, user.variant, java.awt.fonts, os.name, sun.java2d.fontpath, java.library.path, java.specification.name, java.class.version, invokedviajava, java.util.prefs.PreferencesFactory, os.version, user.home, user.timezone, java.awt.printerjob, java.specification.version, java.class.path, user.name, java.vm.specification.version, java.home, sun.arch.data.model, user.language, java.specification.vendor, awt.toolkit, java.vm.info, java.version, sun.boot.class.path, java.vendor, file.separator, java.vendor.url.bug, java.compiler, java.util.logging.configureByServer, java.util.logging.manager Any jvm properties may explicitly be passed by the setVMArgs method.
 
Fields inherited from class org.apache.tools.ant.Task
description, location, target, taskName, taskType, wrapper
 
Fields inherited from class org.apache.tools.ant.ProjectComponent
project
 
Constructor Summary
ServiceDeployTask()
           
 
Method Summary
 void execute()
          This launches the serviceDeploy eclipse application in a child jvm, configured according to the user-specified attributes.
 void setClassPath(java.lang.String classPath)
          The classPath attribute is optional and is used to specify additional archives (jar, rar, or zip) that must be added to the classpath to successfully generate the J2EE application.
 void setClean(boolean clean)
          The clean attribute is optional and is passed to eclipse so that eclipse will regenerate its plugin configuration.
 void setCleanStagingModules(boolean cleanStagingModules)
          The cleanStagingModules attribute is optional and controls whether imported staging modules should be deleted before running the deployer.
 void setDebug(java.lang.String debug)
          The debug attribute is optional and may be used to specify a .options file to enable eclipse-based tracing on a plugin basis.
 void setFileEncoding(java.lang.String fileEncoding)
          The fileEncoding attribute is optional and specifies the default file encoding that should be used by eclipse.
 void setFreeForm(boolean freeForm)
          The freeForm attribute is optional and controls whether jsp and html files will be copied from the optional j2ee folder of an sca jar file and copied to the generated war file.
 void setIgnoreErrors(boolean ignoreErrors)
          The ignoreErrors attribute is optional and indicates whether an ear file should be exported despite compile or validation errors.
 void setKeep(boolean keep)
          The keep attribute is optional and controls whether the generated eclipse workspace should be preserved when the deployer task is complete.
 void setNoJ2EEDeploy(boolean noJ2EEDeploy)
          The noJ2EEDeploy attribute is optional and controls whether the the j2ee deployers, including ejbdeploy, should be skipped during deployment.
 void setOutputApplication(java.lang.String outputApplication)
          The outputApplication attribute is optional and controls the path and name of the generated ear file.
 void setProgressMonitor(java.lang.String progressMonitor)
          The progressMeter attribute is optional and controls how progress should be displayed to the console.
 void setScaModule(java.lang.String scaModule)
          The scaModule attribute is mandatory and is the only required attribute for the serviceDeploy task.
 void setVmArgs(java.lang.String vmArgs)
          The vmArgs attribute is optional and may be used to specify jvm arguments for the deploy process.
 void setWasHome(java.lang.String home)
          The wasHome attribute is optional if WAS_HOME/bin/ws_ant is used to run ANT.
 void setWorkingDirectory(java.lang.String workingDirectory)
          The workingDirectory attribute is optional and controls where the directory in which serviceDeploy will generate a temporary workspace.
 
Methods inherited from class org.apache.tools.ant.Task
getDescription, getLocation, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, handleErrorFlush, handleErrorOutput, handleFlush, handleOutput, init, isInvalid, log, log, maybeConfigure, perform, setDescription, setLocation, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName
 
Methods inherited from class org.apache.tools.ant.ProjectComponent
getProject, setProject
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

excluded_props

public static final java.lang.String[] excluded_props
The jvm launched by the serviceDeploy task is initialized with the ANT process's system properties except for those properties listed in the excluded_props field:
java.assistive, java.runtime.name, sun.boot.library.path, java.vm.version, java.vm.vendor, java.vendor.url, path.separator, java.vm.name, user.country, sun.os.patch.level, java.vm.specification.name, user.dir, java.runtime.version, java.fullversion, java.awt.graphicsenv, java.endorsed.dirs, os.arch, com.ibm.vm.bitmode, java.io.tmpdir, line.separator, java.vm.specification.vendor, user.variant, java.awt.fonts, os.name, sun.java2d.fontpath, java.library.path, java.specification.name, java.class.version, invokedviajava, java.util.prefs.PreferencesFactory, os.version, user.home, user.timezone, java.awt.printerjob, java.specification.version, java.class.path, user.name, java.vm.specification.version, java.home, sun.arch.data.model, user.language, java.specification.vendor, awt.toolkit, java.vm.info, java.version, sun.boot.class.path, java.vendor, file.separator, java.vendor.url.bug, java.compiler, java.util.logging.configureByServer, java.util.logging.manager
Any jvm properties may explicitly be passed by the setVMArgs method.

See Also:
setVmArgs(java.lang.String)
Constructor Detail

ServiceDeployTask

public ServiceDeployTask()
Method Detail

execute

public void execute()
             throws org.apache.tools.ant.BuildException
This launches the serviceDeploy eclipse application in a child jvm, configured according to the user-specified attributes.

Throws:
org.apache.tools.ant.BuildException
See Also:
Task.execute()

setScaModule

public void setScaModule(java.lang.String scaModule)
The scaModule attribute is mandatory and is the only required attribute for the serviceDeploy task. This module may be in the project interchange format exported from the WebSphere Integration Developer or it may be a jar file that contains at least the sca.module file plus any other supporting resources.

Parameters:
scaModule - The scaModule to set.

setClassPath

public void setClassPath(java.lang.String classPath)
The classPath attribute is optional and is used to specify additional archives (jar, rar, or zip) that must be added to the classpath to successfully generate the J2EE application.

Parameters:
classPath - A semi-colon delimited list of jar, rar, and zip files that are required on the deploy classpath

setFreeForm

public void setFreeForm(boolean freeForm)
The freeForm attribute is optional and controls whether jsp and html files will be copied from the optional j2ee folder of an sca jar file and copied to the generated war file. By default, jsp and html files are not copied into the war file. This attribute should not be used when deploying project interchange files, in which case user-provided jsp and html files should be located in user-developed web projects.

Parameters:
freeForm - A boolean indicating whether the temporary workspace should be preserved.

setIgnoreErrors

public void setIgnoreErrors(boolean ignoreErrors)
The ignoreErrors attribute is optional and indicates whether an ear file should be exported despite compile or validation errors. By default, an ear file will not be generated if compile or validation errors were encountered during deploy.

Parameters:
ignoreErrors - A boolean indicating whether an ear file should be generated despite reported compilation or validation errors.

setCleanStagingModules

public void setCleanStagingModules(boolean cleanStagingModules)
The cleanStagingModules attribute is optional and controls whether imported staging modules should be deleted before running the deployer. By default, imported staging modules are not deleted. For an sca module named X, the staging modules will be named XApp, XEJB, XEJBClient, and XWeb.

Parameters:
cleanStagingModules - A boolean indicating whether the staging modules should be deleting and regenerated during deployment.

setKeep

public void setKeep(boolean keep)
The keep attribute is optional and controls whether the generated eclipse workspace should be preserved when the deployer task is complete. By default, the generated eclipse workspace is deleted after deployment. This option can be useful when troubleshooting unexpected problems that might be encountered during deployment.

Parameters:
keep - A boolean indicating whether the temporary workspace should be retained following deployment.

setNoJ2EEDeploy

public void setNoJ2EEDeploy(boolean noJ2EEDeploy)
The noJ2EEDeploy attribute is optional and controls whether the the j2ee deployers, including ejbdeploy, should be skipped during deployment. By default, the J2EE deployers are executed.

Parameters:
noJ2EEDeploy - A boolean indicating whether the J2EE deployers should be skipped.

setOutputApplication

public void setOutputApplication(java.lang.String outputApplication)
The outputApplication attribute is optional and controls the path and name of the generated ear file. If the outputApplication attribute is not specified, then an ear file named XApp.ear will be generated in the directory from which ANT was launched for an SCA module named X.

Parameters:
outputApplication - The fully-qualified path for the generated application.

setProgressMonitor

public void setProgressMonitor(java.lang.String progressMonitor)
The progressMeter attribute is optional and controls how progress should be displayed to the console. Legal values includenone, meter, or message. If the progressMeter attribute is not specified, the the progress meter will default to none.

Parameters:
progressMonitor - The type of console monitor: none | meter | message

setWorkingDirectory

public void setWorkingDirectory(java.lang.String workingDirectory)
The workingDirectory attribute is optional and controls where the directory in which serviceDeploy will generate a temporary workspace. By default, the temporary workspace will be generated in the current project's directory. The name of the temporary workspace will be the system time in milliseconds expressed in hexadecimal; for example, 10eab458774.

Parameters:
workingDirectory - The location at which the temporary workspace should be generated.

setFileEncoding

public void setFileEncoding(java.lang.String fileEncoding)
The fileEncoding attribute is optional and specifies the default file encoding that should be used by eclipse. If specified, the file encoding will be set on the workspace root and will be used by various eclipse-based components including the eclipse java compiler.

Parameters:
fileEncoding - A valid file encoding to server as the workspace default.

setDebug

public void setDebug(java.lang.String debug)
The debug attribute is optional and may be used to specify a .options file to enable eclipse-based tracing on a plugin basis.

Parameters:
debug - The file that contains plugin-specific trace enablement settings.

setClean

public void setClean(boolean clean)
The clean attribute is optional and is passed to eclipse so that eclipse will regenerate its plugin configuration. This attribute should generally not be required unless a patch was made to a plugin under ${WAS_HOME}/deploytool/itp/plugins.

Parameters:
clean - A boolean indicating whether the eclipse plugin configuration should be recalculated.

setVmArgs

public void setVmArgs(java.lang.String vmArgs)
The vmArgs attribute is optional and may be used to specify jvm arguments for the deploy process. The child jvm will inherit the system properties of the ANT jvm except for those specified in the excluded_props field. Inherited properties may be overridden and new properties may be defined by the vmArgs attribute. For example,
setVmArgs("-Xms128m -Dsome.property=true");

Parameters:
vmArgs - A space-delimited list of java properties.

setWasHome

public void setWasHome(java.lang.String home)
The wasHome attribute is optional if WAS_HOME/bin/ws_ant is used to run ANT. It is required if ws_ant is not used to run ANT. This attribute specifies the location of a WebSphere Process Server installation that provides the serviceDeploy capabilities. If the wasHome property is not explicitly set, then the location of the WebSphere Process Server will be calculated by the following system properties, in order:
This task will abort if no location for the WebSphere Process Server can be determined.

Parameters:
home - The location of the WebSphere Process Server used to run this deploy task.