Managing composite lifecycles
Every composite has a state, mode, and associated metadata. The state can be up (started) or down (shut down). The mode can either be active or retired. Metadata is stored in the Metadata Store (MDS), which is a database-based repository used by Oracle SOA Suite 11g, and consists of information that includes default revision number, last modification date, deployment and redeployment times, and instance statistics. Before walking through how to manage the state and mode of composites, we will begin by describing composite revisions.
Understanding revisions
When a HelloWorld composite is deployed to the server, a revision is required during the deployment. Thus, the service’s Web Services Description Language (WSDL) can be accessed via a URL similar to the following, clearly indicating a revision of “1.0” after the composite name:
http://soahost1:8001/soa-infra/services/default/HelloWorld!1.0/HelloWorld.wsdl
However, there may be a case where a new version of the service needs to be deployed and that this version has a different implementation from the existing one. Overwriting the existing version may not be the right option as it would break all client applications that are already utilizing the service. Thus, it makes sense to deploy the new service using a different revision, such as revision “2.0”, and thus make both the versions available simultaneously. It would, therefore, be accessible at a different URL:
http://soahost1:8001/soa-infra/services/default/HelloWorld!2.0/HelloWorld.wsdl
Now, the old and new services are both available and accessible. Clients accessing revision 1.0 of the composite may transition to revision 2.0 at their own pace. If multiple revisions of the same service are deployed, one of them must be specified as the default revision. This can be specified during deployment time or changed at runtime. The default revision would thus be accessed at a revision-independent URL:
http://soahost1:8001/soa-infra/services/default/HelloWorld/HelloWorld.wsdl
Typically, client applications will access the default revision. Revisions are advantageous in environments where maintaining old and new versions of the same composite is required, particularly if it involves breaking changes. As shown in the following screenshot, default revisions are indicated by a green dot in the list of composites for a given partition.
Changing the composite default revision at runtime
If a composite is not the default revision, the Set As Default… button will appear in the composite page, as shown in the following screenshot. By clicking on this button, it is possible at this point to set the revision of this composite as the default revision if you choose to.
If a default composite application is undeployed, the default revision is automatically changed to the last deployed revision.
Deploying, redeploying, and undeploying composites
Composites are deployed and redeployed as SOA Archives or SARs, which are similar to traditional JAR files. 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, the following two important points should be considered:
- A SAR file is a special JAR file that requires a prefix of sca_ and may include environment-specific information bundled within the JAR file. For example, the composite may reference a web service on some external development server. The URL of this web service is hardcoded in the JAR file. Deploying the same JAR to a production server would not be valid.
- Deployment of multiple composites via the console is cumbersome and time consuming. Using ant is the preferred method for deploying multiple SARs and this will be covered in a subsequent section in this article.
Deploying a composite
To deploy a single composite from the console:
- On the navigator, expand Farm_[Domain] | SOA and right-click on soa-infra.
- Navigate to SOA Deployment | Deploy.
- In the field labeled Archive is on the machine where the web browser is running , click on the Browse… button and locate your SAR file (for example,
C:\svn\SOA11g\HelloWorld\deploy\sca_HelloWorld_rev1.0.jar). - Click on Next.
- From the drop-down list, select the partition to which you wish to deploy this composite.
- Click on Next.
- Choose the radio button Deploy as default revision or Do not change the default revision.
- Click on the Deploy button.
When the HelloWorld composite is deployed as revision 1.0 and as the default version, an entry is logged in the soa_server1.out file (located under $MW_HOME/user_projects/domains/soa_domain/servers/soa_server1/logs/soa_server1.out) as follows:
INFO: DeploymentEventPublisher.invoke Publishing deploy event for default/HelloWorld!1.0*soa_fe9ee226-4f29-4db7-b4be- d7410bbc13ffdefault/HelloWorld!1.0*soa_fe9ee226-4f29-4db7-b4be- d7410bbc13ff
Once it is deployed, the service becomes available immediately. If the composite uses inbound resources (such as the JMS Adapter, which consumes from a JMS queue), the consumption begins immediately once the composite is deployed.
The rest of the instructions in this chapter assume that the HelloWorld composite is deployed to the default partition.
Redeploying a composite
To redeploy a single composite from the console:
- On the navigator, expand Farm_[Domain] | SOA | soa-infra.
- Expand the partition (for example, default) and right-click on the composite name that you wish to redeploy (for example, HelloWorld).
- Navigate to SOA Deployment | Redeploy.
- In the field labeled Archive is on the machine where the web browser is running, click on the Browse button and locate your SAR file (for example, C:\svn\SOA11g\HelloWorld\deploy\sca_HelloWorld_rev1.0.jar).
- Click on Next.
- Choose the radio button Deploy as default revision or Do not change the default revision.
- Click on the Redeploy button.
Redeploying a composite overwrites the existing revision. The state of the instances of the older revision are all changed to stale.
Undeploying a composite
To undeploy a single composite from the console:
- On the navigator, expand Farm_[Domain] | SOA | soa-infra.
- Expand the partition (for example, default) and right-click on the composite name that you wish to undeploy (for example, HelloWorld).
- Navigate to SOA Deployment | Undeploy.
- Click on the Undeploy button.
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, denoted by the icon . If the default revision of the composite is undeployed, the last deployed revision of the composite becomes the default.
Starting up and shutting down composites
Composites are automatically started up when they are deployed. If a composite is shut down, all requests to the composite are rejected, including callbacks. New requests are not served and new instances are not created. However, all running instances are allowed to complete.
Though starting up and shutting down composites via the console is extremely easy, if you require to start up or shut down multiple composites, two approaches are available (discussed in detail later in this article):
- Composites deployed to the same partition can all be started up or all be shut down with a single operation.
- Ant can be used to automate the startup and shutdown of composites.
Starting a composite
To start up a single composite from the console:
- On the navigator, expand Farm_[Domain] | SOA | soa-infra.
- Expand the default partition, and click on the HelloWorld composite and the revision.
- Click on the Start Up button, which will only appear if the composite is already shut down.
Shutting down a composite
To shut down a single composite from the console:
- On the navigator, expand Farm_[Domain] | SOA | soa-infra.
- Expand the partition (for example, default), choose from among the deployed composites, and click on the composite name and the revision (for example, HelloWorld[1.0]).
- Click on the Shut Down button, which will only appear if the composite is already started up.
Retiring and activating composites
Composites have two modes—active and retired. These are often confused with composite states, which can be up (started) and down (shut down).
Composites are automatically activated when they are deployed (in fact, they are also started up as well, so active and started composites are really identical in nature). However, when a composite is retired, new instances cannot be created. Existing instances, however, continue to completion. This includes instances that receive callbacks. The ability to receive callbacks and time based waits is the primary difference between a retired composite and a composite that has been shut down.
The only difference between activating a composite and starting up a composite is that activating the composite affects the retired mode, while starting up a composite affects the shutdown state.
Retiring a composite
To retire a single composite from the console:
- On the navigator, expand Farm_[Domain] | SOA | soa-infra.
- Expand the partition (for example, default) and click on the composite name (for example, HelloWorld).
- Click on the Retire button, which will only appear if the composite is already active.
Activating a composite
To activate a single composite from the console:
- On the navigator, expand Farm_[Domain] | SOA | soa-infra.
- Expand the partition (for exampple, default) and click on the composite name (for exampple, HelloWorld).
- Click on the Activate button, which will only appear if the composite is already retired.
Deleting instances
When an SOA composite application is invoked, a new composite instance is created. Every instance has a unique ID and its details can be retrieved from Oracle Enterprise Manager Fusion Middleware Control. Administrators are expected to delete completed instances and free up their data periodically to control growth. Too much instance-related data requires additional storage and it also impacts the performance of the console. Deleting instances is quite easy as demonstrated in the following steps:
- On the navigator, expand Farm_[Domain] | SOA | soa-infra.
- Expand the partition (for example, default) and click on the composite name (for example, HelloWorld).
- Click on the Instances tab.
- At this point, you can delete instances in one of the following two ways:
- Highlight the list of instances (press the Ctrl key and click on each composite one by one) and click on the Delete Selected button.
- Click on the Delete With Options button. From here you can delete instances older than a specific time or delete all instances within a time frame that have a certain state.
We can also bulk delete/purge composite instances from the underlying database dehydration store through the use of SQL scripts.
Structuring composite deployments with partitions
Prior to Oracle SOA Suite11gPS2 (11.1.1.3), as hundreds of composites were deployed to the SOA server, they were all listed in alphabetical order on the console, which made it a burden to manage and was not very structured. Oracle recognized the lack of structure and, therefore, introduced the concept of partitions to help better organize where to deploy your composites. However, partitions are just logical separations to group your composites together. Domain libraries, extension modules, server Java Naming and Directory Interface (JNDI), and infrastructure properties are shared across all partitions.
Partitions do not have their own configuration or logging. They serve no purpose other than grouping composites into separate categories. Thus, for example, code for your Human Resources integrations can reside in a partition separate from your EBS integrations, offering better structuring and organization. There are a few bulk lifecycle management tasks that can be performed on all SOA composite applications in a partition, as we will describe in this section. For example, all composites within a partition can be shut down with a single operation.
The preceding screenshot shows a list of partitions in the navigator under soa-infra. Each partition may have one or more composite applications deployed to it. Partitions cannot be cascaded (that is, a partition cannot have a child partition).
The default partition
Oracle SOA Suite11gshould have, as a minimum, one partition. The default partition is created automatically when the product is installed, but it can be deleted afterwards if you choose to. You must always have at least one partition to allow you to deploy composites.
Managing partitions
You can perform several management tasks pertaining to partitions. These tasks include:
- Creating a partition
- Deleting a partition, including all composites within the partition
- Starting up and shutting down all composites in a partition
- Retiring and activating all composites in a partition
- Undeploying all composites in a partition
The simplest method to manage partitions is via the Manage Partitions page. Simply navigate to this page to create, delete, or perform bulk lifecycle management operations on the partitions:
- Right-click on soa-infra, then click on Manage Partitions to access the Manage Partitions page.
- At this point, you can do one of the following four things:
- Click on the Create button to create a partition.
- Highlight an existing partition and click on the Delete button to delete the partition.
- Highlight an existing partition and click on the Composites Control button to start up, shut down, activate, or retire all composites within that partition.
- Highlight an existing partition and click on the Deployment button to undeploy all composites within this partition, or to deploy a single composite to this partition.
The Manage Partitions page with each of its action buttons is shown in the following screenshot. The Composites Control and Deployment buttons are only activated when a partition is highlighted.
Partitions do not have a state or a mode. Thus, for example, you are not shutting down the partition, you are actually shutting down all composites within the partition.
Creating a partition
When creating a partition, be mindful of the following naming conventions:
- Letters, numbers, underscores, and dashes are allowed (dashes are not allowed as the first character)
- Spaces are not allowed
Also, be aware that partitions cannot be renamed once they are created.
Deleting a partition
When considering deleting partitions, remember that there always needs to be one partition in existence. If you delete all partitions, it will not be possible to deploy any code to the server. If you delete a partition, all composites within that partition are automatically undeployed.
Grouping SOA composite applications into partitions
Typically developers choose a partition to which a particular composite should be deployed, but as an administrator, you must understand its implications.
When composites are deployed—whether through JDeveloper, the console, or ant—a partition name must be specified. Code deployed to the default partition will result in a different WSDL URL than that deployed to, for example, the HumanResources partition as shown here:
- http://soahost1:8001/soa-infra/services/default/HelloWorld/HelloWorld.wsdl
- http://soahost1:8001/soa-infra/services/HumanResources/HelloWorld/HelloWorld.wsdl
Considerations for partition management
There are some considerations regarding partitions that you should be aware of:
- Avoid creating partitions called Dev, Test, and Prod. Though possible, partitions are not designed to separate by environment.
- Domain libraries and SOA extensions (such as MQs and AQs) are shared by all partitions, so it is not possible to have different versions of these libraries or extensions for each partition.
- It is not possible to have the same JNDI address for outbound connection pools in Resource Adapters pointing to different queue manager or data sources for composites deployed in different partitions. Oracle SOA Suite 11 g parameters such as timeouts, threads, and recovery configurations are defined by WebLogic Server domain, not by partition.
- If composites that use inbound adapters (such as the inbound AQ Adapter, in which messages are automatically dequeued from an Oracle AQ) are deployed to multiple partitions, it is not guaranteed which composite will dequeue the inbound message (that is, they will compete with each other).
Setting up ant for automated composite management
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 Suite11gships all necessary ant scripts to perform these tasks, and they are quite easy to use.
Setting the environment
Here, we will describe how to set both Linux and Microsoft Windows based environments to allow you to run your ant commands through the command line. Your ant scripts do not have to be installed on the same machine running Oracle SOA Suite 11g. In fact, it is not unusual to dedicate a single machine or server, which would host your ant scripts, allowing you to centralize the startup, shutdown, and deployment of your SOA composites to multiple target environments. You will also see how ant enables automated build management for your environment in later sections of this artilce.
Setting the environment path for ant
In your environment, we assume that Oracle SOA Suite 11 g is installed, which is recommended, as it will include all the required binaries to run ant. The Middleware Home, the Oracle SOA Suite 11 g Home, the 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 JDK versions may differ depending on the patchset of Oracle SOA Suite11ginstalled. These commands must be executed to set your environment paths before running any ant command.
On Linux/Unix
In this article, we will assume that your code will reside under $CODE under the same Unix account where the Middleware Home and other binaries are installed. This is because the ant scripts require access to specific product libraries. The scripts assume a bash-based shell, so some changes may be required if other shells are used.
To set your environment, we recommend first creating a shell script setAntEnv.sh with the following content while keeping in mind to replace the highlighted values to suit your environment and installation:
export USERNAME=weblogic export PASSWORD=welcome1 export SOAHOST=soahost1 export SOAPORT=8001 export SOAURL=http://${SOAHOST}:${SOAPORT}export CODE=/u01/svn/SOA11g export MW_HOME=/u01/app/oracle/Middleware export ORACLE_HOME=$MW_HOME/Oracle_SOA1 export JAVA_HOME=$MW_HOME/jdk160_24 export ANT_HOME=$MW_HOME/modules/org.apache.ant_1.7.1 export PATH=$JAVA_HOME/bin:$ANT_HOME/bin:$ANT_HOME/lib:$PATH:.
Don’t forget to change the permissions of the script to executable:
chmod 750 setAntEnv.sh
Prior to running any ant command in the remainder of the chapter, simply source this shell script once to set your environment for your session as follows:
source setAntEnv.sh
Finally, make sure to change to the $ORACLE_HOME/bin directory before running any of the ant commands:
cd $ORACLE_HOME/bin
On Windows
We will assume that your code will reside under %CODE%. To set your environment, we recommend first creating a shell script setAntEnv.bat with the following content:
set USERNAME=weblogic set PASSWORD=welcome1 set SOAHOST=soahost1 set SOAPORT=8001 set SOAURL=http://soaHost:soaPort set CODE=c:\svn\SOA11g set MW_HOME=C:\Oracle\Middleware set ORACLE_HOME=%MW_HOME%\Oracle_SOA1 set JAVA_HOME=%ORACLE_HOME%\jdk160_24 set ANT_HOME=%ORACLE_HOME%\modules\org.apache.ant_1.7.1 set PATH=%JAVA_HOME%\bin;%ANT_HOME%\bin;%ANT_HOME%\lib;%PATH%
Make sure to update the highlighted text in the preceding script, to reflect your actual environment and installation.
In your Windows environment, if you do not have Oracle SOA Suite11gand instead only have Oracle JDeveloper11ginstalled, only a few modifications are required, and you should use the following commands instead:
set USERNAME=weblogic set PASSWORD=welcome1 set SOAHOST=soahost1 set SOAPORT=8001 set SOAURL=http://%SOAHOST%:%SOAPORT% set CODE=c:\svn\SOA11g set ORACLE_HOME=C:\Oracle\jdev\jdeveloper set JAVA_HOME=%ORACLE_HOME%\..\jdk160_24 set ANT_HOME=%ORACLE_HOME%\..\modules\org.apache.ant_1.7.1 set PATH=%JAVA_HOME%\bin;%ANT_HOME%\bin;%ANT_HOME%\lib;%PATH%
But only for installations of Oracle JDeveloper 11g, you must also perform a one-time copy of ant-contrib-1.0b3.jar. The file can be downloaded from http://sourceforge.net/projects/ant-contrib/files/ant-contrib/. Simply copy the file to %ANT_HOME%\lib as follows:
copy c:\temp\ant-contrib-1.0b3.jar %ANT_HOME%\lib
Now that your batch script is created, simply run it once in the command prompt to set your environment for your session:
setAntEnv.bat
Finally, make sure to change to the %ORACLE_HOME%\bin directory before running any of the ant commands:
cd %ORACLE_HOME%\bin
All ant commands in the remainder of this chapter will be Linux based. For Windows, simply replace the Linux specific environment variables such as $USERNAME and $SOAHOST with their Windows equivalent of %USERNAME% and %SOAHOST%. Also ensure that the slashes are reversed in the code paths. For example, $CODE/HelloWorld/deploy/sca_HelloWorld_rev1.0.jar in Linux would be %CODE%\HelloWorld\deploy\sca_HelloWorld_rev1.0.jar in Windows.