Weblogic deployment using the Oracle weblogic maven plugin

With the PS3 release of the SOA Suite a new version, 10.3.4, of Weblogic has been released. Amongst others, this release also includes a new Weblogic Maven plugin (weblogic-maven-plugin) that allows interaction with Weblogic from within a Maven environment. As far as I know, this plugin is the successor of the Codehaus Weblogic plugin. That one was a bit difficult to use because it required some other not publicly available Weblogic dependencies which have now been included with the new plugin. Unfortunately, this plugin is not (yet?!) available in any of the public Maven repositories so you have to put it in your own repository. Because of the size (more than 50 MB) the plugin is not included with Weblogic as-is but must be created first just as other weblogic client utilities. The documentation of the new plugin describes in detail how to create and use the plugin. In this blog I’ll summarize them (NB, I assume you’re a little bit familiar Maven).

In summary:

1. Create the plugin.
2. Deploy it to an artifact repository.
3. Use the plugin in your project.

Create the plugin

The Weblogic JarBuilder is a utility to create a variety of client jars, now including the maven plugin.

Go to MW_HOME/wlserver_10.3/server/lib/ and issue the command:

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

This creates the plugin file weblogic-maven-plugin.jar.

Deploy the generated jar file to your Maven artifact repository.

You can install it in your local repository only, but it’s better to deploy it to your company repository and make it easily available for others to use too. Use the pom.xml file that’s included in the generated jar file (META-INF/maven/com.oracle.weblogic/weblogic-maven-plugin/pom.xml) because it includes the identification of the plugin and its dependencies. Extract the pom file and issue the following command:

mvn deploy:deploy-file -Dfile=weblogic-maven-plugin.jar
                       -DpomFile=pom.xml
                       -DrepositoryId=amisrepo-third-party
                       -Durl=http://reposerver/nexus/content/repositories/thirdparty/

(NB use your own url and repositoryId) or use the webinterface of the repository (e.g. Nexus) as you can see in this picture.

Use the plugin in a project.

For this you need a maven enabled project. Since JDeveloper provides very limited support for Maven I assume that most ADF projects are not Maven enabled and that ant and / or the standard JDeveloper deploy deploy profile is used to build the war and ear file. This example expects the ear file to be present in the application’s deploy directory. Add the following pom.xml file to the application’s root directory (NB Use where your own identification and file name):

<?xml	version="1.0"	encoding="UTF-8" ?>
<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>
  <groupId>nl.amis.demo.xyz</groupId>
  <artifactId>mysimpleapp</artifactId>
  <version>1.0-SNAPSHOT</version>
  <name>mysimpleapp example application</name>
  <packaging>pom</packaging>
  <build>
    <plugins>
      <plugin>
        <groupId>com.oracle.weblogic</groupId>
        <artifactId>weblogic-maven-plugin</artifactId>
        <version>10.3.4</version>
        <configuration>
          <adminurl>t3://localhost:7101</adminurl>
          <user>weblogic</user>
          <password>weblogic1</password>
          <upload>true</upload>
          <action>deploy</action>
          <remote>false</remote>
          <verbose>true</verbose>
          <source>deploy/mysimpleapp.ear</source>
          <name>mysimpleapp</name>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

You can now use Maven from the command line to deploy the earfile to weblogic:

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

Other commands that are available are: undeploy, redeploy, start-app, stop-app, list-app, update-app and help. These commands are similar to those supported by the command-line utility, weblogic.Deployer, which is actually not surprising because the Maven plugin is actually a wrapper around this weblogic.Deployer. Each command allows different parameters, as described in the weblogic-Maven-plugin documentation (by the way, the documentation also describes how to shorten the usage to mvn weblogic:deploy). Unfortunately, the plugin passes all arguments as-is to weblogic.Deployer and when an argument is not allowed, it raises an error and the process results in a build failure. This occurs for example with the source argument and the commands undeploy, start-app and stop-app. This means that you cannot use one configuration for all the commands (e.g. deploy and undeploy) and must use a workaround. Probably the easiest one is to provide the source argument as a command-line parameter like -Dsource=deploy/mysimpleapp.ear. Another option could be to use multiple profiles with different configurations for deploy and undeploy. I hope this will be fixed soon.

By the way, deployment to an earlier Weblogic, e.g. 10.3.3.0, works too and also to the JDeveloper embedded Weblogic.

Use the plugin in a Maven enabled project

Now, when your application is maven enabled I would recommend a slightly different approach and to use a separate deployment project that is solely aimed at deploying the application. Use the maven dependency plugin to retrieve the ear file from your company repository and define profiles for different servers. This provides better control of the deployment and allows different versions to be deployed to different servers. An ideal situation for a build server like Hudson. This is an example:

<?xml version="1.0" encoding="UTF-8" ?>
<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>nl.amis.demo.xyz</groupId>
    <artifactId>mysimpleapp</artifactId>
    <version>1.0-SNAPSHOT</version>
  </parent>
  <artifactId>mysimpleapp-deploy</artifactId>
  <name>mysimpleapp deployment</name>
  <packaging>pom</packaging>
  <properties>
    <app.deploy.version>${project.version}</app.deploy.version>
    <ear.filename>${project.build.directory}\mysimpleapp-ear-${app.deploy.version}.ear</ear.filename>
  </properties>
  <profiles>
    <profile>
      <id>local</id>
      <activation>
        <activeByDefault>false</activeByDefault>
      </activation>
      <properties>
        <wls.admin.url>t3://localhost:7101</wls.admin.url>
        <wls.admin.username>weblogic</wls.admin.username>
        <wls.admin.password>weblogic1</wls.admin.password>
      </properties>
    </profile>
  </profiles>
  <build>
     <plugins>
       <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-deploy-plugin</artifactId>
        <version>2.5</version>
        <configuration>
          <skip>true</skip>
        </configuration>
      </plugin>
      <plugin>
         <groupId>com.oracle.weblogic</groupId>
         <artifactId>weblogic-maven-plugin</artifactId>
         <version>10.3.4</version>
         <configuration>
           <adminurl>${wls.admin.url}</adminurl>
          <user>${wls.admin.username}</user>
           <password>${wls.admin.password}</password>
           <upload>true</upload>
           <action>deploy</action>
           <remote>false</remote>
           <verbose>true</verbose>
           <source>${ear.filename}</source>
           <name>mysimpleapp</name>
         </configuration>
       </plugin>
       <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <version>2.1</version>
        <executions>
          <execution>
            <id>copy-ear</id>
            <phase>package</phase>
            <goals>
              <goal>copy</goal>
            </goals>
            <configuration>
              <artifactItems>
                <artifactItem>
                  <groupId>nl.amis.demo.xyz</groupId>
                  <artifactId>mysimpleapp-ear</artifactId>
                  <version>${app.deploy.version}</version>
                  <type>ear</type>
                  <overWrite>true</overWrite>
                  <outputDirectory>target</outputDirectory>
                </artifactItem>
              </artifactItems>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
   </build>
  <dependencies>
    <dependency>
      <groupId>nl.amis.demo.xyz</groupId>
      <artifactId>mysimpleapp-ear</artifactId>
      <version>${app.deploy.version}</version>
      <type>ear</type>
    </dependency>
  </dependencies>
</project>

You can now perform a deployment with the following statement:

mvn package com.oracle.weblogic:weblogic-maven-plugin:deploy -Plocal

The package goal is to retrieve the ear file from the repository and the -Plocal activates the local profile and thus the arguments for the local weblogic. I have the maven-deploy-plugin configured to prevent this artifact to be deployed to the artifact repository (Note that for Maven the term deploy means deploying to the artifact repository, not the application server (I know, it’s a bit confusing)).

The argument app.deploy.version allows to override the version (that defaults to the project version), for example:

mvn clean package com.oracle.weblogic:weblogic-maven-plugin:deploy -Plocal -Dapp.deploy.version=1.5

The documentation also describes how to bind the plugin to a maven lifecycle phase, e.g. the install phase. This will deploy the ear file when the install phase is executed. This is actually a good idea, but since the install phase is executed quite often (mvn clean install is a normal way to execute the maven build lifecycle) it’s also good practice to use profiles to prevent continuous deployment. An often used practice is to bind deployment to the pre-integration-test phase and undeployment to the post-integration-test phase, but only when you actually perform an integration test. I’m not including examples for that, if you’re interested let me know.

To summarize. The weblogic-maven-plugin is a very valuable plugin for deployment to Weblogic by Maven, it performs great and I will certainly use it on my projects. I’m especially happy with deployment to earlier versions of Weblogic too.