Throttling JMS adapters in SOA Suite

When working with JCA adapters that need to process huge amounts of transactions per second it's important to have some sort of control over the processing. Failing to do so can lead to memory issues and stuck threads on your servers. In this blog I will show you how you can implement a throttling mechanism on inbound JMS adapters. This way you can control the number of transactions processed per time interval. I will also show you how you can adjust the properties run-time in the Enterprise Manager.

The following two properties will be used for our JMS adapter:

1) adapter.jms.receive.threads: Specifies the number of poller threads that are created when an endpoint is activated. The default is 1.
2) minimumDelayBetweenMessages: Default is False, or no delay. Inbound-only. This property is configured in milliseconds. Ensures that there at least will be MILLI_SECONDS delay between two consecutive messages posted to the downstream composite application.

Note that minimumDelayBetweenMessages is effective per adapter polling thread. If you have configured multiple adapter polling threads, this setting controls the delay between messages processed by each thread only. 

Source: https://docs.oracle.com/middleware/1221/adapters/develop-soa-adapters/GUID-2BB20502-6F62-462F-A490-3AF301AB6089.htm#TKADP2128

I'm working with SOA Suite 11g but these properties exist for 12c too as seen in the Oracle documentation.

These properties are set in the composite.xml as part of the service definition that represents your JCA adapter, as follows:

When setting the values you have to think about what number of transactions per second is desirable. You also need to take the number of managed servers in your environment into account. The following formula could be helpful:

(Number of Managed Servers x thread count) / (minimumDelayBetweenMessages / 1000) 

Calculation example:
-There are two managed servers.
-Each adapter will handle two threads at the same time (set via property adapter.jms.receive.threads = 2).
-Each thread waits at least half a second before processing a new transaction (set via property minimumDelayBetweenMessages = 500ms).

When the formula is applied that means (2 x 2) / (500  / 1000) = 8 transactions per second will be processed per JMS queue.

It's possible to adjust these values run-time. This is done via the Enterprise Manager. Navigate to your SOA Composite and then the Service/Reference Properties:

Adjust the values and click 'Apply'.

Let's do some testing now. To view the results unambiguously, I will just use one active managed server with one queue and one thread per adapter so we can clearly see the time interval.

I will use the following values for the properties: 

<property name="adapter.jms.receive.threads">1</property>
<property name="minimumDelayBetweenMessages">2000</property>

Now according to the formula (Number of Managed Servers x thread count) / ( minimumDelayBetweenMessages / 1000) that means we have (1 x 1) / (2000 /1000) = 0,5 transaction per second. Or 1 transaction every 2 seconds per queue.

I will dump a batch of messages on one JMS queue. Then we will check the logs how the JMS adapter has processed those messages. Of course we would like to see that indeed 1 message was processed every 2 seconds.

First we need to adjust the Diagnostic Logging Level. This is done via the Log Configuration in the Enterprise Manager. Set the level for the oracle.soa.adapter logger to TRACE. This is the logging for JCA adapters.

 
When the batch of messages is imported on the JMS queue to be processed we can check our logging:

 
If we look at the Time column we can verify that the JMS adapter indeed processed 1 message every 2 seconds, great!

Working with an SOA MDS: using abstract WSDL's

The WSDL plays an essential role in defining a web service. Besides describing the structure of the SOAP message, it often contains additional implementation details about the location of the service by having the endpoint described in the service tag. This is what we call a concrete WSDL and it may look as follows:

When we populate our MDS we want it to contain abstract WSDL’s that do not contain these implementation details. This way we take away the direct dependencies between services. It means that the actual referenced services don’t need to be deployed and active in order for our SOA composite to be compiled. It also means we keep our MDS clean in the sense that it does not have any references to other environments.

The way of working with abstract WSDL’s in jDeveloper differs slightly compared to concrete WSDL’s. When creating a reference to a service, you would typically select the WSDL needed from the MDS, as below:

In contrary to using a concrete WSDL you will now get the following warning to notify you the WSDL doesn’t contain any bindings. This is perfectly fine and we can just continue by clicking ‘Yes’.

If you now check the composite.xml, you will notice that no binding details were provided in the binding.ws tag.

We need to provide them manually by looking up the concrete WSDL within the development environment. The format is as follows for the port details:
<Namespace service>#wsdl.endpoint(Service name/Port name)

In our case it becomes: http://www.stellent.com/FolderInfo/#wsdl.endpoint(FolderInfo/FolderInfoSoap)

In the location attribute we provide the endpoint. Altogether your service reference should look like this:

When we create a deployment for installation on a different environment we will create a deployment plan which contains the endpoints of the target environment. This will overwrite the endpoint we provided in the location attribute of the composite.xml.

Error calling an external service from composite: oracle.fabric.common.FabricInvocationException: Unable to find the WSDL service defined for service name

I want to share an error that has kept me busy for a bit. I could not find the cause of the error easily, but as always with troubleshooting: afterwards it all made sense.

So I had an SOA composite calling an external service. Invoking this service resulted in the error below. This happened after deploying the service in my test environment.

      <bpelFault>
        <faultType>0</faultType>
         <remoteFault xmlns="http://schemas.oracle.com/bpel/extension">
           <part name="summary">
              <summary>oracle.fabric.common.FabricInvocationException: Unable to find the WSDL service defined for service name {http://www.stellent.com/GetCaseNumberWCC/}GetCaseNumberWCC.  Please make sure that the port attribute for the binding defined in the composite file is correct by checking the namespace and service name in the #wsdl.endpoint element. In addition, check that the WSDL associated with the binding namespace is imported and currently reachable (check the import nodes at the top of the composite file). Finally, validate any HTTP proxy settings for the server.</summary>
           </part>
            <part name="code">
              <code>null</code>
            </part>
           <part name="detail">
              <detail>Unable to find the WSDL service defined for service name {http://www.stellent.com/GetCaseNumberWCC/}GetCaseNumberWCC.  Please make sure that the port attribute for the binding defined in the composite file is correct by checking the namespace and service name in the #wsdl.endpoint element. In addition, check that the WSDL associated with the binding namespace is imported and currently reachable (check the import nodes at the top of the composite file). Finally, validate any HTTP proxy settings for the server.</detail>
           </part>
         </remoteFault>
       </bpelFault>

It didn’t make sense to me as the external service was up and running and I could call it from SoapUI. The endpoint looked good and I could view the WSDL in my browser. I checked my composite as the text in the exception suggested, but it looked fine and in accordance with my WSDL:

The SOA service worked fine in my development environment but failed in my test environment. It lead me to the configuration plan I generated using jDeveloper. In the reference part I changed the location to my test environment, the rest I had left untouched.

When I viewed the WSDL in my browser (http://tstenvironment:80/default/WCC/Services/GetCaseNumberWcc/V1?wsdl) I saw the following:

Apparently the service and port names were different in OSB, so it made sense that the port attribute wasn’t updated correctly in the configuration plan. This caused the invocation of the service to throw an error about the service name. I corrected the configuration plan (see yellow underlined text), redeployed the composite and it resolved my problem!

In my case the error was caused by a wrong service name and port generated in the configuration file. But while looking for a solution I saw that this error could also be caused by using version specific abstract WSDL’s or the WSDL location in your composite.xml pointing to the wrong destination (for example your local machine). If you’re using an MDS make sure it is in sync with the target MDS.