The Buttso Blathers

12 December 2011

WebLogic Server 12c - Maven Usage Notes

Note: apologies for the formatting, this posting was a cut and paste from a .docx document and thus has all the styles inlined. In the interests of time, I thought it was better to just post it as-is and make it available, rather than try and reformat it. Which I know I'd keep pushing off until eternity.

This document provides a short overview of installing, configuring and using the new wls-maven-plugin provided in WebLogic Server 12c.

Convention Over Configuration

With the wls-maven-plugin:12.1.1.0 we have followed the theme of Maven and used a convention-over-configuration approach. This means that for a set of the commonly used configuration elements, we have adopted a sensible, consistent set of default values that can be used across all of the goals. This reduces the amount of configuration necessary to use the plugin and helps achieve uniform goal executions, even in different environments.

The common configuration elements are:

middlewareHome: ${project.basedir}/Oracle/Software

weblogicHome: “wlserver” or “wlserver_12.1”, depending on the install type

domainHome: ${project.basedir}/Oracle/Domains

source: ${project.build.directory}/${project.build.finalName}.${project.packaging}

adminurl: t3://localhost:7001

While these configuration parameters have default values, they can all be overridden in a pom.xml file or on the command line as need be.

However by having them be sensible defaults, they can be left out of a configuration section and used consistently across all of the goals.

As an example, it’s possible to issue the following commands that all use the same WLS installation and domain without specifying any repetitive values:

$ wls:install -
DartifactLocation=/Users/sbutton/Downloads/wls/wls_1211/wls1211_dev.zip

$ wls:create-domain –Duser=weblogic –Dpassword=welcome1

$ wls:start-server

Installing the Plugin

For WLS 12c, the wls-maven-plugin is provided as a pre-built jar file and the

accompanying pom.xml file is also provided as an easily accessible file in the same directory.

$MW_HOME/wlserver/server/lib/wls-maven-plugin.jar

$MW_HOME/wlserver/server/lib/pom.xml

The wls-maven-plugin is installed using the following commands:

$ cd $MW_HOME/wlserver/server/lib

$ mvn install

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

The default pom.xml file now has the required setting to enable the use of the “wls” goal prefix enabled by default.

To use the “wls” goalPrefix, you will need to edit the Maven settings.xml file and add the following entry:

<pluginGroups>

<pluginGroup>com.oracle.weblogic</pluginGroup>

</pluginGroups>

Once you have installed the plugin, you can very simply validate it using the wls:help goal.

$ mvn wls:help

This goal does not require a project or pom.xml and will display the list of goals available in the wls-maven-plugin if the plugin has been successfully installed.

Basic Configuration of Plugin

Below is an example of a basic Java EE 6 Web Application pom.xml file that enables the use of the wls-maven-plugin.

<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/xsd/maven-4.0.0.xsd">

<artifactId>maven-demo</artifactId>

<version>1.0-SNAPSHOT</version>

<name>maven-demo</name>

<endorsed.dir>${project.build.directory}/endorsed</endorsed.dir>

<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

</properties>

<groupId>javax</groupId>

<artifactId>javaee-web-api</artifactId>

<scope>provided</scope>

</dependency>

</dependencies>

<build>

...

<plugin>

<groupId>com.oracle.weblogic</groupId>

<artifactId>wls-maven-plugin</artifactId>

<version>12.1.1.0</version>

</plugin>

</plugins>

</build>

</project>

Install

This goal installs WLS into a local directory to enable it to be used execute the other goals, as well as a installation to create a WLS domain that can be used to deploy and test the application represented as the Maven project.

To install, you need a distribution to install. This is specified using the <artifactLocation> configuration element in the wls-maven-plugin section of the pom.xml, or specify it using the –DartifactLocation property when Maven is invoked.

The target directory for the installation is specified using the optional weblogicHome configuration element. This is set to ${basedir}/Oracle/Software by default. Specifying a <middlewareHome> value will direct the install to be performed in the specified location.

I will focus on the zip distribution since it reflects a development usage model.

The location of the zip distribution can be specified as one of the following:

a) local file reference

For a local file reference, you specify the path on the local file system

<groupId>com.oracle.weblogic</groupId>

<artifactId>wls-maven-plugin</artifactId>

<artifactLocation>

/Users/sbutton/Downloads/wls/wls_1211/wls1211_dev.zip

</artifactLocation>

</configuration>

</plugin>

The execution of the wls:install goal is shown below.

sbutton:~/Projects/Java/wls-maven-doc/maven-demo $ mvn wls:install

[INFO] Scanning for projects...

[INFO]

[INFO] ------------------------------------------------------------------------

[INFO] Building maven-demo 1.0-SNAPSHOT

[INFO] ------------------------------------------------------------------------

[INFO]

[INFO] --- wls-maven-plugin:12.1.1.0:install (default-cli) @ maven-demo ---

[INFO] ++====================================================================++

[INFO] ++ wls-maven-plugin: install ++

[INFO] ++====================================================================++

[INFO] Installing /Users/sbutton/Downloads/wls/wls_1211/wls1211_dev.zip into /Users/sbutton/Projects/Java/wls-maven-doc/maven-demo/Oracle/Software

[INFO] Installing the product, this may take some time.

[INFO] Executing: [cmd:[/bin/bash, -c, chmod +x ./configure.sh; ./configure.sh]]

[INFO] Process being executed, waiting for completion.

[INFO] [exec] **************************************************

[INFO] [exec] WebLogic Server 12c (12.1.1.0) Zip Configuration

[INFO] [exec]

[INFO] [exec] MW_HOME: /Users/sbutton/Projects/Java/wls-maven-doc/maven-demo/Oracle/Software

[INFO] [exec] JAVA_HOME: /System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home

[INFO] [exec] **************************************************

...

[INFO] [exec] BUILD SUCCESSFUL

[INFO] [exec] Total time: 0 seconds

[INFO] [configure script] exit code: 0

[INFO] ------------------------------------------------------------------------

[INFO] BUILD SUCCESS

[INFO] ------------------------------------------------------------------------

[INFO] Total time: 1:53.210s

[INFO] Finished at: Wed Nov 23 15:46:53 CST 2011

[INFO] Final Memory: 3M/81M

[INFO] ------------------------------------------------------------------------

b) URL reference

<groupId>com.oracle.weblogic</groupId>

<artifactId>wls-maven-plugin</artifactId>

<artifactLocation>

http://test.us.oracle.com:7001/downloads/wls1211_dev.zip

</artifactLocation>

</configuration>

</plugin>

The execution of the wls:install goal is shown below.

sbutton:~/Projects/Java/wls-maven-doc/maven-demo $ mvn wls:install

[INFO] Scanning for projects...

[INFO]

[INFO] ------------------------------------------------------------------------

[INFO] Building maven-demo 1.0-SNAPSHOT

[INFO] ------------------------------------------------------------------------

[INFO]

[INFO] --- wls-maven-plugin:12.1.1.0:install (default-cli) @ maven-demo ---

[INFO] ++====================================================================++

[INFO] ++ wls-maven-plugin: install ++

[INFO] ++====================================================================++

[INFO] Installing http://test.us.oracle.com:7001/downloads/wls1211_dev.zip into /Users/sbutton/Projects/Java/wls-maven-doc/maven-demo/Oracle/Software

[INFO] Attempt to download artifact from maven repo failed - Artifact not found

[INFO] Attempt to download the weblogic server instance directly from url.

[INFO] Downloading the file ...

...

[INFO] [exec] BUILD SUCCESSFUL

[INFO] [exec] Total time: 0 seconds

[INFO] [configure script] exit code: 0

[INFO] ------------------------------------------------------------------------

[INFO] BUILD SUCCESS

[INFO] ------------------------------------------------------------------------

[INFO] Total time: 4:23.710s

[INFO] Finished at: Wed Nov 23 15:53:21 CST 2011

[INFO] Final Memory: 3M/81M

[INFO] ------------------------------------------------------------------------

c) Maven Artifact

Here the distribution is retrieved from the local Maven repository itself. This means it needs to have been installed into the repository or pulled over from a remote repository at some point.

To install wls1211-dev.zip into Maven repository the following type of command can be used:

sbutton:~ $ mvn install:install-file -Dfile=wls1211_dev.zip
-DgroupId=com.oracle.weblogic -DartifactId=wls-dev
-Dpackaging=zip -Dversion=12.1.1.0

[INFO] Scanning for projects...

[INFO]

[INFO] ------------------------------------------------------------------------

[INFO] Building Maven Stub Project (No POM) 1

[INFO] ------------------------------------------------------------------------

[INFO]

[INFO] --- maven-install-plugin:2.3.1:install-file (default-cli) @ standalone-pom ---

[INFO] Installing /Users/sbutton/Downloads/wls/wls_1211/wls1211_dev.zip to /Users/sbutton/.m2/repository/com/oracle/weblogic/wls-dev/12.1.1.0/wls-dev-12.1.1.0.zip

[INFO] Installing /var/folders/cL/cLTyZKXjGgmQhEpoV+U-DE+++TI/-Tmp-/mvninstall7575420374983698784.pom to /Users/sbutton/.m2/repository/com/oracle/weblogic/wls-dev/12.1.1.0/wls-dev-12.1.1.0.pom

[INFO] ------------------------------------------------------------------------

[INFO] BUILD SUCCESS

[INFO] ------------------------------------------------------------------------

[INFO] Total time: 11.089s

[INFO] Finished at: Wed Nov 23 15:30:17 CST 2011

[INFO] Final Memory: 3M/81M

[INFO] ------------------------------------------------------------------------

This installs wls1211-dev.zip as a Maven artifact with the following coordinate:

com.oracle.weblogic:wls-dev:zip:12.1.1.0

To use this Maven artifact as the distribution to install, the plugin looks like the below.

<groupId>com.oracle.weblogic</groupId>

<artifactId>wls-maven-plugin</artifactId>

<artifactLocation>

com.oracle.weblogic:wls-dev:zip:12.1.1.0

</artifactLocation>

</configuration>

</plugin>

The execution of the wls:install goal is shown below.

sbutton:~/Projects/Java/wls-maven-doc/maven-demo $ mvn wls:install

[INFO] Scanning for projects...

[INFO]

[INFO] ------------------------------------------------------------------------

[INFO] Building maven-demo 1.0-SNAPSHOT

[INFO] ------------------------------------------------------------------------

[INFO]

[INFO] --- wls-maven-plugin:12.1.1.0:install (default-cli) @ maven-demo ---

[INFO] ++====================================================================++

[INFO] ++ wls-maven-plugin: install ++

[INFO] ++====================================================================++

[INFO] Installing com.oracle.weblogic:wls-dev:zip:12.1.1.0 into /Users/sbutton/Projects/Java/wls-maven-doc/maven-demo/Oracle/Software

[INFO] Installing the product, this may take some time.

[INFO] Executing: [cmd:[/bin/bash, -c, chmod +x ./configure.sh; ./configure.sh]]

[INFO] Process being executed, waiting for completion.

[INFO] [exec] **************************************************

[INFO] [exec] WebLogic Server 12c (12.1.1.0) Zip Configuration

[INFO] [exec]

[INFO] [exec] MW_HOME: /Users/sbutton/Projects/Java/wls-maven-doc/maven-demo/Oracle/Software

[INFO] [exec] JAVA_HOME: /System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home

[INFO] [exec] **************************************************

[INFO] [exec]

...

[INFO] [exec]

[INFO] [exec] Your environment has been set.

[INFO] [exec]

[INFO] [exec] BUILD SUCCESSFUL

[INFO] [exec] Total time: 0 seconds

[INFO] [configure script] exit code: 0

[INFO] ------------------------------------------------------------------------

[INFO] BUILD SUCCESS

[INFO] ------------------------------------------------------------------------

[INFO] Total time: 1:57.549s

[INFO] Finished at: Wed Nov 23 15:35:32 CST 2011

[INFO] Final Memory: 4M/81M

[INFO] ------------------------------------------------------------------------

Unless the <middlewareHome> configuration paramter is specified, the installation is performed in the ${basedir}/Oracle/Software directory.

sbutton:~/Projects/Java/wls-maven-doc/maven-demo $ ls -l

total 8

drwxr-xr-x 3 sbutton staff 102 23 Nov 15:44 Oracle

-rw-r--r-- 1 sbutton staff 3597 23 Nov 15:43 pom.xml

drwxr-xr-x 3 sbutton staff 102 23 Nov 15:03 src

sbutton:~/Projects/Java/wls-maven-doc/maven-demo $ ls -l Oracle/Software/

total 64

-rw-r--r-- 1 sbutton staff 5808 23 Nov 15:45 README.txt

-rw-r--r-- 1 sbutton staff 3064 23 Nov 15:45 configure.cmd

-rwxr-xr-x 1 sbutton staff 2857 23 Nov 15:45 configure.sh

-rw-r--r-- 1 sbutton staff 3189 23 Nov 15:45 configure.xml

-rw-r--r-- 1 sbutton staff 133 23 Nov 15:45 domain-registry.xml

drwxr-xr-x 508 sbutton staff 17272 23 Nov 15:46 modules

-rw-r--r-- 1 sbutton staff 1138 23 Nov 15:45 registry.template

-rw-r--r-- 1 sbutton staff 1320 23 Nov 15:46 registry.xml

drwxr-xr-x 3 sbutton staff 102 23 Nov 15:45 utils

drwxr-xr-x 7 sbutton staff 238 23 Nov 15:46 wlserver

Create-Domain

This goal creates a standard WLS domain from the specific WLS installation.

The location of the domain is specified using the optional <domainHome> configuration element. By default <domainHome> is set to ${basedir}/Oracle/Domains so it will be created in an Oracle/Domains subdirectory of the root directory of the Maven project.

The WLS installation to be used is specified using the optional <middlewareHome> configuration element. This is set to ${basedir}/Oracle/Software by default, so if the default location has been used to execute the install goal, it can be left out of this goal.

To create a domain, a user and password are required. These can be specified as configuration parameters using the <user> and <password> properties or they can be specified on the command line.

<groupId>com.oracle.weblogic</groupId>

<artifactId>wls-maven-plugin</artifactId>

com.oracle.weblogic:wls-dev:zip:12.1.1.0

</artifactLocation>

<user>weblogic</user>

<password>welcome1</user>

</configuration>

</plugin>

The execution of the wls:install goal is shown below.

sbutton:~/Projects/Java/wls-maven-doc/maven-demo $ mvn wls:create-domain

[INFO] Scanning for projects...

[INFO]

[INFO] ------------------------------------------------------------------------

[INFO] Building maven-demo 1.0-SNAPSHOT

[INFO] ------------------------------------------------------------------------

[INFO]

[INFO] --- wls-maven-plugin:12.1.1.0:create-domain (default-cli) @ maven-demo ---

[INFO] ++====================================================================++

[INFO] ++ wls-maven-plugin: create-domain ++

[INFO] ++====================================================================++

[INFO] Domain creation script:

readTemplate('/Users/sbutton/Projects/Java/wls-maven-doc/maven-demo/Oracle/Software/wlserver/common/templates/domains/wls.jar')

cd('/Security/base_domain/User/weblogic')

set('Name', 'weblogic')

set('Password', '***')

writeDomain('/Users/sbutton/Projects/Java/wls-maven-doc/maven-demo/Oracle/Domains/mydomain')

[INFO] ------------------------------------------------------------------------

[INFO] BUILD SUCCESS

[INFO] ------------------------------------------------------------------------

[INFO] Total time: 39.345s

[INFO] Finished at: Wed Nov 23 16:01:13 CST 2011

[INFO] Final Memory: 24M/81M

[INFO] ------------------------------------------------------------------------

Unless the <domainHome> configuration property is specified, the domain will be created in the ${basedir}/Oracle/Domains directory of the project.

sbutton:~/Projects/Java/wls-maven-doc/maven-demo $ ls -l Oracle/Domains/mydomain

total 16

drwxr-xr-x 3 sbutton staff 102 23 Nov 16:01 autodeploy

drwxr-xr-x 10 sbutton staff 340 23 Nov 16:01 bin

drwxr-xr-x 10 sbutton staff 340 23 Nov 16:01 config

drwxr-xr-x 3 sbutton staff 102 23 Nov 16:01 console-ext

-rw-r--r-- 1 sbutton staff 462 23 Nov 16:01 fileRealm.properties

drwxr-xr-x 7 sbutton staff 238 23 Nov 16:01 init-info

drwxr-xr-x 3 sbutton staff 102 23 Nov 16:01 lib

drwxr-xr-x 6 sbutton staff 204 23 Nov 16:01 security

drwxr-xr-x 3 sbutton staff 102 23 Nov 16:01 servers

-rwxr-x--- 1 sbutton staff 293 23 Nov 16:01 startWebLogic.sh

Start-Server

This goal executes a startWebLogic command on a given domain, starting the WebLogic Server instance for use.

This goal also uses the <middlewareHome> and <domainHome> configuration elements to specify the location of the WLS installation and domain to use.

If you have followed the convention-over-configuration approach and adopted the default values, these configuration elements do not need to be specified.

If you have installed WLS or created a domain in a different location, you must specify the location using the <middlewareHome> and <domainHome> configuration elements in the pom.xml or specify them as parameters on the command line.

Using the convention-over-configuration approach, the default domain ${basedir}/Oracle/Domains/mydomain using the WLS installation in ${basedir}/Oracle/Software can be started as shown below.

sbutton:~/Projects/Java/wls-maven-doc/maven-demo $ mvn wls:start-server

[INFO] Scanning for projects...

[INFO]

[INFO] ------------------------------------------------------------------------

[INFO] Building maven-demo 1.0-SNAPSHOT

[INFO] ------------------------------------------------------------------------

[INFO]

[INFO] --- wls-maven-plugin:12.1.1.0:start-server (default-cli) @ maven-demo ---

[INFO] ++====================================================================++

[INFO] ++ wls-maven-plugin: start-server ++

[INFO] ++====================================================================++

.[INFO] Starting server in domain /Users/sbutton/Projects/Java/wls-maven-doc/maven-demo/Oracle/Domains/mydomain

[INFO] Check stdout file for details: /Users/sbutton/Projects/Java/wls-maven-doc/maven-demo/Oracle/Domains/mydomain/server-2388282492279558044.out

[INFO] Process being executed, waiting for completion.

.........

[INFO] Server started successful

[INFO] ------------------------------------------------------------------------

[INFO] BUILD SUCCESS

[INFO] ------------------------------------------------------------------------

[INFO] Total time: 9.137s

[INFO] Finished at: Wed Nov 23 16:23:07 CST 2011

[INFO] Final Memory: 4M/81M

[INFO] ------------------------------------------------------------------------

Deploy

The deploy goal deploys an application.

The convention-over-configuration approach uses the defaults available for middlewareHome, adminurl, and the source file to deploy allowing the goal to be executed without any additional configuration.

sbutton:~/Projects/Java/wls-maven-doc/maven-demo $ mvn wls:deploy

[INFO] Scanning for projects...

[INFO]

[INFO] ------------------------------------------------------------------------

[INFO] Building maven-demo 1.0

[INFO] ------------------------------------------------------------------------

[INFO]

[INFO] --- wls-maven-plugin:12.1.1.0:deploy (default-cli) @ maven-demo ---

[INFO] ++====================================================================++

[INFO] ++ wls-maven-plugin: deploy ++

[INFO] ++====================================================================++

weblogic.Deployer invoked with options: -noexit -user weblogic -deploy -source /Users/sbutton/Projects/Java/wls-maven-doc/maven-demo/target/maven-demo.war

Task 0 initiated: [Deployer:149026]deploy application maven-demo on AdminServer.

Task 0 completed: [Deployer:149026]deploy application maven-demo on AdminServer.

Target state: deploy completed on Server AdminServer

[INFO] ------------------------------------------------------------------------

[INFO] BUILD SUCCESS

[INFO] ------------------------------------------------------------------------

[INFO] Total time: 5.803s

[INFO] Finished at: Wed Nov 23 16:36:52 CST 2011

[INFO] Final Memory: 6M/81M

[INFO] ------------------------------------------------------------------------

Stop-Server

The stop-server goal stops an executing server using the stopWebLogic script on the specified domain.

sbutton:~/Projects/Java/wls-maven-doc/maven-demo $ mvn wls:stop-server

[INFO] Scanning for projects...

[INFO]

[INFO] ------------------------------------------------------------------------

[INFO] Building maven-demo 1.0

[INFO] ------------------------------------------------------------------------

[INFO]

[INFO] --- wls-maven-plugin:12.1.1.0:stop-server (default-cli) @ maven-demo ---

[INFO] ++====================================================================++

[INFO] ++ wls-maven-plugin: stop-server ++

[INFO] ++====================================================================++

[INFO] Stop server in domain: /Users/sbutton/Projects/Java/wls-maven-doc/maven-demo/Oracle/Domains/mydomain

[INFO] Process being executed, waiting for completion.

[INFO] [exec] Stopping Weblogic Server...

[INFO] [exec]

[INFO] [exec] Initializing WebLogic Scripting Tool (WLST) ...

[INFO] [exec]

[INFO] [exec] Welcome to WebLogic Server Administration Scripting Shell

[INFO] [exec]

[INFO] [exec] Type help() for help on available commands

[INFO] [exec]

[INFO] [exec] Connecting to t3://localhost:7001 with userid weblogic ...

[INFO] [exec] Successfully connected to Admin Server 'AdminServer' that belongs to domain 'mydomain'.

[INFO] [exec]

[INFO] [exec] Warning: An insecure protocol was used to connect to the

[INFO] [exec] server. To ensure on-the-wire security, the SSL port or

[INFO] [exec] Admin port should be used instead.

[INFO] [exec]

[INFO] [exec] Shutting down the server AdminServer with force=false while connected to AdminServer ...

[INFO] [exec] WLST lost connection to the WebLogic Server that you were

[INFO] [exec] connected to, this may happen if the server was shutdown or

[INFO] [exec] partitioned. You will have to re-connect to the server once the

[INFO] [exec] server is available.

[INFO] [exec] Disconnected from weblogic server: AdminServer

[INFO] [exec] Disconnected from weblogic server:

[INFO] [exec]

[INFO] [exec] Exiting WebLogic Scripting Tool.

[INFO] [exec]

[INFO] [exec] Done

[INFO] [exec] Stopping Derby Server...

[INFO] ------------------------------------------------------------------------

[INFO] BUILD SUCCESS

[INFO] ------------------------------------------------------------------------

[INFO] Total time: 8.921s

[INFO] Finished at: Wed Nov 23 16:41:14 CST 2011

[INFO] Final Memory: 4M/81M

[INFO] ------------------------------------------------------------------------

APPC

The appc goal executes the WebLogic Server application compiler tool to prepare the application for deployment.

This benefits from the convention-over-configuration model, allowing it to be executed using the defaults of the project.

An example of the goal being executed is shown below. Note this example uses the –verbose flag to highlight the activities the appc utility is performing. This is not normally necessary.

sbutton:~/Projects/Java/wls-maven-doc/maven-demo $ mvn wls:appc -Dverbose

[INFO] Scanning for projects...

[INFO]

[INFO] ------------------------------------------------------------------------

[INFO] Building maven-demo 1.0

[INFO] ------------------------------------------------------------------------

[INFO]

[INFO] --- wls-maven-plugin:12.1.1.0:appc (default-cli) @ maven-demo ---

[INFO] ++====================================================================++

[INFO] ++ wls-maven-plugin: appc ++

[INFO] ++====================================================================++

[JspcInvoker]Checking web app for compliance.

[jspc] -webapp specified, searching . for JSPs

[jspc] Compiling /index.jsp

[INFO] ------------------------------------------------------------------------

[INFO] BUILD SUCCESS

[INFO] ------------------------------------------------------------------------

[INFO] Total time: 5.281s

[INFO] Finished at: Wed Nov 23 16:43:12 CST 2011

[INFO] Final Memory: 16M/81M

[INFO] ------------------------------------------------------------------------

WLST

The WLST goal enables the WebLogic Scripting Tool (WLST) to be used to execute scripts that configure resources or perform other operational actions on a WebLogic Server domain. The WLST used by the wlst Maven goal is the standard environment WebLogic Server WLST environment so all existing scripts should be able to be used.

Benefitting again from the convention-over-configuration, the middlewareHome and domainHome locations do not need to be specified if the defaults are used.

The WLST goal can execute an external script specified using the <fileName> configuration element or a sequence of WLST calls can be specified within the pom.xml using the <script> configuration element.

<groupId>com.oracle.weblogic</groupId>

<artifactId>wls-maven-plugin</artifactId>

com.oracle.weblogic:wls-dev:zip:12.1.1.0

</artifactLocation>

<user>weblogic</user>

<password>welcome1</user>

<filename>create-datasource.py</fileName>

</configuration>

</plugin>

An execution of the wlst goal is shown below.

sbutton:~/Projects/Java/wls-maven-doc/maven-demo $ mvn wls:wlst -DfileName=create-datasource.py

[INFO] Scanning for projects...

[INFO]

[INFO] ------------------------------------------------------------------------

[INFO] Building maven-demo 1.0

[INFO] ------------------------------------------------------------------------

[INFO]

[INFO] --- wls-maven-plugin:12.1.1.0:wlst (default-cli) @ maven-demo ---

[INFO] ++====================================================================++

[INFO] ++ wls-maven-plugin: wlst ++

[INFO] ++====================================================================++

*** Creating DataSource ***

Connecting to t3://localhost:7001 with userid weblogic ...

Successfully connected to Admin Server 'AdminServer' that belongs to domain 'mydomain'.

Warning: An insecure protocol was used to connect to the

server. To ensure on-the-wire security, the SSL port or

Admin port should be used instead.

Location changed to edit tree. This is a writable tree with

DomainMBean as the root. To make changes you will need to start

an edit session via startEdit().

For more help, use help(edit)

Starting an edit session ...

Started edit session, please be sure to save and activate your

changes once you are done.

Activating all your changes, this may take a while ...

The edit lock associated with this edit session is released

once the activation is completed.

Activation completed

Location changed to serverRuntime tree. This is a read-only tree with ServerRuntimeMBean as the root.

For more help, use help(serverRuntime)

**** DataSource Details ****

Name: cp

Driver Name: Oracle JDBC driver

DataSource: oracle.jdbc.xa.client.OracleXADataSource

Properties: {user=demo}

State: Running

[INFO] ------------------------------------------------------------------------

[INFO] BUILD SUCCESS

[INFO] ------------------------------------------------------------------------

[INFO] Total time: 10.686s

[INFO] Finished at: Wed Nov 23 16:55:25 CST 2011

[INFO] Final Memory: 13M/81M

[INFO] ------------------------------------------------------------------------

11 August 2011

weblogic.xml and prefer-application-packages

Short and sweet this one, purely for my own future simple reference.

To use prefer-application-packages in weblogic.xml, it looks like this:

<weblogic-web-app xmlns="http://xmlns.oracle.com/weblogic/weblogic-web-app" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd http://xmlns.oracle.com/weblogic/weblogic-web-app http://xmlns.oracle.com/weblogic/weblogic-web-app/1.2/weblogic-web-app.xsd">

  <jsp-descriptor>
    <keepgenerated>true</keepgenerated>
    <debug>true</debug>
  </jsp-descriptor>

  <context-root>/quicktest</context-root>
  
  <container-descriptor>
    <prefer-application-packages>
        <package-name>org.codehaus.jackson.*</package-name>
        <package-name>org.codehaus.jettison.*</package-name>
        <package-name>org.objectweb.asm.*</package-name>
    </prefer-application-packages>
  </container-descriptor>

</weblogic-web-app>

13 July 2011

Unofficial Java SE 7 Builds for Mac OS X

Not sure how I overlooked this, but according to this page here:

http://wikis.sun.com/display/OpenJDK/Mac+OS+X+Port

There are prebuilt (unofficial) binaries for Java SE 7 on Mac OS X here:

http://code.google.com/p/openjdk-osx-build/downloads/list?q=label:Featured

Good stuff.

04 July 2011

Plugging in a later version of EclipseLink to WebLogic Server

Talking with Doug Clarke of EclipseLink fame and fortune last week, it sounds like there is some real interest from developers in wanting to update WebLogic Server to use later versions of the EclipseLink in order to access it's evolving feature set.

Which should offer no surprises really, EclipseLink rocks.

Investigation

Turning to the situation at hand, the main points to be addressed are:

1. The later versions of EclipseLink are JPA 2.0 based, so we'll assume that the predominant use case is centered around using JPA 2.0.

WebLogic Server supports JPA 2.0 through the application of a Smart Update patch or via manual adjustments to the PRE_CLASSPATH to incorporate two additional JAR files that enable the use of JPA 2.0.

We'll consider this one easy to handle using documented features.

2. WebLogic Server provides a version of EclipseLink that is loaded as one it's standard feature bearing modules and thus is present by default in the classpath of WebLogic Server for deployed applications. For WLS 10.3.5, this version is org.eclipse.persistence_1.1.0.0_2-1.jar.

WebLogic Server has a feature called the Filtering Classloader, which enables applications to selectively override the libraries from WebLogic Server that an application sees. This should allow an application to be configured to not use the default version of EclipseLink that WebLogic Server provides. This requires each application to specifically provide a weblogic-application.xml file that lists the <prefer-application-packages> configuration set to explicitly filter our the org.eclipselink.persistence package.

3. Any change to the EclipseLink version should be isolated to just an application, and not applied to an entire WebLogic Server installation or domain.

To make the later version of EclipseLink available, there are a few simple options available that could be explored: a) the EclipseLink jar file could be added to the CLASSPATH of WebLogic Server; b) the EclipseLink jar file could be dropped into the $domain/lib directory; c) the newer version of EclipseLink could be used to replace the existing EclipseLink jar file shipped with WebLogic Server, retaining the same name; d) the WebLogic Server shared-library mechanism could be used to deploy the EclipseLink libraries which applications can then selectively reference.

For the sake of expediency, I won't bother going through the pros/cons with each of those options and will just pick a winner from my perspective: the use of a shared-library to provide a selectively consumable version of EclipseLink.

Let's just examine this for a moment -- a WebLogic Server shared-library is an artifact that can be deployed to a WebLogic Server target, which can then be referenced by an application being deployed, whereupon WebLogic Server will merge the contents of the shared-library with the application. This enables common libraries to be deployed and used by multiple applications. Furthermore, shared-libraries can take the format of a standard Java EE archives, where descriptors can be provided which are then also merged with the final application deployment.

Given those capabilities:

a) it's possible to construct and deploy an EAR file based shared-library that contains a later version of EclipseLink and a weblogic-application.xml file which provides a preset prefer-application-packages setting that filters the org.eclipselink.persistence.* package.

b) to use a later version of EclipseLink, an application simply needs to include it's own weblogic-application.xml that imports the EclipseLink shared-library it need to use.

Thus, we have a supported deployment format (can be targeted at single nodes, clusters, whatever ...) to provide later versions of EclipseLink, which can be shared and selectively used by applications as desired.

Implementation

To test this out in an end-to-end manner, I performed the following steps:

1. Downloaded eclipselink-2.2.0.v20110202-r8913.zip from the EclipseLink web site.

2. Created a small ant project to produce an eclipselink-shared-lib.ear file. The layout of the shared-library is just a standard Java EE EAR file and contains the following items:

META-INF/weblogic-application.xml
META-INF/application.xml
lib/eclipselink.jar

The weblogic-application.xml file contains the following configuration elements:

<weblogic-application>
<prefer-application-packages>
    <package-name>org.eclipse.persistence.*</package-name>
</prefer-application-packages>
</weblogic-application>

The application.xml was a necessary element to support the runtime library merging. As you can see from the below, it's basically a NOOP configuration file.

<application>
<display-name>eclipselink-shared-lin</display-name>
<module>
        <java></java>
</module>
</application>

The ant build script produces an EAR file from these elements with one important addition that marks the EAR file as a shared-library for WebLogic Server by adding a number of attributes to the META-INF/MANIFEST.MF file:

<target name="package" depends="prepare">
    <jar destfile="dist/${ant.project.name}.ear">
        <metainf dir="etc" includes="*.xml"/>
        <manifest>
            <attribute name="Extension-Name" value="eclipselink"/>
            <attribute name="Specification-Version" value="2.0"/>
            <attribute name="Implementation-Version" value="2.2.0"/>
        </manifest>
        <fileset dir="build" includes="**/*"/>
    </jar>
</target>

At deployment time, WebLogic Server will use the attributes as meta-data for the deployed shared-library.

The final EAR file looks like this:

sbutton:~/Projects/Java/eclipselink-shared-lib/dist $ jar tf eclipselink-shared-lib.ear
META-INF/
META-INF/MANIFEST.MF
META-INF/application.xml
META-INF/weblogic-application.xml
lib/
lib/eclipselink.jar

For reference, the simple ant project to build the eclipselink-shared-lib.ear file is here: eclipselink-shared-lib.zip.

3. Deployed eclipselink-shared-lib.ear to WebLogic Server. This results in a new library being available on the server, eclipselink#2.0@2.2.0.

4. Created a test application that imports eclipselink#2.0@2.2.0 and outputs the version of it that it is seeing.

The application uses a weblogic.xml to reference the eclipselink#2.0@2.2.0 shared-library that was deployed, which picks up both the new version of eclipselink.jar as well as the filtering-classloader description the library contains:

weblogic-application.xml:

<weblogic-application>
    <library-ref>
        <library-name>eclipselink</library-name>
        <specification-version>2.0</specification-version>
        <implementation-version>2.2.0</implementation-version>
    </library-ref>
</weblogic-application>

Within the application, used a simple servlet that outputs the version of EclipseLink it is seeing:

out.printf("<p>EclipseLink Version: %s</p>", org.eclipse.persistence.Version.getVersionString());

5. Packaged the application into an EAR file and deployed it to WebLogic Server as an application.

When the application is accessed it reports the new version of EclipseLink supplied via the shared-library:

EclipseLink Version: 2.2.0.v20110202-r8913

6. Performed a negative test by undeploying the application, removed the weblogic-application.xml file from it and redeployed it.

When the application is accessed it reports the default version of EclipseLink that WebLogic Server supplies:

EclipseLink Version: 2.1.3.v20110304-r9073

7. With the basic premise validated, add a JPA module to validate the code-weaving EclipseLink performs works as expected. To verify the version EclipseLink is using the EclipseLink log level was set to fine and the console output reviewed, which showed up as Eclipse Persistence Services - 2.2.0.v20110202-r8913

Summary

The use of WebLogic Server shared-libraries appears to be a very suitable model for providing later versions of EclipseLink that automatically filter out the WebLogic Server supplied versions, which applications can selectively choose to import when they need the later versions.

This was just a simple test of the concept of using WebLogic Server shared-libraries to do this. The EclipseLink/TopLink team are in the throes of formally certifying this approach, so keep an eye out for it on the EclipseLink site if it does pass full muster!

17 June 2011

Building and Running OpenJDK 7 on Mac OS X - A Breeze

Preparing a little for the Adelaide JUG meeting yesterday, where Java SE 7 was going to be the topic of discussion, I finally thought it was time to grab the OpenJDK 7 source, get it built and working on my Mac.

http://wikis.sun.com/display/OpenJDK/Mac+OS+X+Port

After checking off the pre-reqs, the process was as simple as following the small set of very clear instructions on the Wiki page.

The only small side excursion I had was that my bash environment had a JAVA_HOME env var set, which aborted the build at one point. Unsetting that and restarting the build, it then ran flawlessly for about 30mins before out popped a shiny new Open JDK 7 build.

Having never manually installed a JDK on my Mac (Apple updates have served me well) the instructions for how and where to install it was very helpful. And so simple! Particularly with how it results in the new JDK being visible to the /usr/libexec/java_home utility:



sbutton:~ $ /usr/libexec/java_home  -V 

Matching Java Virtual Machines (4):

1.6.0_24-b07-334, x86_64: "Java SE 6" /System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home

1.6.0_24-b07-334, i386: "Java SE 6" /System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home

1.7.0, x86_64: "OpenJDK 7" /Users/sbutton/Library/Java/JavaVirtualMachines/1.7.0.jdk/Contents/Home

1.7.0, i386: "OpenJDK 7" /Users/sbutton/Library/Java/JavaVirtualMachines/1.7.0.jdk/Contents/Home

Voila!

sbutton:~ $ export JAVA_HOME=`/usr/libexec/java_home  -v 1.7`

sbutton:~ $ java -version

openjdk version "1.7.0-internal"

OpenJDK Runtime Environment (build 1.7.0-internal-sbutton_2011_06_16_11_39-b00)

OpenJDK 64-Bit Server VM (build 21.0-b15, mixed mode)

Now looking forward to trying out some of the new language features with NetBeans 7.0.

All in all, a total breeze! Kudos to the OpenJDK Mac porters group.

14 June 2011

WebLogic Server: Listing Groups of an Authenticated User

Another question from a colleague today: "for a given authenticated user, how can I see what groups the user belongs to?"

Yep, good question Pas. Not sure, but worth some time to find out.

Hunting through the WebLogic Security Documentation, I found a good description and diagram of how a Subject is related to a Principal.

A principal is an identity assigned to a user or group as a result of authentication. Both users and groups can be used as principals by application servers such as WebLogic Server. The Java Authentication and Authorization Service (JAAS) requires that subjects be used as containers for authentication information, including principals.

As part of a successful authentication, principals are signed and stored in a subject for future use.

Any principal that is going to represent a WebLogic Server user or group needs to implement the WLSUser and WLSGroup interfaces, which are available in the weblogic.security.spi package.

Thus presumably, if you can get hold of the Subject, then you should be able to see the Principals associated with the User, of which some should reflect the Group(s) the User belongs to.

But how do you get the Subject?

I kept reading through documentation, but I couldn't see any really obvious description of where/how the Subject could be obtained.

Then, after almost giving up and resorting to looking through the Javadoc, I found this small reference:

http://download.oracle.com/docs/cd/E17904_01/web.1111/e13711/thin_client.htm#i1030501

In Example 3-3, notice that the JSP is calling an API (request.getRemoteUser()) to get the name of the user that logged in.

A different API, weblogic.security.Security.getCurrentSubject(), could be used instead. To use this API to get the name of the user, use it with the SubjectUtils API as follows:
String username = weblogic.security.SubjectUtils.getUsername(
weblogic.security.Security.getCurrentSubject());

Note: In the actual doc, there's a missing opening parenthesis in the supplied code snippet. I've added it in orange in the above.

Looking at the Javadoc, the weblogic.security.Security class has a static method that returns a javax.security.auth.Security object.

I also found a post from Edward Biemond here: http://blog.whitehorses.nl/2010/01/29/weblogic-web-application-container-security-part-1/ that discusses this area, from a slightly different more practical perspective perhaps.

With the Subject accessible and the description of the WLUser and WLGroup interfaces above, the group(s) an authenticated user belongs to can be readily discovered.

    import weblogic.security.Security;
    import weblogic.security.spi.WLSUser;
    import weblogic.security.spi.WLSGroup;
    ...
    private void doSubjectStuff(PrintWriter out,
      HttpServletRequest request,
      HttpServletResponse response) {



        Subject subject = Security.getCurrentSubject();

        

        StringBuffer groups = new StringBuffer();

        String user = null;

        boolean first = true;



        for(Principal p: subject.getPrincipals()) {

            if(p instanceof WLSGroup) {

                if(first) {

                    first=false;

                } else {

                    groups.append(", ");

                }

                groups.append(p.getName());

            } else if (p instanceof WLSUser) {

                user = p.getName();

            }

        }

        

        out.printf("<p>RemoteUser: %s, User: %s, belongs to: %s</p>", 

                request.getUserPrincipal().getName(),

                user, 

                groups);

    }

Calling this from a servlet, deployed within a simple web application that uses BASIC authentication mapped to a couple of WebLogic Server groups, the following output is displayed when the user "steve" logs in:

RemoteUser: steve, User: steve, belongs to: AppTesters, Deployers

Note, as Edmond also points out, the groups that are provided in the Subject are the WebLogic Server groups the user belongs to, and not the logical role-name defined in the web.xml file.

web.xml:
<security-role> <role-name>ADMINS</role-name> </security-role>

weblogic.xml:
<security-role-assignment> <role-name>ADMINS</role-name> <principal-name>AppTesters</principal-name> <principal-name>Administrators</principal-name> </security-role-assignment>

The primary new takeaway point I got from this was the use of the weblogic.security.Security class to obtain an instance of the current Subject.

07 June 2011

Using SLF4J with WebLogic Server Logging

Just recently, I needed to take a look at the SLF4J (Simple Logging Facade 4 Java) API, and more specifically, to how it could be employed on WebLogic Server.

Simple Logging Facade for Java

http://www.slf4j.org/

SLF4J follows the Commons-Logging model in that it provides a "Simple Logging Facade" with an API that can be used to insert log messages into application code, without specifying the specific Logging framework that is to be used. The actual work of capturing and emitting the log message is handled by "pluggable" SLF4J binding, which are added at deployment/runtime time (or server start) and handle the actual logging implementation work. There are pre-built bindings for the common logging frameworks such as JDK logging, Log4J, LogBack, as well as a simple Logging implementation that appears to simply print log messages to stdout.

Basic Problem

Having a look at a project that was using SLF4J with WebLogic Server, the question that came up was how could we direct the SLF4J logs into the standard WebLogic Server log facilities.

In it's basic form, with the slf4j-simple-1.6.0.jar binding being used, the SLF4J logs were not consistent with the rest of the WebLogic Server logs.

<Jun 7, 2011 3:22:04 PM CST> <Notice> <WebLogicServer> <BEA-000395> <Following extensions directory contents added to the end of the classpath:

/Users/sbutton/Projects/Domains/wls1035/lib/slf4j-api-1.6.0.jar:/Users/sbutton/Projects/Domains/wls1035/lib/slf4j-simple-1.6.0.jar> 

<Jun 7, 2011 3:22:05 PM CST> <Info> <WebLogicServer> <BEA-000377> <Starting WebLogic Server with Java HotSpot(TM) 64-Bit Server VM Version 19.1-b02-334 from Apple Inc.> 

<Jun 7, 2011 3:22:05 PM CST> <Info> <Management> <BEA-141107> <Version: WebLogic Server 10.3.5.0  Fri Apr 1 20:20:06 PDT 2011 1398638 > 

. . .

. . .

<Jun 7, 2011 3:22:13 PM CST> <Notice> <WebLogicServer> <BEA-000331> <Started WebLogic Admin Server "myserver" for domain "mydomain" running in Development Mode> 

<Jun 7, 2011 3:22:13 PM CST> <Notice> <WebLogicServer> <BEA-000365> <Server state changed to RUNNING> 

<Jun 7, 2011 3:22:13 PM CST> <Notice> <WebLogicServer> <BEA-000360> <Server started in RUNNING mode> 

14 [[ACTIVE] ExecuteThread: '0' for queue: 'weblogic.kernel.Default (self-tuning)'] INFO com.oracle.demo.wlsslf4j.TestServlet - *** This is an info: class com.oracle.demo.wlsslf4j.TestServlet

14 [[ACTIVE] ExecuteThread: '0' for queue: 'weblogic.kernel.Default (self-tuning)'] WARN com.oracle.demo.wlsslf4j.TestServlet - *** This is a warning: class com.oracle.demo.wlsslf4j.TestServlet

14 [[ACTIVE] ExecuteThread: '0' for queue: 'weblogic.kernel.Default (self-tuning)'] ERROR com.oracle.demo.wlsslf4j.TestServlet - *** This is an error: class com.oracle.demo.wlsslf4j.TestServlet

The question was: without writing a specific WLS binding, is there a way to enable the SLF4J logs to be directed into the WebLogic Server logs so they are consistently formatted and able to be viewed in the WebLogic Server console with the rest of the logs?

One Solution

The solution was quite straightforward in the end, simply by combining two pieces of existing functionality:

1. The SLF4J distribution ships with a binding for JDK logging called slf4j-jdk14-1.6.0.jar. This results in the SLf4J logs being directed into the JDK logging framework.

2. WebLogic Server ships with a JDK logging handler which will pick up log messages emitted from JDK logging framework and direct them into the WebLogic Server logging system.

The weblogic.logging.ServerLoggingHandler is documented here: http://download.oracle.com/docs/cd/E14571_01/web.1111/e13739/logging_services.htm#CHDBBEIJ

To get it all working, all it required was making the relevant libraries available to WebLogic Server and wiring them together using a logging.properties file.

Copy Libraries into WebLogic Server

SLF4J basically comes as two components. There's the API which is used by applications, and then there's the bridgings that handle the actual production of log messages into the desired form.

To make SLF4J available to WebLogic Server, I employed the simplest way I know - copy them into the domain/lib directory. This has a certain set of limitations in terms of updating versions without a server restart, etc. but it's a really simple way to get things working in the first instance.

sbutton:~/Projects/Domains/wls1035 $ ls -l lib/

total 88

-rw-r--r--  1 sbutton  staff    702  6 Jun 13:15 readme.txt

-rw-r--r--  1 sbutton  staff  25496  7 Jun 15:19 slf4j-api-1.6.0.jar

-rw-r--r--  1 sbutton  staff   8887  7 Jun 15:34 slf4j-jdk14-1.6.0.jar

Create a logging.properties file

The logging.properties file is a standard way to control JDK logging. Since we have directed SLf4J logs into JDK logging framework by making the slf4j-jdk14-1.6.0 binding available, we can configure JDK logging to use the ServerLoggingHandler provided by WebLogic Server, so as to direct its logs into the WebLogic Server logging system.

The JDK logging framework and its configuration options are all well documented, starting from Nov 2001 here: http://download.oracle.com/javase/1.4.2/docs/guide/util/logging/overview.html

Here is the logging.properties file that was used:

####

# Specify the handlers to create in the root logger

handlers = weblogic.logging.ServerLoggingHandler



# Register handlers for the com.oracle.demo package and its child loggers

com.oracle.demo.handlers = weblogic.logging.ServerLoggingHandler



# Do not send the org.hibernate.validator log messages to the root handler

com.oracle.demo.useParentHandlers = false



# Set the default logging level for the root logger

.level = ALL

com.oracle.demo.level = ALL



# Set the default logging level for new ServerLoggingHandler instances

weblogic.logging.ServerLoggingHandler.level = ALL

To direct the JDK logging framework to use the logging.properties file, the standard System property java.util.logging.config.file is used. With WebLogic Server, this can be easily accomplished by setting the JAVA_OPTIONS System property with the corresponding value.



$ export JAVA_OPTIONS="-Djava.util.logging.config.file=/Users/sbutton/Projects/Domains/wls1035/logging.properties"

Start WebLogic Server and Observe

With the libraries copied into the domain/lib directory, the logging.properties file created and specified as $JAVA_OPTIONS, starting WebLogic Server should now allow the logs created via SLF4J to be directed into the WebLogic Server logging framework. This should let them be seen on stdout in a consistent form with the standard WebLogic Server log messages, as well as via the WebLogic Server console through it's log viewer.

SL4J logs in stdout

<Jun 7, 2011 3:52:01 PM CST> <Notice> <WebLogicServer> <BEA-000365> <Server state changed to RUNNING> 

<Jun 7, 2011 3:52:01 PM CST> <Notice> <WebLogicServer> <BEA-000360> <Server started in RUNNING mode> 

<Jun 7, 2011 3:52:07 PM CST> <Warning> 

<com.oracle.demo.wlsslf4j.TestServlet> <BEA-000000> <*** This is a warning: class com.oracle.demo.wlsslf4j.TestServlet> 

<Jun 7, 2011 3:52:07 PM CST> <Error> <com.oracle.demo.wlsslf4j.TestServlet> <BEA-000000> <*** This is an error: class com.oracle.demo.wlsslf4j.TestServlet>

12 December 2011

Convention Over Configuration

Installing the Plugin

Basic Configuration of Plugin

Install

Create-Domain

Deploy

Stop-Server

APPC

WLST

11 August 2011

13 July 2011

04 July 2011

17 June 2011

14 June 2011

07 June 2011

Simple Logging Facade for Java

Basic Problem

One Solution

Copy Libraries into WebLogic Server

Create a logging.properties file

Start WebLogic Server and Observe

SL4J logs in stdout

SL4J logs in WebLogic Server console