Best Practices for Configuration Management in a SOA Environment

by Brian Jimerson

download-icon13-1Oracle SOA Suite
download-icon13-1Oracle WebLogic Server
download-icon13-1Oracle Enterprise Manager


Configuration management (CM), by definition, is the practice of managing IT resources, assets, and controls through consistent versions, naming, change control, and automation. CM for software solutions encompasses many disciplines, including version control, automated deployments, environmental configurations, and team development. These disciplines are well known and there are many standard tools to address traditional solution CM.

However, SOA solution practices impose unique needs for CM. Paradigms such as service versioning, distributed deployments, dynamic end-point resolution, and the infrastructure used to support SOA practices all have unique requirements. The good news is that many of the traditional CM tools and techniques can be adopted into a SOA practice.

This article discusses best practices for CM in an Oracle SOA Suite 11g practice. It discusses the tools, techniques, and processes that should be used to ensure the proper management of software, services, and infrastructure configuration for these practices.

 Note: It assumed that the reader is familiar with traditional Java Platform, Enterprise Edition (Java EE) CM principles. Many of the discussions and examples in this article build on these principles. 

Build Processes for SOA Artifacts

One of the most fundamental needs for any application is a repeatable process for building the source code into an executable package. For Java EE applications, these distributable units are usually in the form of:

  • JAR files for standalone applications, Enterprise JavaBeans (EJB), and libraries
  • WAR files for Web applications
  • EAR files for enterprise applications
  • RAR files for resource adapters

Building these artifacts usually encompasses the same basic steps:

  1. Delete any old build artifacts.
  2. Build any needed dependencies.
  3. Compile the source code into classes.
  4. Apply environment-specific settings in resources.
  5. Copy resources into a specific directory.
  6. Assemble the compiled code, libraries, and files into a target layout.
  7. Create the deployment archive (JAR, WAR, and so on).

Because of these standard steps, there are a couple of de-facto tools to build Java EE artifacts. Apache Ant is a well-known tool for configuring, building, and deploying Java projects. It is modeled after *nix make, and it is extremely configurable for just about any type of build need. It also offers a plug-in system so additional tasks (such as secure copying over SSH and deploying to particular application servers, such as Oracle WebLogic Server) can be accomplished through an Ant build.

Ant uses an XML file to describe the build process. Groups of tasks needed to accomplish a particular task are called targets. Each target can have 0 or more tasks, which are executable steps in a build process. A set of targets in an XML build file is called a project. A simple Ant build file that can compile a Java application and create a distributable JAR file is shown in Listing 1.

Listing 1 -- Sample Ant Build File

<project name="Sample Build" default="dist" basedir=".">
  <description>A sample Ant build file.</description>

  <!-- Clean target deletes old build files -->
  <target name="clean" description="Cleans old build artifacts" >
    <delete dir="build"/>
    <delete dir="dist"/>

  <!-- Compile target compiles all Java source code; depends on the clean target -->
  <target name="compile" depends="clean" description="Compiles source code" >
    <javac srcdir="src" destdir="build"/>

  <!-- Dist target creates JAR file of compiled code; depends on the compile target, 
  which in turn depends on the clean target -->
  <target name="dist" depends="compile" description="Creates a distributable JAR file" >
    <mkdir dir="dist/lib"/>
    <jar jarfile="dist/lib/SampleProject.jar" basedir="build"/>

Ant has been a standard build tool for many years. Build processes are very configurable, and through the use of plug-ins, they can accomplish almost any task. However, Ant does not address some of the needs of standard build processes, such as dependency management, naming conventions, reporting, and generating standard build processes.

Apache Maven addresses some of the shortcomings of Ant, especially dependency management, standard source code layout, and build processes. Maven relies heavily on conventions for source code layout, build configurations, and naming to greatly simplify build processes. For example, to accomplish a build similar to the Ant build in Listing 1, you simply need to execute the following command:

mvn clean package

As long as the project has a standard layout, this command will clean and compile a Java project, and create a JAR archive of the project for distribution. Maven also greatly simplifies dependency management of projects by using dependency repositories. A project's dependencies and versions are described in an XML descriptor file called a project object model (POM) file; Maven automatically downloads and packages these dependencies during build time. With Ant, dependencies need to be manually collected and packaged for a project.

Because of the improvements that Maven has over Ant, many organizations utilize Maven for all of their builds and deployments. However, different project types require Maven plug-ins in order to execute properly. For example, a Java Web application requires a WAR plug-in in order to properly build the WAR distributable file. This plug-in is freely available through the standard Maven repositories.

Some project assembly types, such as an Oracle SOA Suite composite application, do not have stable Maven plug-ins available. Oracle SOA Suite composite applications have extensive Ant support available to build and deploy Service Component Architecture (SCA) archives; in fact, deploying an SCA composite in Oracle JDeveloper utilizes these Ant scripts to execute the build and deploy process.

For SOA practices that currently utilize, or wish to use, Maven to build standard applications such as Web applications (WAR), Java libraries (JAR), and enterprise applications (EAR), there a couple of options when incorporating SCA composites into their build infrastructure:

  • Mix Ant builds for SCA composites with Maven builds for other applications. This options works well if SCA composites are built and deployed independently of other applications, and a build server that supports both platforms is utilized.
  • Use the Maven AntRun plug-in to call SCA Ant tasks from Maven. This is a good option for companies who wish to use Maven for all their builds and deployments. Although the Ant SCA tasks still need to be configured with the composite application, the Maven plug-in takes care of delegating build and deployment calls to the underlying Ant tasks.

Note that Oracle JDeveloper IDE has some support for Maven projects in the form of a Developer's Preview update. Organizations that currently use Maven and are considering switching to Oracle JDeveloper for standard Java EE development as well, should evaluate whether the state of the Oracle JDeveloper Maven update is sufficient and stable enough for their needs. Many practices use a hybrid of development tools in a SOA environment, such as Eclipse or NetBeans with Maven support for standard Java EE applications, and Oracle JDeveloper, which fully supports Ant builds, for composites, BPM, and other Oracle SOA Suite projects.

Deployment Processes for SOA Artifacts

There are several tools that can be used deploy SOA artifacts to an Oracle WebLogic Server. The most significant of these are Oracle Enterprise Manager, WebLogic Scripting Tool (WLST), Apache Ant, and Apache Maven with the WebLogic plug-in.

Oracle Enterprise Manager is a good choice for occasional manual deployments. Oracle Enterprise Manager provides a graphical interface for deployment, and provides most of the options necessary for configuring the deployment. However, using Oracle Enterprise Manager for deployment is a manual process, which can lead to errors in deployment. Using Oracle Enterprise Manager to document steps and configuration for a new artifact can be a useful process, though.

WLST provides an automated interface for deploying SOA artifacts. WLST is a command-line scripting tool for managing WebLogic servers, including deployment of applications. WLST uses the Jython language for scripting; deployments can be saved in a Jython script file and passed to WLST when invoked. Jython is a Python bridge to Java, and uses the Python language syntax; more information on the Python syntax can be found here. An example of a WLST command for deploying a SOA composite application is shown in Listing 2. More information about using WLST to compile, deploy, and manage composite applications can be found here.

Listing 2 -- Using WLST to Deploy a Composite Application

wls:/soa_domain/ServerConfig> sca_deployComposite("http://localhost:7001", 

Ant and Maven are also good choices for automated deployments of SOA artifacts. Maven with the WebLogic plug-in can be used for deploying non-SCA SOA artifacts, such as standalone Web Service projects. Ant with the SCA custom tasks can be used to deploy composite applications; as discussed previously, Maven support for composite applications is minimal.

Using Maven for deploying WebLogic applications requires the WebLogic Maven plug-in. The plug-in needs to be configured as well; you'll find an example pom.xml with WebLogic configuration here.  Note the usage of different profiles for development, test, and production environments. Using profiles such as this provides the ability to set up different configurations for different environments, and then specify the profile as part of the mvn command.

Using Ant to deploy SCA composite applications requires referencing the SCA build scripts packaged with the Oracle JDeveloper SOA Composite Editor plug-in; these scripts are located in the JDeveloper/bin directory by default. The following build scripts are needed:

  • ant-sca-deploy.xml
  • ant-sca-mgmt.xml
  • ant-sca-package.xml
  • ant-sca-test.xml
  • ant-sca-upgrade.xml
  • ant-soa-common.xml
  • ant-soa-util.xml

Once these scripts are packaged with a composite application, a wrapper script can be used to compile, package, and deploy the composite. An example of this wrapper script is available here; it can be used to customize SCA composite deploys.

To use this script, you need to update the properties in the file, put the and sca-build.xml files in the same directory as the Oracle JDeveloper build scripts, and execute the appropriate target for the environment, such as dev-deploy. You also need a composite configuration plan for each environment, even if there is no environment-specific configuration for the composite.

Source and Version Control

Source and version control deals with the process of managing source files in a team environment and providing versions and management of the files. Examples of version control software are Subversion, CVS, Microsoft Team Foundation Server, Mercurial, and so on.

Traditional source control is very applicable to source control for SOA practices. There are a couple of unique requirements for SOA practices that traditional software development centers are not typically concerned with. For the purpose of this discussion, Subversion terminology will be used, since Subversion is fully supported in Oracle JDeveloper and related Oracle SOA Suite tools. All other major version control system technologies support the same concepts with different terminology.

One of the first things that SOA practices need to deal with in their version control software is aligning SOA composite application versions with revisions in their version control software. SOA composite applications are always versioned when they are deployed to a WebLogic server. A composite's run-time version should be able to be tied back to a revision in the source control system. Being able to tie a run-time composite's version to a revision in the source control system allows a team to provide change documents for a version, reproduce or roll back to a version, and communicate features and release notes.

A similar imposition of a SOA environment is the ability to version discrete services. One of the tenets of SOA is the contract between a service and client; most services inevitably need to change their contract throughout their lifecycle, but in doing so they need to maintain previous versions of the contract for existing consumers. This creates the need for synthetic versioning of discrete services that consumers can bind to.

Most source control systems employ their own revision naming system. Subversion uses an incremental numeric system; each Subversion transaction creates an increment in the revision number. Aligning a source control system's revision with a composite or discrete service's version throughout the deployment lifecycle can be difficult, and it is not always necessary. Typically, a production release of a service needs to be tied back to a source control revision, but development versions of a service can be volatile and do not need specific alignment with source control revisions.

To bridge the gap between versions of services and revisions in source control systems, tags or labels can be used. Production versions of services are of interest, and they are usually deployed after functional and regression testing in the test environment; creating a tag when a deployment is made to the test environment is a relatively low-impact solution. Tags can be arbitrary in name, so the naming of a tag can reflect a service's version, independent of the source control system's versioning system. Figure 1 describes the process of tagging version control with service versions.

Figure 1 -- Version Control Tagging

Automated Building and Deployment

Automated building and deployment of SOA artifacts can drastically reduce the effort of deploying artifacts, deployment errors, and the need for developers to deploy artifacts from their IDEs or command line. Typically, a build server is used to automate builds and deployments. A build server provides the ability to configure multiple projects or builds; invoke build tools such as Maven, Ant, or shell scripts; and provide auditing features such as failure reports and notifications.

An excellent open-source build server is Hudson, hosted by Oracle. Hudson is classified as a continuous integration server, but it can be used for most types of automated building and deploying. It can execute Maven goals, Ant targets, Java compiler tasks, .NET builds, and shell commands. It can also work with most version control systems, including CVS, Subversion, and Perforce. Hudson also provides support for projects, version control tagging, and distributing builds across multiple machines.

Other build servers that are similar in function to Hudson include:

Environmental Configuration of SOA Artifacts

SOA artifacts, like traditional applications, need the ability to configure themselves for different environments as they are promoted through development, test, and production. Applications need to be able to vary connection and login information to external entities such as databases, e-mail servers, and third parties. SOA artifacts also need to resolve service end-points dynamically.

Depending on the build platform, there are a number of ways to vary configuration information by environment:

  • Maven filters and profiles: Maven filters provide the ability to merge properties in a properties file with resources at build time. By combining profiles for each environment with filters, different filter files can be merged for different environments, based on the profile being used. More information on Maven filters can be found here.
  • Ant copy task: Using a copy task, Ant builds can copy or rename different configuration files for different environments. This is typically done by setting an environment property in an Ant target and using that property as part of the name resolution for the copy task.
  • Environment properties or variables: Each server or environment can have resources available that are specific to it, and applications can locate and load these resources at run time.

These approaches work well for connection settings, login information, and the like. However, service end-point resolution needs in a SOA environment are more complicated. Consuming services in a SOA environment should be in a loosely coupled format, and delivering end-point URIs as part of the application violates this principle. Ideally, end-point URIs are resolved dynamically at run time; dynamically resolving end-point URIs allows services to vary their location and contract independently without the need for consumers to change.

To accomplish dynamic end-point resolution, a service registry is typically used. A service registry can provide service end-point URIs based on a key or registry entry. Oracle Service Registry, a UDDI version 2 and version 3 compliant service registry, and it can be structured to provide dynamic end-point resolution to clients based on a key and environment property.

One way to accomplish dynamic end-point resolution in Oracle Service Registry is to create a taxonomy for the different environments. Each service in the registry can have multiple bindings, one for each environment; each binding has an environment category assigned to it. Clients query the registry for a service and then find the binding corresponding to their environment. Figure 2 shows this process graphically.

Figure 2 -- Dynamic End-Point Resolution with Oracle Service Registry


This article discussed many configuration management techniques and best practices for a SOA development practice. A SOA practice has many of the same configuration management needs as traditional software development; however, SOA development CM has additional and unique needs not seen in traditional development practices. This article showed how to apply industry-standard CM techniques to a SOA environment to ensure high-quality solution delivery.

Brian Jimerson [LinkedIn] is a Senior Technical Architect for Avantia, Inc., a custom solutions provider in Cleveland, OH. He specializes in middleware and web infrastructure solutions, enterprise integration patterns and practices, and enterprise methodologies.