C Using the WebLogic Maven Plug-In for Deployment

Apache Maven is a software tool for building and managing Java-based projects. Now you can use a Maven plug-in for WebLogic Server (weblogic-maven-plugin) to perform deployment operations similar to those supported by the command-line utility, weblogic.Deployer. The plug-in lets you deploy, redeploy, update, and such, applications built using Maven to WebLogic Server from within the Maven environment.

To download and configure Maven on supported platforms, see http://maven.apache.org/download.html. Be sure to read the set up instructions closely to ensure that Maven is working correctly in your environment.

Configuring and Using the WebLogic Maven Plug-In

Follow these steps for generating, installing, and using the weblogic-maven-plugin:

Note:

To successfully accomplish these steps, your computer must be connected to the Internet and have the necessary proxy settings configured correctly in the settings.xml file (typically $HOME/.m2/settings.xml). For further details, see http://maven.apache.org/guides/mini/guide-proxies.html.

Build the plug-in JAR file using the WebLogic JarBuilder Tool (wljarbuilder) under MW_HOME/wlserver_10.3/server/lib/ with the following command:

java -jar wljarbuilder.jar -profile weblogic-maven-plugin

The weblogic-maven-plugin.jar contains a Project Object Model (pom.xml) file which specifies the groupId, artifactId, version, and packaging of the weblogic-maven-plugin.jar:

Provision the weblogic-maven-plugin.jar in your local Maven repository with the following command. However, for a shortened command-line goal invocation of the plug-in, follow the directions in step 5 before performing this step.

Because the mvn install command downloads Maven dependencies from the Internet which are required for the successful execution of Maven goals, you must have run mvn installat least once on your local machine.

From a POM file—By including the Maven plug-in in the application's pom.xml file.

You add the plug-in into any life cycle phase of the project. Optionally, you can add a goal to any of the default Maven life cycle phases by adding an executions tag in the pom.xml file. The goal is then bound to that particular phase of the Maven life cycle. For example, as shown in Example C-1, the goal is bound to the "install" phase of the Maven life cycle. By doing this, every time you run the mvn install command, the deployment plug-in is also called.

Optionally, you can shorten the full invocation of the plug-in by providing a pom.xmlfile, as shown in Example C-2, and modifying the settings.xml file located in your $HOME/.m2 directory, before you provision the plug-in in your Maven repository.

Change the settings.xml file as follows:

<!-- pluginGroups
| This is a list of additional group identifiers that will be searched
| when resolving plugins by their prefix, for example, when invoking a
| command line like "mvn prefix:goal". Maven will automatically add the
| group identifiers "org.apache.maven.plugins" and "org.codehaus.mojo"
| if theses are not already contained in the list.
| -->
<pluginGroups>
<!-- pluginGroup
| Specifies a further group identifier to use for plugin lookup.
-->
<pluginGroup>com.oracle.weblogic</pluginGroup>
</pluginGroups>

Replace the MW_HOME/wlserver_10.3/server/lib/pom.xml file with the following:

Lists the deployment names for applications and standalone modules deployed, distributed, or installed in the domain.

weblogic:update-app

Updates an application's deployment plan by redistributing the plan files and reconfiguring the application based on the new plan contents.

weblogic:help

Lists all the deployment goals.

weblogic.deploy

Full Name

com.oracle.weblogic:weblogic-maven-plugin:deploy

Short Name

weblogic:deploy

Description

Deploys an application or module.

Attributes

Requires a Maven 2.0 project.

Requires an application ready for deployment.

Parameters

Table C-2 weblogic:deploy Parameters

Option

Type

Default

Description

name

String

none

Deployment name to assign to a newly-deployed application or standalone module. If you do not specify this attribute, WebLogic Server assigns a deployment name to the application, based on its archive file or exploded directory.

source

String

none

Required. Archived file or exploded archive directory to deploy.

plan

String

none

Deployment plan to use when deploying the application or module.

targets

String

none

Targets on which to distribute and deploy the application or module. The value of this attribute is a comma-separated list of target servers, clusters, or virtual hosts.

upload

Boolean

false

Copies the source files to the Administration Server's upload directory prior to deployment.

stage

Boolean

false

Copies deployment files to target servers' staging directories.

nostage

Boolean

true

Does not copy the deployment files to target servers, but leaves them in a fixed location, specified by the source option.

external_stage

Boolean

false

Does not copy the deployment files to target servers; instead, you must ensure that deployment files have been copied to the correct subdirectory in the target servers' staging directories. You can manually copy the files or use a third-party tool or script.

You can specify only one of the following attributes: stage, nostage, or external_stage. If none is specified, the default deployment mode to Managed Servers is stage; the default mode to the Administration Server and single server instances is nostage.

retiretimeout

Integer

-1

Number of seconds before WebLogic Server undeploys the currently-running version of this application or module so that clients can start using the new version.

library

Boolean

false

The deployment as a shared J2EE library or optional package.

libspecver

String

none

Specification version of a J2EE library or optional package. You can use this option only if the library or package does not include a specification version in its manifest file. libversion can be used only in combination with the library attribute.

libimplver

String

none

Implementation version of a J2EE library or optional package. You can use this option only if the library or package does not include an implementation version in its manifest file. libimplversion can be used only in combination with the library attribute.

usenonexclusivelock

Boolean

false

Deployment operation uses an existing lock, already acquired by the same user, on the domain. This option is helpful in environments where multiple deployment tools are used simultaneously and one of the tools has already acquired a lock on the domain configuration.

altappdd

String

none

Name of an alternate J2EE deployment descriptor (application.xml) to use for deployment.

altwlsappdd

String

none

Name of an alternate WebLogic Server deployment descriptor (weblogic-application.xml) to use for deployment.

Task identifier of a running deployment task. Make sure that the identifier is unique to all other running deployment tasks. The system automatically generates a unique identifier if you do not specify one.

Required. Deployment name of a deployed application or module. If you do not specify this attribute, WebLogic Server assigns a deployment name to the application, based on its archive file or exploded directory.

appversion

String

none

Version identifier of the deployed application.

planversion

String

none

Version identifier of the deployment plan.

plan

String

none

Deployment plan to use when undeploying.

targets

String

none

Targets from which the application or module are undeployed. The value of this attribute is a comma-separated list of target servers, clusters, or virtual hosts.

retiretimeout

Integer

-1

Number of seconds before WebLogic Server undeploys the currently-running version of this application or module so that clients can start using the new version.

graceful

String

false

Stops the application after existing HTTP clients have completed their work. If you do not specify the graceful option, WebLogic Server immediately stops the application or module.

ignoresessions

String

false

Immediately places the application into Administration mode without waiting for current HTTP sessions to complete.

id

String

none

Task identifier of a running deployment task. Make sure that the identifier is unique to all other running deployment tasks. The system automatically generates a unique identifier if you do not specify one.

Required. Deployment name of a deployed application or module. If you do not specify this attribute, WebLogic Server assigns a deployment name to the application, based on its archive file or exploded directory.

If you do not specify the name attribute, you must specify a source.

source

String

none

Archive file or exploded archive directory to redeploy.

plan

String

none

Deployment plan to use when redeploying.

targets

String

none

Targets on which to redeploy the application or module. The value of this attribute is a comma-separated list of target servers, clusters, or virtual hosts.

upload

String

false

Copies the source files to the Administration Server's upload directory prior to redeployment.

delete_files

String

false

Removes static files from a server's staging directory. This attribute is valid only for unarchived deployments, and only for applications deployed using stage mode. You must specify target servers when using this attribute.

retiretimeout

Integer

-1

Number of seconds before WebLogic Server undeploys the currently-running version of this application or module so that clients can start using the new version.

filelist

String

none

One or more files to redeploy.

id

String

none

Task identifier of a running deployment task. Make sure that the identifier is unique to all other running deployment tasks. The system automatically generates a unique identifier if you do not specify one.

Start application in Administration mode, not Production mode (which is the default). Administration mode restricts access to an application to a configured Administration channel.

name

String

none

Required. Deployment name of a deployed application or module to start.

appversion

String

none

Version of the application to start.

planversion

String

none

Version of the deployment plan to use when starting the application.

targets

String

none

Targets on which to start the application or module. The value of this attribute is a comma-separated list of target servers, clusters, or virtual hosts.

retiretimeout

Integer

-1

Number of seconds before WebLogic Server undeploys the currently-running version of this application or module so that clients can start using the new version.

id

String

none

Task identifier of a running deployment task. Make sure that the identifier is unique to all other running deployment tasks. The system automatically generates a unique identifier if you do not specify one.

Indicates that a running application should switch to Administration mode and accept only Administration requests via a configured Administration channel. If this option is not specified, the running application is stopped and cannot accept Administration or client requests until is it restarted.

name

String

none

Required. Deployment name of a deployed application or module to stop.

appversion

String

none

Version identifier of the deployed application.

planversion

String

none

Version identifier of the deployment plan.

targets

String

none

Targets on which to stop the application or module. The value of this attribute is a comma-separated list of target servers, clusters, or virtual hosts.

graceful

Boolean

false

Stops the application after existing HTTP clients have completed their work. If you do not specify the graceful option, WebLogic Server immediately stops the application or module.

ignoresessions

Boolean

false

Immediately places the application into Administration mode without waiting for current HTTP sessions to complete.

rmiGraceperiod

Integer

-1

The amount of time, in seconds, that the Work Manager accepts and schedules RMI calls until there are no more RMI requests arriving within the RMI grace period during a graceful shutdown or a retirement.

retiretimeout

Integer

-1

Number of seconds before WebLogic Server undeploys the currently-running version of this application or module so that clients can start using the new version.

id

String

none

Task identifier of a running deployment task. Make sure that the identifier is unique to all other running deployment tasks. The system automatically generates a unique identifier if you do not specify one.

weblogic:update-app

Updates an application's deployment plan by redistributing the plan files and reconfiguring the application based on the new plan contents.

Attributes

Requires a Maven 2.0 project.

Can have an application already deployed.

Parameters

Table C-7 weblogic:update-app Parameters

Option

Type

Default

Description

name

String

none

Required. Deployment name of a deployed application or module. If you do not specify this attribute, WebLogic Server assigns a deployment name to the application, based on its archive file or exploded directory.

plan

String

none

Required. Deployment plan to use for updating the application's configuration. The specified deployment plan must be valid for the application's target servers. For example, the plan cannot contain null variables for required resources unless those resources were previously defined in the associated descriptors.

Update operations update only those descriptors for which there is a changed, not null value in the deployment plan. If a plan that is used by an update operation contains null variables, the current values in the corresponding descriptors are not updated.

planversion

String

none

Version identifier of the deployment plan.

targets

String

none

Targets on which to update the application or module. The value of this attribute is a comma-separated list of target servers, clusters, or virtual hosts.

upload

Boolean

false

Transfers a new deployment plan to the Administration Server before updating the application.

appversion

String

none

Version identifier of the deployed application.

id

String

none

Task identifier of a running deployment task. Make sure that the identifier is unique to all other running deployment tasks. The system automatically generates a unique identifier if you do not specify one.

Troubleshooting

Table C-8 describes some common Maven plug-in errors and helps you resolve them.

Table C-8 Maven Plug-In Errors

Configuration Step

Error Message

Resolution

Step 1: Generating the plug-in.

java –jar wljarbuilder.jar –profile weblogic-maven-plugin

Unable to access jarfile wljarbuilder.jar

Make sure that you have issued the command from within the MW_HOME/wlserver_10.3/server/lib/ directory.

Step 2: Extracting the pom.xml file from weblogic-maven-plugin.

The pom.xml file is created in MW_HOME/wlserver_10.3/server/lib/META-INF/maven/com.oracle.weblogic/weblogic-maven-plugin/pom.xml. From this location, you must copy the pom.xml file to MW_HOME/wlserver_10.3/server/lib/ (see Step 2 in Configuring and Using the WebLogic Maven Plug-In).

Step 3: Provisioning the weblogic-maven-plugin.jar in the Maven repository.

If the provisioning is successful, you will see a Build Successful message.

You must run the mvn install command at least once before invoking mvn weblogic:goal. This is required because there are Maven dependencies which must be retrieved from the Internet (see the Note in Step 3 in Configuring and Using the WebLogic Maven Plug-In).

You have executed the mvn install command from a location other than MW_HOME/wlserver_10.3/server/lib/.

There was no pom.xml file found under MW_HOME/wlserver_10.3/server/lib/.

Scripting on this page enhances content navigation, but does not change the content in any way.