In this recipe, we will explore how to add third-party libraries to the SOA Suite server. Usually, our intension is to bring some functionality into the BPEL processes. For the practical reason the extensions come packed as the JAR archive, especially in cases where one package contains many classes.
We will add the Apache Common Codec library in this recipe. However, this same recipe can also be used for the addition of other third-party libraries. The Apache Common Codec library consists of the various encoders for different tasks, such as Base64 encoding/decoding, Digest calculation utilities (MD5 and SHA), and language and network encoders. Follow the given steps to add the library:
- If the server is running, we need to stop it first. Open the command prompt and issue the following command to stop the server:
- To stop the server on a Windows OS, issue the following command:
C:>cd %SOA_Home%in C:ProgramsOracleMiddlewareuser_projectsdomainsSOA_Devin>.stopWebLogic.cmd
- To stop the server on a Unix OS, issue the following command:
#> cd $SOA_Home/bin #> ./stopWebLogic.sh
- To stop the server on a Windows OS, issue the following command:
- After the server has stopped, copy the library (in our case,
commons-codec-1.7.jar) to the extension folder. - After the library is copied, we need to rebuild the extension repository JAR by issuing the
antcommand in the extension directory as shown in the following command line:C:>cd %Middleware_home%\%SOA_Suite_Home%soamodulesoracle.soa.ext_11.1.1 C:ProgramsOracleMiddlewareOracle_SOA1soamodulesoracle.soa.ext_11.1.1>ant Buildfile: build.xml create-manifest-jar: [echo] Creating oracle.soa.ext at C:ProgramsOracleMiddlewareOracle_SOA1soamodulesoracle.soa.ext_11.1.1/oracle.soa.ext.jar :C:ProgramsOracleMiddle wareOracle_SOA1soamodulesoracle.soa.ext_11.1.1UserDefinedFunctions.jar;C:ProgramsOracleMiddlewareOracle_SOA1soamodulesoracle.soa.ext_11.1.1commons- codec-1.7.jar;C:ProgramsOracleMiddlewareOracle_SOA1soamodulesoracle.soa.ext_11.1.1classes [jar] Updating jar: C:ProgramsOracleMiddlewareOracle_SOA1soamodulesoracle.soa.ext_11.1.1oracle.soa.ext.jar BUILD SUCCESSFUL Total time: 0 seconds C:ProgramsOracleMiddlewareOracle_SOA1soamodulesoracle.soa.ext_11.1.1>
- Finally, start the Oracle SOA Suite by issuing the following command:
- To start the Oracle SOA Suite on Windows, issue the following command:
C:>cd %SOA_Home%in C:ProgramsOracleMiddlewareuser_projectsdomainsSOA_Devin>.startWebLogic.cmd
- To start the Oracle SOA Suite on Unix, issue the following command:
#> cd $SOA_Home/bin #> ./startWebLogic.sh
- To start the Oracle SOA Suite on Windows, issue the following command:
The Oracle SOA Suite provides the extension directory that is used to hold for the extensions. We drop the extensions in to the extention directory for usage in different parts of the Oracle SOA Suite.
One of the important steps in this recipe is rebuilding the repository JAR file which is created by the code procedure and is named oracle.soa.ext.jar. If we check the content of its manifest file, we see the following line inside the file:
Class-Path: UserDefinedFunctions.jar commons-codec-1.7.jar classes/
This content shows us the list of included JARs and classes that reside in the extension directory and are exposed as extensions. This leads us to think that we can organize the extension directory any way we want. We can organize the extension directory in hierarchies and as such make extensions more transparent and manageable. Let's reorganize the extension directory a bit now:
- Create the directory
apache_extin the extension directory. - Move the commons codec JAR to the
apache_extdirectory. - Issue the
antcommand again and check the manifest file:Class-Path: UserDefinedFunctions.jar apache_ext/commons-codec-1.7.jar classes/
We can see that a new directory structure is taken into account while rebuilding the repository JAR.
When we put an extension with multiple dependency JARs into place, we put the extension JAR into the extension directory and the dependency jars into the %SOA_Home%lib directory. This way, the extension library will find the dependency classes.
If we use the extensions in a BPEL process, we need to perform some additional steps of configuration in the Oracle SOA Suite Enterprise Manager Console. These steps are required in case we call the code from the BPEL process Java Embedding activity:
- Log in to the Oracle SOA Suite Enterprise Manager Console.
- Right-click on the soa-infra node and then navigate to SOA Administration | BPEL Properties as shown in the following screenshot:
- The BPEL Properties window opens. Select More BPEL Configuration Properties… from the window.
- In the System MBean Browser, select the BpelcClasspath property as shown in the following screenshot:
- The dialog opens; in the Value field, enter the newly added JAR. Depending on the platform where we installed the Oracle SOA Suite, we need to use proper separators (on Windows, the separator is –
;, and on Unix, the separator is the –:character) in case we list more JAR files.
- Click on the Apply button and then on the Return button. When you click on the Apply button, you'll receive the following notification:
In situations where we write a helper or utility class, it is easier to add it to the Oracle SOA Suite server in class form rather than as a JAR file. That way, we avoid preparing a package for later copy to the Oracle SOA Suite server. To learn how to add a custom class to the Oracle SOA Suite server, refer to the next recipe, Adding custom classes to the SOA Suite server.