Oracle SOA Build System

TECHNICAL DESIGN DOCUMENT

Author: Marc Kelderman

Creation Date: 11-8-2008

Last Updated: 12-8-2008

Version: 0.1
1. Document Control

1.1 Revision History

Date Author Version Change Summary

11-8-2008 Marc Kelderman 0.1 First version

1.2 Contributors

Contributor Role Position

1.3 Reviewers

Name Role Position Document Status Date Reviewed Comments

Incorporated

Page ii of 19
 Contents

1. Document Control......................................................................................ii
1.1 Revision History........................................................................................................ ii

1.2 Contributors.............................................................................................................. ii

1.3 Reviewers................................................................................................................. ii

2. Introduction................................................................................................1
2.1 Scope for this Document.......................................................................................... 1

2.2 Requirements for this Document..............................................................................1

2.3 Audience.................................................................................................................. 1

2.4 Document Reference................................................................................................ 1

3. Design Overview........................................................................................2
3.1 Design Goals............................................................................................................ 2

3.2 Requirements........................................................................................................... 2
3.2.1 Platform independent......................................................................................2
3.2.2 Independent of existing software installations.................................................2
3.2.3 Deploy to multiple environments.....................................................................2
3.2.4 Handle the following components...................................................................2
3.2.5 Integrate with a source control system............................................................3
3.2.6 Easy to use..................................................................................................... 3
3.3 Technology............................................................................................................... 3

3.4 Design Assumptions and Decision...........................................................................3

4. Oracle SOA Build Server Design..............................................................4

4.1 Overall view.............................................................................................................. 4

4.2 Technical structure................................................................................................... 5

5. Oracle SOA Build Server Design..............................................................6

5.1 OSBS – Shell script.................................................................................................. 6

5.2 OSBS – build.xml..................................................................................................... 7

5.3 OSBS – tasks........................................................................................................... 7

Page iii of 19
 5.3.1 CompileJava................................................................................................... 7
5.3.2 CreateWar...................................................................................................... 8
5.3.3 CreateEar....................................................................................................... 8
5.3.4 DeployAIABPEL.............................................................................................. 8
5.3.5 DeployAIAESB................................................................................................ 9
5.3.6 DeployAIAXSD............................................................................................... 9
5.3.7 DeployBPEL................................................................................................... 9
5.3.8 DeployDVM................................................................................................... 10
5.3.9 DeployESB................................................................................................... 10
5.3.10 DeployJava................................................................................................... 10
5.3.11 DeployXref.................................................................................................... 11
5.3.12 Download...................................................................................................... 11
5.3.13 EarJava......................................................................................................... 11
5.3.14 WarJava........................................................................................................ 12
5.3.15 MakeAll......................................................................................................... 12
5.3.16 Promote........................................................................................................ 12
5.3.17 SendMail....................................................................................................... 13
5.3.18 UndeployBPEL............................................................................................. 13
5.3.19 UndeployESB...............................................................................................13
5.4 OSBS – Web Interface........................................................................................... 14

Page iv of 19
2. Introduction

2.1 Scope for this Document

This document describes how the Oracle SOA Build system is designed. It describes to
structure of the tool and how it integrates with the different technologies. After reading the
document the reader should be able to maintain this tool to make changes and fix bugs.

2.2 Requirements for this Document

This is a technical document that describes the design of the Oracle SOA Build System.
The document refers to various technologies. Reads should be aware of these
technologies and terminologies.

 Java
 Ant
 Oracle SOA Suite
 Unix scripting
 Perl

2.3 Audience
This document is targeted for technical readers that will maintain the Oracle SOA Build
System. It is expected that the reader has some technical background related to the
technologies mentioned in the previous paragraph.

2.4 Document Reference

Ref Document Name URL

nr.

1 Java http://java.sun.com
2 Ant http://ant.apache.org
3 Oracle SOA Suite http://www.oracle.com/technology/soa/index.html
http://download-uk.oracle.com/docs/cd/B31017_01/integrate.1013/b28981/deployproc.htm
http://www.oracle.com/technology/tech/soa/soa-suite-best-practices/auto-deploy.html
4 Unix scripting http://tldp.org/LDP/Bash-Beginners-Guide/html/index.html
5 Perl http://www.perl.org
6 OSBS User Guide UsingANTinSOAEnvironment_v??.doc

Page 1 of 19
3. Design Overview

3.1 Design Goals

The goal for this design is to design a system that will automate the deployment of SOA
components to various environments; development, test, production etc.

3.2 Requirements
The system must be design and implemented on the following business requirements:

 Platform independent
 Independent of existing software installations
 Deploy to multiple environments
 Handle the following components;
o BPEL
o ESB
o Human Workflow
o Java
o AIA
 Integrate with a source control system
 Easy to use

3.2.1 Platform independent

The system should run on any platform; Linux, Windows or any other Unix system.

3.2.2 Independent of existing software installations

The system should not depend on a particular software installation of a vendor. This
means that the system can be installed on any server or workstation in the network
infrastructure.
The system should be run standalone.

3.2.3 Deploy to multiple environments

Every project has multiple environments that implements a application, for example
development, test, acceptance and production environment. These are the most common
used environments. The OSBS should handle any environment.

Page 2 of 19
3.2.4 Handle the following components

OSBS should deploy and undeploy any component in a SOA project; BPEL, ESB,
Human workflow. While a project consists also of non SOA components, it should
anticipate also on this, like Java or AIA components.

3.2.5 Integrate with a source control system

Source control is essential when implementing a project. OSBS should integrate the
source control systems.

3.2.6 Easy to use

The OSBS should be easy to use. Any complexity on the usages should be hidden from
the user;

 Command line interface

 Web Interface

3.2.6.1 Command line interface

A simple command line interface must be provided to execute all the tasks of OSBS.

3.2.6.2 Web Interface

An even simpler interface should be provided to execute common tasks to users via a
web browser.

3.3 Technology
The system must be implemented based on following Oracle technology:

 Oracle Application Server

 Oracle SOA Suite
 Oracle AIA Framework

The system must be implemented based on following non-Oracle technology:

 Apache ANT – as core build system

 Perl – for the web interface
 (L)inux scripting – for the command line interface on Unix like O/S.
 Windows scripting – for Windows platform

3.4 Design Assumptions and Decision

Assumptions

 Linux is used as platform for development.

Page 3 of 19
Design decisions

 SubVersion is used as source control system for integration with OSBS.

Page 4 of 19
4. Oracle SOA Build Server Design

4.1 Overall view

This diagram shows an overview of the OSBS. The core application is in the middle and
exists only in a build.xml file. This file is an ANT project file. In this project file all tasks of
OSBS are defined.

From this project file the various environments are being called. This depends on various
property files.

Runtime libraries, supplied with OSBS, are used to make the OSBS independent of
existing software installations.

The project file is called via the command line shell script or via the web interface written
in Perl.

Page 5 of 19
4.2 Technical structure

The implementation of the OSBS is as follows:

A script is executed, obbbuild.sh, that will parse the command line arguments and read
the runtime libraries.

After the check on the syntax the project file of ant, build.xml, is called via Java and Ant
runtime libraries with the supplied arguments.

The ant project file will execute the specific task.

The web interface, based on a Perl script, will collect the arguments from the HTTP
request and transform those into a command line argument. So the Perl script calls the
obbuild.sh script.

Page 6 of 19
5. Oracle SOA Build Server Design

5.1 OSBS – Shell script

The shell script is used to verify the syntax of the command line parameters. It should
provide initial feedback if the syntax is not correct.

It should also provide help information on the usage of the tool.

Initially the tool is written for Unix like operating system using the Kourne shell.

The following functions should be executed in the shell script:

 Read environment settings to execute Java and ANT

 Shows help information

 Show the version of OSBS

 Show all the tasks that OSBS can execute

 Set generic the parameters for the various environments

 Verbose output option

 Pass the correct parameters to the ANT build project file.

 Set the correct classpath for the used technologies; Oracle SOA; AIA; SVN, etc.

Page 7 of 19
5.2 OSBS – build.xml

The structure of the OSBS build file is as follows

The build file starts with an initialization part. In this part additional ANT tasks and
functionality is added. This is based on the libraries that were defined by the classpath in
the shell script.

Then there is a part of ‘hidden’ tasks. These are tasks that are used internally and should
not be exposed to the user when it asks of ‘help’ via the command line. The tasks are
often used by other tasks to make the build file maintainable.

At last the various definitions of each task are defined. Each tasks runs on his own. A
task can call others tasks.

5.3 OSBS – tasks

The OSBS must be able to execute the different tasks.

5.3.1 CompileJava

Compile Java files for a specific application.

Page 8 of 19
 Input

The Java source code of the application

Output

The compiled classes of the application

Arguments

Environment setting, name-of the java application

5.3.2 CreateWar

Create a WAR file containing all the JAR files of the BPEL processes.

Input

The name of the file

Output

The EAR file for this application

Arguments

Environment setting, name-for-the-war file

5.3.3 CreateEar

Create an EAR file based on the WAR file that contains the BPEL jar files.

Input

The WAR file created from the CreateWAR task for this application

Output

The EAR file for this application

Arguments

Environment setting, name-of the java application

5.3.4 DeployAIABPEL

Deploy an AIA BPEL processes to a domain on a remote application server on which AIA
is configured.

Input

Page 9 of 19
 The compiled JAR file of the BPEL process

Output

The JAR file is deployed to the application server and registered to AIA

Arguments

Environment setting, name-of the BPEL process, version

5.3.5 DeployAIAESB

Deploy an AIA ESB service to a esb-system on a remote application server on which AIA
is configured.

Input

The ESB service definition

Output

The ESB service is deployed to the application server and registered to AIA

Arguments

Environment setting, name-of the ESB service

5.3.6 DeployAIAXSD

Deploy the AIA XSD/WSDL definitions to the remote application server on which AIA is
configured.

Input

A pointer location where the AIA XSD/WSDL files are located

Output

A zip file containing the XSD and WSDL files of AIA

Arguments

Environment setting

5.3.7 DeployBPEL

Deploy a BPEL processes to a domain on a remote application server.

Input

The name of the BPEL process

Output

Page 10 of 19
 A JAR file with the compiled BPEL process

Arguments

Environment setting, Name of the BPEL process, version, domain

5.3.8 DeployDVM

Deploy all or single domain value map (DVM) table files to the server

Input

The name of the DVM

Output

DVM is loaded into the application server

Arguments

Environment setting, Name of the domain value map

5.3.9 DeployESB

Deploy an ESB service to a system on a remote application server.

Input

The name of ESB Service

Output

The ESB service is registered in the application server

Arguments

Environment setting, Name of the ESB service, esb-system

5.3.10 DeployJava

Deploy an EAR file to application server.

Input

The name of the Java application

Output

The EAR file, from the CreateEAR task, is deployed to the application server

Arguments

Page 11 of 19
 Environment setting, Name of the Java Application

5.3.11 DeployXref

Deploy single XREF table files to the server

Input

The name of the XREF

Output

XREF is loaded into the application server

Arguments

Environment setting, the XREF name

5.3.12 Download

Download latest or a specific version of the source code.

Input

Source control system

Output

The source code is exported from source control into a temporary staging area.

Arguments

Environment setting, the source code version or the latest

5.3.13 EarJava

Create BPEL an EAR file for a Java application.

Input

The WAR file created from the WarJava task for this application

Output

The EAR file for this application

Arguments

Environment setting, name-of the java application

Page 12 of 19
5.3.14 WarJava

Create a WAR file for a Java application

Input

The compiled classes from the CompileJava task for this application

Output

The EAR file for this application

Arguments

Environment setting, name-of the java application

5.3.15 MakeAll

Execute all the tasks that is needed to create a complete new set of the application. This
means that all the components of the application, like BPEL; ESB ; Java, are being
compiled and deployed to the application server in the correct sequence.

The task should be aware of the chicken-egg issue in BPEL/ESB.

Chicken-egg issue: A process A could call another process B that is not yet deployed,
while the process B is calling process A.

Input

The source code of the application

Output

Compiled version of BPEL / ESB / Java / etc have been created and deployed to the
application server.

Arguments

Environment setting, bpel version, bpel domain, ESB system

5.3.16 Promote

The promote task is use to change the source code for a particular environment
(development / acceptance / etc). This means that end-points; URL’s or any other code
that need to be changed for specific environment should be replaced.

In general this is more or less a find and replace on source code.

The promotion should take place on the whole source tree or on a single component.

Input

The source code of the application downloaded from source control

Page 13 of 19
 Output

The source code has been updated on end-points, URL’s or any other code that need to
be replaced.

Arguments

Environment setting, name of the component or everything

5.3.17 SendMail

Send an email.

Input

Output

A email is send.

Arguments

Environment setting, to-addres, subject, message

5.3.18 UndeployBPEL

Undeploy a BPEL process from an application server.

Input

The name of the BPEL process to be undeployed

Output

The BPEL process is undeployed from the application server

Arguments

Environment setting, name of the BPEL process

5.3.19 UndeployESB

Undeploy an ESB service from the application server.

Page 14 of 19
 Input

The name of the ESB service to be undeployed

Output

The ESB service is undeployed from the application server

Arguments

Environment setting, name of the ESB service

5.4 OSBS – Web Interface

A simple web interface should be provided. This interface must act as a shell around the
command line script. The web interface encapsulates the command line interface to a
web interface in which the user can execute a selection of the tasks.

The web interface must be implemented in Perl.

In the web interface the user should be able to select;

 The environment for which the OSBS is working.

 A list of tasks that can be selected; for example Compile BPEL, Deploy Deploy
ESB, Download from source control.

 The object that belongs to the task.

Page 15 of 19