25 February 2011

Using the “weblogic” prefix with the WebLogic Maven Plugin

The documentation for the WebLogic Maven Plugin describes a technique whereby the goals exposed by the plugin can be called using the short name (or prefix) weblogic


This means that instead of calling a goal using this form:

$ com.oracle.weblogic:weblogic-maven-plugin:help

You can use the much more convenient form of:

$ weblogic:help 

Sounds great.  However there is a documentation bug (logged and fixed for next release) which misses out one crucial step in the process. 

After extracting the pom.xml file from weblogic-maven-plugin.jar and editing it to specify the  <build> configuration that maps the plugin goalPrefix as weblogic;

And before
you issue the “mvn install:install-file –Dfile=weblogic-maven-plugin.jar -DpomFile=pom.xml”;

You first need to execute a simple “mvn install” command in the directory in which the pom.xml file resides;

Then you use the “mvn install:install-file ….” goal to install the weblogic-maven-plugin.jar file.

Blow by Blow

Let’s recap those steps:

  1. Generate the weblogic-maven-plugin.jar using the MW_HOME/wlserver_10.3/server/lib/wljarbuilder.jar file.

  2. Extract the pom.xml file from weblogic-maven-plugin.jar and copy/move it into the current working directory:

    $ jar xvf weblogic-maven-plugin.jar META-INF/maven/com.oracle.weblogic/weblogic-maven-plugin/pom.xml

    $ mv META-INF/maven/com.oracle.weblogic/weblogic-maven-plugin/pom.xml .

  3. Edit both ~/.m2/settings.xml and pom.xml to add the entries as described in the documentation:


  4. Execute “mvn install” to initially configure the plugin in the Maven repository:

    $ mvn install

    ** Extra info: if you look at the ~/.m2/repository/com/oracle/weblogic directory, you should now see a file called maven-metadata-local.xml in which the weblogic-maven-plugin is defined and mapped to the prefix weblogic.  If you neglect this step, then this file is not created and the weblogic-maven-plugin is not able to be accessed using the weblogic prefix. 

  5. Execute “mvn install:install-file” to install the weblogic-maven-plugin.jar file into the repository, using the pom.xml to supply the coordinates:

    $ mvn install:install-file –Dfile=weblogic-maven-plugin.jar –DpomFile=pom.xml

With that one extra step done you should now be able to execute a weblogic-maven-plugin goal simply using the weblogic prefix. 

I find a quick test using weblogic:help is the easiest way to verify it is working correctly:

Screen shot 2011-02-25 at 3.21.23 PM

Not working?

It’s crucial that the additional “mvn install” step is performed before you install the actual weblogic-maven-plugin.jar library for this to work. 

If you have installed the weblogic-maven-plugin as documented and either now want to use the short-name or tried the short-name and it didn’t work, then what I’d suggest is that you blow away the ~/.m2/repository/com/oracle directory and start again from scratch.  That should get you a clean install in which the weblogic prefix is mapped correctly to the weblogic-maven-plugin. 

22 February 2011

WebLogic Schema Files

If you are looking for the location of the public hosted schema files for WebLogic Server 10.3.x, here is is a starting link, select the version you are interested in: http://xmlns.oracle.com/weblogic/index.html.

Note: due to the recent OTN conversion to a different content management system, this may now be subjected to a redirection.

$ wget http://xmlns.oracle.com/weblogic/index.html
--2011-02-22 11:17:26--  http://xmlns.oracle.com/weblogic/index.html
Resolving xmlns.oracle.com...
Connecting to xmlns.oracle.com||:80... connected.
HTTP request sent, awaiting response... 301 Moved Permanently
Location: http://www.oracle.com/technology/weblogic/index.html [following]

21 February 2011

Using Secure Config Files with the WebLogic Maven Plugin

WebLogic Server has long had a mechanism to provide a more secure way of connecting to the Administration Server from client utilities such that the username and password do not need to be specified and therefore can’t be seen from the process list or command shell history.

This secure config authenticaiton mechanism works by first storing the username and password in encrypted form in an external file, and then using this later as the input credential with which to connect to the WebLogic Server domain,  along with the key that was used to encrypt the file. 

** From a security perspective,  controlling access to these files is vital since they permit connection access to the server, but that’s not the focus of this blog.

Securing Access from WLST Online:

Utility weblogic.Deployer, User Credential Arguments:

WLST, storeUserConfig Command:

WLST, Connection Examples:


This security mechanism is particularly interesting with the use of WebLogic Maven Plugin. 
In order to connect to the Administration Server to perform the desired deployment operation, the weblogic-maven-plugin  must supply valid credentials.  For quick and simple cases, this is typically done by specifying the username and password directly in the Maven pom.xml file. 

Here is an example:


As can be clearly seen, this results in the username and password entries being stored in clear-text form in the pom.xml file.

To avoid this password exposure, it would be ideal if the secure connection mechanism described above could be used, replacing the clear text username and password entries with the respective external userConfig and userKey files that specify the credentials that are used to perform the connection.

The documentation for the WebLogic Maven Plugin doesn’t explicitly describe this as a connection option for any of the goals it exposes:


But it does contain a reference to the weblogic.Deployer guide for additional usage information:


Which in turn, does support the use of the userconfigfile and userkeyfile parameters to specify the connection credentials:


Looking at the Mojo classes in the weblogic-maven-plugin.jar file, which implement the goals exposed by the plugin,  we can see that there is support for all these additional properties being set on the Mojo by Maven:

public class weblogic.tools.maven.plugins.DeployerMojo extends weblogic.tools.maven.plugins.BaseMojo{
java.util.List flags;
  protected boolean failonerror;
  protected java.lang.String adminurl;
  protected java.lang.String user;
  protected java.lang.String password;
  protected java.lang.String userConfigFile;
  protected java.lang.String userKeyFile;
  protected boolean advanced;
  protected boolean debug;
  protected boolean examples;
  protected boolean help;
  protected boolean noversion;
  protected boolean nowait;
  protected boolean purgetasks;
  protected boolean remote;
  protected java.lang.Integer timeout;
  protected boolean verbose;
  protected boolean version;
  protected boolean external_stage;
  protected boolean stage;
  protected java.lang.String id;
  protected java.lang.String name;
  protected boolean nostage;
  protected java.lang.String source;
  protected java.lang.String targets;
  protected java.lang.Integer retiretimeout;
  protected java.lang.Integer rmiGracePeriod;
  protected java.lang.String action;
  protected boolean upload;
  protected java.lang.String plan;
  protected java.lang.String planversion;
  protected boolean adminmode;
  protected java.lang.String appversion;
  protected boolean graceful;
  protected boolean ignoresessions;
  protected java.lang.String securityModel;
  protected boolean isLibrary;
  protected java.lang.String libSpecVer;
  protected java.lang.String libImplVer;
  protected java.lang.String submoduletargets;
  protected boolean usenonexclusivelock;
  protected boolean allversions;
  protected boolean enableSecurityValidation;
  protected java.lang.String deleteFiles;
  public weblogic.tools.maven.plugins.DeployerMojo();
  public void execute() throws org.apache.maven.plugin.MojoExecutionException;
  protected java.lang.String[] getArgsRedeployer(java.util.List);

Therefore to use this more secure connection approach, it should be a simple case of creating and storing the relevant userconfig and userkey files using WLST, and referencing them in the Maven pom.xml file, right?

The answer to this is, yes, but …

It turns out we have a very minor bug that prevents this from working in WLS 10.3.4.  The bug number is 10382796 for reference. It has already been fixed for the next release of WLS.  Should you wish to use this secure connection mechanism, I’d suggest opening a support TAR, referencing the bug number and asking for a backport of the bug fix.

Having access to the bug fix, I can walk through the steps required to configure and use this connection mechanism and show it in operation.

1. Create the userConfigFile and userKeyFile from the weblogic.WLST utility

This is a straight forward step and is well documented in the links shown above.

Connect to the running WebLogic Server domain using WLST and issue the storeUserConfig command, specifying the locations of the userConfig and userKey files that will be generated:

Screen shot 2011-02-21 at 10.19.28 AMIn this case, we have created the files as ‘/tmp/wls.config’ and ‘/tmp/wls.key’.

We can validate these files work correctly using the weblogic.Deployer utility to connect to the WebLogic Server domain, using the userconfigfile and –userkeyfile parameters:

$ java weblogic.Deployer -adminurl t3://localhost:7001 -userconfigfile /tmp/wls.config -userkeyfile /tmp/wls.key –listapps
Screen shot 2011-02-21 at 10.59.28 AM

2. Install WebLogic Maven Plugin and Crypto Library into Maven Repository

Summary of steps in this section: in order to use the WebLogic Maven Plugin from Maven, it needs to generated from a WebLogic Server installation, then installed into the local repository.  Furthermore, to use the secure config file connection mechanism, an additional library must also be installed into the repository to support the encryption operations.  This must be manually installed first, then added as dependency of the weblogic-maven-plugin via its pom.xml.  Finally, the weblogic-maven-plugin.jar file is installed.

Install Dependency crytpo.jar into Maven Repository

The <MW_HOME>/modules/crypto.jar is required to support the use of the secure config file connection mechanism by the weblogic-maven-plugin.  It must be installed into the Maven repository first.

$ cd <MW_HOME>
$ cd modules
$ mvn install:install-file -Dfile=cryptoj.jar -DgroupId=com.oracle.cryptoj -DartifactId=cryptoj -Dversion=1.0 -Dpackaging=jar

Generate weblogic-maven-plugin.jar and extract pom.xml

To generate the weblogic-maven-plugin and its pom.xml file, follow steps 1, 2 from the documentation:


$ java -jar wljarbuilder.jar -profile weblogic-maven-plugin
$ jar xvf weblogic-maven-plugin.jar META-INF/maven/com.oracle.weblogic/weblogic-maven-plugin/pom.xml
$ mv META-INF/maven/com.oracle.weblogic/weblogic-maven-plugin/pom.xml .

** It is important that the pom.xml file be available in the directory in which wewill invoke the first “mvn install” command shown below.  The easiest way to do this is as shown above, copy/move it into the same directory as the weblogic-maven-plugin.jar file so all the files we will work with are located together.

Edit pom.xml to specify cryptoj dependency and goalPrefix

There are two changes that need to be made to the pom.xml file.  The first change is to add the cryptoj library as a dependency to the weblogic-maven-plugin.  The second is to add a configuration section to allow the use of the shortname weblogic to invoke the Maven goals.

Here is the final pom.xml with changes at lines [16-22] and [24-35]:

   1:  <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
   2:    <modelVersion>4.0.0</modelVersion>
   3:    <groupId>com.oracle.weblogic</groupId>
   4:    <artifactId>weblogic-maven-plugin</artifactId>
   5:    <packaging>maven-plugin</packaging>
   6:    <version>10.3.4</version>
   7:    <name>Maven Mojo Archetype</name>
   8:    <url>http://maven.apache.org</url>
   9:    <dependencies>
  10:      <dependency>
  11:        <groupId>org.apache.maven</groupId>
  12:        <artifactId>maven-plugin-api</artifactId>
  13:        <version>2.0</version>
  14:      </dependency>
  16:      <!-- Dependency on cryptoj library -->
  17:      <dependency>
  18:        <groupId>com.oracle.cryptoj</groupId>
  19:        <artifactId>cryptoj</artifactId>
  20:        <version>1.0</version>
  21:      </dependency>
  22:    </dependencies>
  24:    <!-- Use weblogic goalPrefix -->
  25:    <build>
  26:      <plugins>
  27:        <plugin>
  28:          <artifactId>maven-plugin-plugin</artifactId>
  29:          <version>2.3</version>
  30:          <configuration>
  31:             <goalPrefix>weblogic</goalPrefix>
  32:          </configuration>
  33:        </plugin>
  34:      </plugins>
  35:    </build>
  36:  </project>

Install weblogic-maven-plugin

Now we want to actually install the weblogic-maven-plugin into the Maven repository.  There are two install commands that are issued here, which both need to be followed.  The first command implictly uses the edited pom.xml file and configures the weblogic-maven-plugin inside the Maven repository.  The second command performs the actual installation of the weblogic-maven-plugin library into the Maven repository.

** Ensure the pom.xml file we have edited is in the directory in which you will execute the commands.

$ mvn install
$ mvn install:install-file -Dfile=weblogic-maven-plugin.jar -DpomFile=pom.xml 

We should see output from these commands as shown in the screencaps below:

Screen shot 2011-02-21 at 11.59.42 AMScreen shot 2011-02-21 at 12.03.47 PM

3. Configure pom.xml to use secure config file for authentication

Now that the secure configuration files have been generated, the cryptoj dependency and the oracle-maven-plugin  installed into the Maven repository, we can configure your Maven pom.xml file to use them to connect to the WebLogic Server domain.

Instead of using the <username> and <password> elements as part of the weblogic-maven-plugin <configuration> stanza to specify the connection credentials, we use the <userConfigFile> and <userKeyFile> elements and point to the location of the files we generated from WLST earlier.

A fully configured Maven pom.xml for a Java EE 5 Web application is shown below. 

Lines [13-18] shows the creation of properties that identify the location of the relevant external files we generated from WLST.

Lines [67-69] shows the use of the <userConfigFile> and <userKeyfile> elements to specify the use of the secure config file authentication model.

Example pom.xml:

   1:  <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   2:    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
   3:    <modelVersion>4.0.0</modelVersion>
   5:    <groupId>sab.demo.maven</groupId>
   6:    <artifactId>webapp</artifactId>
   7:    <packaging>war</packaging>
   8:    <version>1.0-SNAPSHOT</version>
  10:    <name>webapp JEE5 Webapp</name>
  11:    <url>http://maven.apache.org</url>
  13:    <!-- weblogic-maven-plugin properties -->
  14:    <properties>        
  15:      <weblogic.adminurl>t3://localhost:7001</weblogic.adminurl>    
  16:      <weblogic.configfile>/tmp/wls.config</weblogic.configfile>
  17:      <weblogic.keyfile>/tmp/wls.key</weblogic.keyfile>
  18:    </properties>  
  20:    <dependencies>
  22:      <dependency>
  23:        <groupId>javax.servlet</groupId>
  24:        <artifactId>servlet-api</artifactId>
  25:        <version>2.5</version>
  26:        <scope>provided</scope>
  27:      </dependency>
  29:      <dependency>
  30:        <groupId>javax.servlet.jsp</groupId>
  31:        <artifactId>jsp-api</artifactId>
  32:        <version>2.1</version>
  33:        <scope>provided</scope>
  34:      </dependency>
  36:      <dependency>
  37:        <groupId>junit</groupId>
  38:        <artifactId>junit</artifactId>
  39:        <version>3.8.1</version>
  40:        <scope>test</scope>
  41:      </dependency>
  43:    </dependencies>
  45:    <build>
  46:      <plugins>
  47:        <plugin>
  48:          <groupId>org.apache.maven.plugins</groupId>
  49:          <artifactId>maven-compiler-plugin</artifactId>
  50:          <version>2.0.2</version>
  51:          <configuration>
  52:            <source>1.5</source>
  53:            <target>1.5</target>
  54:          </configuration>
  55:        </plugin>
  57:      <plugin>
  58:          <groupId>com.oracle.weblogic</groupId>         
  59:          <artifactId>weblogic-maven-plugin</artifactId>
  60:          <version>10.3.4</version>
  61:          <configuration>
  62:              <adminurl>${weblogic.adminurl}</adminurl>
  63:              <!--
  64:              <user>${weblogic.user}</user>             
  65:              <password>${weblogic.password}</password>                                
  66:              -->
  67:              <!-- Use external connection files --> 
  68:              <userConfigFile>${weblogic.configfile}</userConfigFile>
  69:              <userKeyFile>${weblogic.keyfile}</userKeyFile>            
  70:              <source>
  71:                  ${project.build.directory}/${project.build.finalName}.${project.packaging}
  72:              </source>
  73:              <name>${project.build.finalName}</name>
  74:          </configuration>
  75:       </plugin>    
  77:      </plugins>    
  79:      <finalName>webapp</finalName>
  80:    </build>
  81:  </project>

Verify it Works

With all configuration and installation tasks performed, we can now verify that the weblogic-maven-plugin can successfully connect to the WebLogic Server domain.

To do this, I typically use the weblogic:list-apps goal – this doesn’t perform any deployment operation, but does connect to the target server, authenticates, and returns a list of the currently deployed applications.

The output from executing weblogic:list-apps is shown below.  Note the [INFO] output which shows the underlying weblogic.Deployer command that is issued, in which the –userconfigfile and –userkeyfile parameters are used:

$ mvn weblogic:list-apps
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Building webapp JEE5 Webapp 1.0-SNAPSHOT
[INFO] ------------------------------------------------------------------------
[INFO] --- weblogic-maven-plugin:10.3.4:list-apps (default-cli) @ webapp ---
weblogic.Deployer invoked with options:  -noexit -adminurl t3://localhost:7001 -userconfigfile /tmp/wls.config -userkeyfile /tmp/wls.key -listapps
jersey-bundle [LibSpecVersion=1.1.1,LibImplVersion=] <ACTIVE VERSION>
jsr311-api [LibSpecVersion=1.1.1,LibImplVersion=1.1.1] <ACTIVE VERSION>
jackson-jaxrs [LibSpecVersion=1.0,LibImplVersion=1.1.1] <ACTIVE VERSION>
jettison [LibSpecVersion=1.1,LibImplVersion=1.1] <ACTIVE VERSION>
jackson-core-asl [LibSpecVersion=1.0,LibImplVersion=1.1.1] <ACTIVE VERSION>
jackson-mapper-asl [LibSpecVersion=1.0,LibImplVersion=1.1.1] <ACTIVE VERSION>
Number of Applications Found : 9
[INFO] ------------------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 6.150s
[INFO] Finished at: Mon Feb 21 12:31:22 CST 2011
[INFO] Final Memory: 12M/81M
[INFO] ------------------------------------------------------------------------


In this post, I’ve shown how the the WebLogic Maven Plugin can support the use of secure config files to prevent the need to specify administrator passwords in clear text in the Maven pom.xml. 

I would like to again note that there is a very minor known bug that prevents this being used with the WLS 10.3.4 release, which has already been fixed  in the next release code line. 

If you are wanting to use this feature and need to get a patch, the bug to refer to is #10382796.

11 February 2011

Using JAX-RS with WebLogic Server 10.3.4

There's been a flurry of blogs recently about using JAX-RS.

It may have slipped under the radar a little, but WebLogic Server 10.3.4 now also provides support for deploying applications that use JAX-RS Web Services.

Here's the documentation for it:

Programming RESTful Web Services


With WebLogic Server, the JAX-RS support is handled in the same manner as JSF, in that a set of optional shared-libraries are provided that can be deployed to the server, which makes the JAX-RS framework available for deployed applications to use. Applications then reference these shared-libraries using the relevant weblogic deployment descriptor.

What I'd like to do in this blog is to show JAX-RS working on WebLogic Server 10.3.4 and at the same time, how the NetBeans 7.0 Beta release supports WebLogic Server to make the development of JAX-RS based applications quick and efficient by removing some of the work required in deploying and referencing the libraries.  .

1. Launch NetBeans and register a WebLogic Server 10.3.4 instance.

I won't go through the individual steps as this is very straight forward. In my particular case, I have a brand new domain I am using, so there are no applications or shared-libraries deployed.


2. Create a new Java EE Web project

The next step is to create a new Java EE Web project using the NetBeans project wizards. This project will host our JAX-RS resource and is what we will deploy and test on WebLogic Server.

Create a new Java Web Project and fill in the project details.

For the Server, I specify the WebLogic Server domain that I registered earlier, leave the Context-Path and finish the project creation and click finish to create the new project.

3. Add a JAX-RS resource to the project.

With the Java Web project created, I can now add a new JAX-RS resource to it, again using a NetBeans wizard -- the simplest way to test this is to use the "RESTful Web Services from Patterns" wizard and select the "Simple Root Resource"option.

Select the “Simple Root Resource” option.

Fill in the details for the resource to be created. In this case, I am specifying a MIME Type of "text/html" to make the default end point easy to test from a browser.

On the last page of the wizard, I am presented with options for how to configure the project. NetBeans has knowledge of how WebLogic Server employs JAX-RS and presents them to you.

I select the option to have NetBeans automatically configure the JAX-RS servlet adapter in web.xml and then I select the "Use server bundled Jersey Library" option.

The JAX-RS resource is then created and added to the project.

Looking at the project, I can see a number of things have changed:

The existing web.xml descriptor has been modified to expose the Jersey Servlet adapter.

A new weblogic.xml deployment descriptor has been added, which references the required JAX-RS shared-library that will be deployed on the server.

And a new class has been added that represents the JAX-RS resource.

After editing the generated getHtml method to return a string I'll recognize, the project is ready to be deployed and tested.

4. Deploy and run the project

Selecting "Run" from the project menu, NetBeans will perform the task of compiling and deploying the project to the target WebLogic Server domain.

NetBeans performs the necessary deployment operations.

Now the interesting thing that happens as part of this "run" process (and why it takes 27 seconds most likely) is that NetBeans has recognized that the target WebLogic Server domain doesn't have the necessary shared-library that the project is using. To resolve this problem, it seamlessly deploys the required library from the $WL_HOME/common/deployable-libraries directory as part of the deployment process.

Once the deployment of the project has completed, looking at the registered WebLogic Server domain, I can now see the jersey-bundle#1.1.1@ library present on the server.

We can now test the JAX-RS resource.

5. Test the JAX-RS Resource

Expanding the project, there is a "RESTful Web Services" folder that presents a view of the JAX-RS resources in the project. To test the end-point, I select the method and click the "Test Resource URI" option.

This opens a browser window and shows the results of successfully calling the getHtml method.

So there you have it, a JAX-RS resource created in NetBeans, deployed and running on WebLogic Server 10.3.4.

As a final piece to add to this blog, I'll also show off another new feature that NetBeans 7.0 has added to further support WebLogic Server. The new "local deployment" model deploys applications from an exploded, local directory. This means that deployment to WebLogic Server is now much better since a code change doesn't require a full packaging and "deployment" cycle to test. In fact, using NetBeans with WebLogic Server nows offer compile-on-save and test functionality!

6. Add another method and test

With the application deployed, I can now change the class to add more functionality. I'll add two new methods that sayHello and sayBye to a user. In these methods, I'll use the @PathParam and @QueryParam annotations respectively to extract the value from the URI and set it automatically on the method call.

To test these new methods, all I need to do is save the change, NetBeans automatically compiles the class and I can immediately test if from the browser, without needing to issue a redeployment operation!

First off, let's say hello. I use the path variable here to to specify my name:


Then I'll say goodbye, this time using a query parameter to specify my name:


And that's all there is to getting a basic JAX-RS resource up and running on WebLogic Server, developed and deployed in next to no time using NetBeans 7.0.