Oracle SOA Suite 12c has grown to include numerous component types and objects, each of these naturally requiring some form of a deployment process. Though developers traditionally use JDeveloper for deployment, this is not ideal in an enterprise with multiple environments. Thus, automating deployments becomes a necessity.
This chapter focuses on the three most commonly developed object types of SOA Suite 12c: SOA composite applications, OSB services, and BAM artifacts. We cover multiple ways each of these can be deployed, giving the administrator the flexibility of choosing the option that best suits their environment.
We describe in detail how to automate the deployment of these components:
Instructions to deploy components to a single node or clustered environments are generally the same.
Developers typically create composite applications that are packaged into single deployable JAR files. These applications can contain any number of service components that include BPEL or BPMN processes, mediator services, human tasks and workflows, and business rules. Composites include logic and code that form the foundation of SOA-based integrations.
There are a number of different tools that can be used to deploy code. However, some are better suited in providing a consistent deployment process. The tools include: JDeveloper, Fusion Middleware Control, Ant, and WLST.
As an administrator performing deployments, JDeveloper and Fusion Middleware Control provide an ancillary role. Developers deploy to certain non-production environments primarily using the former, and the latter should only be used in rare cases, if ever, for production deployments. Knowing how to deploy from Fusion Middleware Control could prove useful in a few cases though.
To many, the act of deploying code into an environment is a one-step process of deployment. However, in reality, there are a number of phases that take place along the way, some of which could be further broken down, but for our purposes, we will treat them as a single unit. These phases include: setup, customization, compilation, packaging, and deployment.
Composites are deployed (or redeployed) as JAR files. In fact, these deployable JAR files are also referred to as SOA archives or SARs. Oracle Enterprise Manager Fusion Middleware Control provides the ability to deploy, redeploy, and undeploy a SAR from the convenience and simplicity of a web browser. Though deploying via the console is extremely easy, two important points should be considered:
To deploy a single composite from the console, we can have a look at the following procedure:
http://adminhost:7001/em
.C:svnSOA12cHelloWorlddeploysca_HelloWorld_rev1.0.jar
):When a composite is deployed, an entry is logged in the soa_server1-diagnostic.log
file (typically located under $MW_HOME/user_projects/domains/soa_domain/servers/soa_server1/logs/
) as follows:
[2015-02-01T16:13:18.092-05:00] [soa_server1] [NOTIFICATION] [] [oracle.integration.platform.blocks.deploy] [tid: DaemonWorkThread: '2' of WorkManager: 'wm/SOAWorkManager'] [userId: <anonymous>] [ecid: 9027493d-b37d-4795-a996-331a7c6ae275-00000004,0:513] [APP: soa-infra] Publishing deploy event for default/HelloWorld!1.0*soa_d91d1c4c-7a7b-4405-9b6e-6dd5a053bfbb
Once it is deployed, the service becomes available immediately. If the composite uses inbound resources, such as an inbound JMS Adapter that consumes from a JMS destination, the consumption begins immediately.
To redeploy a single composite from the console, follow these steps:
default
) and right-click on the composite name you wish to undeploy (for example, HelloWorld
).C:svnSOA12cHelloWorlddeploysca_HelloWorld_rev1.0.jar
).Redeploying a composite overwrites the existing revision. The state of the instance of the older revision is changed to stale.
To undeploy a single composite from the console, go through the following steps:
default
) and right-click on the composite name you wish to undeploy (for example, HelloWorld
).In addition to the service no longer being available, undeploying a composite (or a composite revision) changes the state of all historical instances to stale. If the default revision of the composite is undeployed, the next available revision of the composite becomes the default one.
All component management tasks that can be performed manually through the web-based Oracle Enterprise Manager Fusion Middleware Control console can also be executed with a script through the command-line utility Ant. In this section, we describe how to use Ant to start up, shut down, activate, and retire composites as well as package and deploy them. Oracle SOA Suite 12c ships all the necessary Ant scripts to perform these tasks, and they are quite easy to use.
Here, we describe how to set up a Linux environment to allow you to run your Ant commands through the command line. The Ant scripts do not have to be installed on the same machine running Oracle SOA Suite 12c. In fact, it is not unusual to dedicate a single machine or server that would host your Ant scripts, allowing you to centralize the startup, shutdown, and deployment of your SOA composites to multiple target environments.
In your environment, we assume that Oracle SOA Suite 12c is installed, which is recommended as it will include all the required binaries to run Ant. The Middleware Home, Oracle SOA Suite 12c Home, Java Home, WebLogic Server username and password, and SOA server host and port will need to be updated appropriately to reflect your environment. Directory locations and the JDK version may differ depending on the patchset level of your Oracle SOA Suite 12c installation. These commands must be executed to set your environment paths before running any Ant command.
In this chapter, we assume that your code resides under $CODE
and simply follow the next steps to set up the environment:
setAntEnv.sh
shell script with the following content:export USERNAME=weblogic export PASSWORD=welcome1 export SOAHOST=soahost1 export SOAPORT=8001 export SOAURL=http://${SOAHOST}:${SOAPORT} export CODE=/home/oracle/code export MW_HOME=/u01/app/oracle/middleware export ORACLE_HOME=$MW_HOME/soa export JAVA_HOME=$MW_HOME/jdk1.7.0_15 export ANT_HOME=$MW_HOME/oracle_common/modules/org.apache.ant_1.9.2 export PATH=$JAVA_HOME/bin:$ANT_HOME/bin:$ANT_HOME/lib:$PATH:.
chmod 750 setAntEnv.sh
source setAntEnv.sh
$ORACLE_HOME/bin
directory before running any of the Ant commands:cd $ORACLE_HOME/bin
All the commands in the remainder of this chapter will be based on Linux.
Packaging a SOA composite project effectively involves validating, compiling, and eventually building the project into a single deployable JAR file. To package the HelloWorld
composite application in Linux, simply run:
ant -f ant-sca-package.xml package -DcompositeDir=$CODE/HelloWorld/SOA -DcompositeName=HelloWorld -Drevision=1.0
If no errors are encountered, you should expect to find the sca_HelloWorld_rev1.0.jar
file under the $CODE/HelloWorld/SOA/deploy
directory.
Now that the composite application is packaged, the SAR (or JAR file) can be deployed. The Ant command references the path to the SAR directly (in Linux), as shown here:
ant -f ant-sca-deploy.xml deploy -DserverURL=$SOAURL/soa-infra/deployer -Duser=$USERNAME -Dpassword=$PASSWORD -DsarLocation=$CODE/HelloWorld/SOA/deploy/sca_HelloWorld_rev1.0.jar -Dpartition=default -Doverwrite=true -DforceDefault=true
As shown in these examples, the server URL, username, and password to the Oracle SOA Suite 12c runtime environment must be supplied. The fully qualified path to the SAR file must be provided in the sarLocation
argument. Similar to deploying a composite to the console, you must specify the partition on which you want to deploy. In this example, you can see that we do not provide a revision for the composite. This is because the revision was already specified during packaging time.
The overwrite
argument specifies whether you want to overwrite the composite already deployed to the server and the forceDefault
argument specifies whether you want this revision to be set as the default revision once it is deployed.
The WebLogic Server Tool, more commonly known as WLST, uses Jython, which allows Python scripts to be executed, but can also be used interactively to issue ad hoc commands. In the transition to WebLogic Server 12c, the tool remains largely unchanged. It can, however, provide a valuable asset to administrators who are more comfortable with WLST. Behind the scenes, these WSLT commands actually invoke the Ant scripts.
WebLogic Server, SOA Suite, and JDeveloper installations come shipped with a wlst.sh
script. To deploy SOA composites using WLST, you must run the script from the bin
subdirectory in the Oracle Home directory of the SOA Suite product as follows:
export MW_HOME=/u01/app/oracle/middleware export ORACLE_HOME=$MW_HOME/soa cd $ORACLE_HOME/bin $ORACLE_HOME/common/bin/wlst.sh wls:/offline> wls:/offline>connect()
Once you are connected and in the offline mode, you must connect to the domain by providing your WebLogic username, password, and server URL (for example, t3://adminhost:7001
).
To package the HelloWorld
composite application in WLST, simply run:
sca_package ("/home/oracle/code/HelloWorld/SOA", "HelloWorld", "1.0", oracleHome="/u01/app/oracle/middleware/soa")
The first parameter is the path to the source code of your composite. The second parameter is the name of the composite. The third is the composite revision number, whether it be 1.0, 1.1, and so on. If no errors are encountered, you should expect to find sca_HelloWorld_rev1.0.jar
under the $CODE/HelloWorld/SOA/deploy
directory.
Now that you have a packaged composite application, the JAR file can be deployed. The WLST command to deploy the composite is:
sca_deployComposite("http://soahost1:8001", "/home/oracle/code/HelloWorld/SOA/deploy/sca_HelloWorld_rev1.0.jar", true, user="weblogic", password="password123", partition="default")
The first parameter is SOAURL
, taking the format of http://host:port
. This is the port of the SOA server, not the AdminServer. The SARFILE
parameter should be the absolute path to the JAR file that needs to be deployed.
The next parameter is the overwrite
parameter, a Boolean value that determines whether to overwrite the existing composite or not. The last parameters are simply username, password, and the target partition in which to deploy the composite.
A composite can be undeployed via WLST as well. This is done by running this command:
sca_undeployComposite("http://soahost1:8001", "HelloWorld", "1.0", user="weblogic", password="password123", partition="default")
The parameters here are nearly identical to that of the deployment command, with the only difference being the REVISION
parameter that identifies which revision to undeploy.
Promoting code refers to the activity of taking code from one environment, such as the development environment, and deploying it to the next one, such as the test environment. A typical software development promotion lifecycle sees code move from development to test to QA (quality assurance) to production. As code is successfully tested in one environment, it is deployed to the next.
Unlike Java applications, SOA composite applications do not rely on property files to maintain environment-specific configuration. Many SOA projects may include references to other external services, for example, http://payment-processing-server-dev:7777/proc/servlet/createCustomer
. As you can see from this example URL, the developer is referencing some external development server as identified by the hostname payment-processing-server-dev
. This URL is hardcoded within the code and ultimately included within the deployable SAR. Prior to deploying this code to the test environment, the administrator must find a way to ensure that the test URL is referenced instead (which may have a different host, port, and protocol), as shown here: https://payment-processing-server-test:7778/proc/servlet/createCustomer
.
The SAR may potentially have other environment-specific settings, such as URLs, JNDIs, and hostnames hardcoded in the SAR. One option is to manually extract the contents of the JAR file, manually edit all entries, and re-JAR them. This is a manual, cumbersome, and error-prone process. Another approach is to attach a configuration plan to your composite at deployment.
The configuration plan is a single XML file that is attached to the SAR at deployment time. It is similar to a search-and-replace functionality, ensuring that the references of one environment (such as development) are replaced with the next one (such as the test environment).
The following cfgplan_test.xml
file is a configuration plan designed to be attached to the SAR at deployment time. It is used when deploying code that is written against a development environment to a test environment:
<?xml version="1.0" encoding="UTF-8"?> <SOAConfigPlan xmlns:jca="http://platform.integration.oracle/blocks/adapter/fw/metadata" xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" xmlns:orawsp="http://schemas.oracle.com/ws/2006/01/policy" xmlns:edl="http://schemas.oracle.com/events/edl" xmlns="http://schemas.oracle.com/soa/configplan"> <composite name="*"> <import> <searchReplace> <search>http://soa12cdev:8001</search> <replace>http://soa12ctest:8001</replace> </searchReplace> </import> <service name="readFile"> <binding type="*"> <property name="inFileFolder"> <replace>/u01/input/test</replace> </property> </binding> </service> <reference name="*"> <binding type="ws"> <attribute name="location"> <searchReplace> <search> http://payment-processing-server-dev:7777/proc/servlet</search> <replace> https://payment-processing-server-test:7778/proc/servlet</replace> </searchReplace> </attribute> </binding> </reference> </composite> <wsdlAndSchema name="HelloWorld.wsdl|xsd/HelloWorld.xsd"> <searchReplace> <search>sharedSchemaServerDev</search> <replace>sharedSchemaServerTest</replace> </searchReplace> <searchReplace> <search>7777</search> <replace>80</replace> </searchReplace> </wsdlAndSchema> </SOAConfigPlan>
The file contains two main sections: composite
and wsdlAndSchema
. All entries within the <composite>
tags are applied to the composite.xml
file in the SOA composite application. In this example, the <wsdlAndSchema>
tag is specifically applied to the HelloWorld.wsdl
and xsd/HelloWorld.xsd
files within the project.
Let's walk through the preceding configuration plan in some detail:
<composite name="*">
tag: This indicates that no matter which composite this configuration plan is attached to, the search-replace rules will apply to all, designated by the *. Alternatively, it is possible to create different rules that apply to different composites such as:<composite "HelloWorld1"> <import> <searchReplace> <search>http://soa12cdev:8001</search> <replace>http://soa12ctest:8001</replace> </searchReplace> </import> </composite "HelloWorld1"> <composite "HelloWorld2"> <import> <searchReplace> <search>http://soa12cdev:8001</search> <replace>http://soa12ctest:8001</replace> </searchReplace> </import> </composite "HelloWorld2">
The only reason to separate composite configuration as shown here is if the search-replace rules are different for each composite. If you do not envision any difference in the search-replace rules, we recommend that you stick to <composite "*">
instead in order to maintain simplicity.
<import>
tag: The import
tag is a sub element of the <composite>
tag. Essentially, any search-replace rule within the <import>
tag applies to the <import>
sections in composite.xml
. You can have any number of search-replace elements here.<service>
tag: In this, all composites will likely have a service. A service definition is synonymous with the input of the composite. A composite may have multiple services (for multiple interfaces), where each can be invoked separately.In the configuration plan, the <service>
and <reference>
tags use similar approaches. In the preceding example, there appears to be an inbound File Adapter that has an inFileFolder
property. The code may be hardcoded with the folder property /u01/input/dev
. But here, the configuration plan will overwrite that property with the setting of /u01/input/test
as the input folder.
<reference>
tag: Composite references refer to other resources such as another web service or an adapter. A composite may have zero references or have many. Often, the reference can be a fully qualified URL to some other service either on the same server or a different one. Here, the configuration plan will replace all references to http://payment-processing-server-dev:7777/proc/servlet
(the development server) with https://payment-processing-server-test:7778/proc/servlet
(the test server).Attaching a configuration plan is quite simple. The Ant command to deploy a composite application does not change and only an additional argument is required, which is the reference to the fully qualified path to the configuration plan:
ant -f ant-sca-deploy.xml deploy -DserverURL=$SOAURL/soa-infra/deployer -Duser=$USERNAME -Dpassword=$PASSWORD -DsarLocation=$CODE/HelloWorld/SOA/deploy/sca_HelloWorld_rev1.0.jar -Dpartition=default -Doverwrite=true -DforceDefault=true -Dconfigplan=/tmp/cfgplan_test.xml
The approach to manage code promotion effectively involves following a simple process to maintain consistency and ensure proper substitution of environment-specific settings and deployment to other environments.
The summarized approach we recommend is as follows:
For example, if multiple developers are working on multiple pieces of code that reference the same external service, they should try to be as consistent as possible. Say, for example, that the following reference is used:
http://payment-processing-server-dev:7777/proc/servlet
They should avoid being inconsistent across their code:
http://payment-processing-server-dev.somedomain.org:7777/proc/servlet
http://PAYMENT-PROCESSING-SERVER-DEV:7777/proc/servlet
https://payment-processing-server-dev:7778/proc/servlet
The lack of consistency only means that additional search-replace statements will need to be added in the configuration plans.
Test – cfgplan_test.xml
QA – cfgplan_qa.xml
Prod – cfgplan_prod.xml
The cfgplan_test.xml
configuration plan should replace all development environment settings with the test equivalent. The cfgplan_qa.xml
plan should, similarly, replace all development environment settings that are QA equivalent. The cfgplan_prod.xml
plan should do the same.
Thus, the code will always maintain development environment-specific settings, and it is the configuration plan that will ensure that these settings are replaced appropriately when the code is deployed to the target environment.
In this example, we will demonstrate the usage of configuration plans in a real-world scenario.
We have a simple HelloWorld BPEL project already deployed to both our development and test servers, as shown in Figure 5.2. On our development server, this project is accessible at http://soa12cDEV:8001/soa-infra/services/default/HelloWorldBPEL/helloworld_client_ep?WSDL
.
On our test server, it is accessible here, with only the hostname being changed:
http://soa12cTEST:8001/soa-infra/services/default/HelloWorldBPEL/helloworld_client_ep?WSDL
As shown in the following figure, the developer creates a new Mediator project that invokes this BPEL service and deploys it to the development server:
Our goal, as the administrator, is to deploy this same Mediator project to the test server and change its references to the test environment accordingly.
Once the Mediator project is saved, the project will include two files with hardcoded URLs. The composite.xml
file has the following code snippet:
<reference name="HelloWorldBPEL_BPEL" ui:wsdlLocation="http://soa12cdev:8001/soa-infra/services/default/HelloWorldBPEL/HelloWorldBPEL.wsdl"> <interface.wsdl interface="http://xmlns.oracle.com/SOA12c/HelloWorldBPEL/HelloWorld#wsdl.interface(HelloWorld)"/> <binding.ws port="http://xmlns.oracle.com/SOA12c/HelloWorldBPEL/HelloWorld#wsdl.endpoint(helloworld_client_ep/HelloWorld_pt)" location="http://soa12cdev:8001/soa-infra/services/default/HelloWorldBPEL/helloworld_client_ep?WSDL" soapVersion="1.1"> <property name="weblogic.wsee.wsat.transaction.flowOption" type="xs:string" many="false">WSDLDriven</property> </binding.ws> </reference>
And the Mediator1.componentType
file in the same project includes the following:
<reference name="HelloWorld_BPEL" ui:wsdlLocation="http://soa12cDEV:8001/soa-infra/services/default/HelloWorldBPEL/HelloWorld.wsdl"> <interface.wsdl interface="http://xmlns.oracle.com/SOA12c/HelloWorldBPEL/HelloWorld#wsdl.interface(HelloWorld)"/> </reference>
Prior to deploying this to the test server, we first create a cfgplan_test.xml
configuration plan with the following content:
<?xml version="1.0" encoding="UTF-8"?> <SOAConfigPlan xmlns:jca="http://platform.integration.oracle/blocks/adapter/fw/metadata" xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" xmlns:orawsp="http://schemas.oracle.com/ws/2006/01/policy" xmlns:edl="http://schemas.oracle.com/events/edl" xmlns="http://schemas.oracle.com/soa/configplan"> <composite name="*"> <import> <searchReplace> <search>http://soa12cDEV:8001</search> <replace>http://soa12cTEST:8001</replace> </searchReplace> </import> <reference name="*"> <binding type="ws"> <attribute name="location"> <searchReplace> <search>http://soa12cDEV:8001</search> <replace>http://soa12cTEST:8001</replace> </searchReplace> </attribute> </binding> </reference> </composite> </SOAConfigPlan>
The configuration plan replaces all references of http://soa12cDEV:8001
to the test server's equivalent http://soa12cTEST:8001
.
We finally deploy the Mediator project to the test environment, attaching the configuration plan that has just been created:
cd $ORACLE_HOME/bin ant -f ant-sca-deploy.xml deploy -Duser=$USERNAME -Dpassword=$PASSWORD -DserverURL=$SOAURL/soa-infra/deployer -DsarLocation=$CODE/HelloWorld_Mediator/deploy/sca_HelloWorld_Mediator_rev1.0.jar -Dpartition=default -Doverwrite=true -DforceDefault=true -Dconfigplan=/tmp/cfgplan_test.xml
By attaching the configuration plan, the code originally developed to reference development server-specific URLs is now deployed to the test server that references test-specific URLs.
3.133.133.233