9 Configuring a Reference Configuration Domain

Beginning with Release 12c (12.2.1.4), you can create either a Reference Configuration domain or a Classic domain on the Templates screen in the Configuration Wizard during installation. A Reference Configuration domain guards servers from running into out-of-memory, stuck threads, endpoint connectivity, and database issues. A Reference Configuration domain supports SOA, OSB, and B2B topologies. The templates in these products include Reference Configuration in their names, and are the default templates listed in the Configuration Wizard for these products.

Notes:

• A Reference Configuration domain does not support BPM or BAM components.
• There is no specific Reference Configuration template for ESS. However, ESS can be added to both a Reference Configuration domain and to a Classic domain.
• The Reference Configuration feature does not apply to MFT domains.

What Is a Reference Configuration Domain?

A Reference Configuration domain provides tuned parameters out-of-the-box for newly created SOA projects. Tuned parameters include but are not limited to:

• Java Virtual Machine: heap size, HTTP timeouts.
• WebLogic Server: JTA timeout, HTTP extended logging.
• Database: distributed_lock_timeout, db_securefiles.
• Product-Specific: SOA, Service Bus, Adapters - Work Manager configuration, payload size restriction, and more.

Developing a SOA project in Reference Configuration mode means that you enable Reference Configuration settings in JDeveloper so that new adapters that you create in the project will have special JCA endpoint properties defined in their source files. You can modify these properties directly in the Adapter Configuration Wizard for projects newly created in Release 12c (12.2.1.4). See JCA Endpoint Properties in the Adapter Configuration Wizard in Understanding Technology Adapters.

For more information about the Reference Configuration domain and settings, see:

• Selecting the Configuration Template for Oracle SOA Suite in Installing and Configuring Oracle SOA Suite and Business Process Management.

• Developing SOA Projects in Reference Configuration Mode in Developing SOA Applications with Oracle SOA Suite.

• Deploying SOA Composite Applications or Projects in Oracle JDeveloper in Developing SOA Applications with Oracle SOA Suite.

What Is a Classic Domain?

A Classic domain contains all features except for the Reference Configuration domain settings and is the default domain for JDeveloper.

This chapter includes the following sections:

• Advantages of a Reference Configuration Domain

• Memory Resiliency

• Using the DiffTool Utility for Checking Reference Configuration Domain Settings

• Configured Reference Configuration Domain Settings

Advantages of a Reference Configuration Domain

A Reference Configuration domain guards against the following:

Database Issues:

• Quiesces SOA server when DB allocated space reaches the configured limit.
• Provides optimum default values for database processes and parameters like distributed_lock_timeout and db_securefiles.

Memory Issues:

• Triggers message throttling till the pressure on memory subsides.
• Ramps up processing automatically when memory pressure eases.
• Rejects input payload beyond default threshold.

Connectivity Issues:

• Enables bounded retries on downstream failures.
• Sets optimum default values for connection and read timeouts.
• Provides optimum default JCA connection pool size

Thread Issues:

• Tunes work managers for inbound/outbound services.
• Limits the number of worker threads for JCA adapters.
• Enables dynamic worker threads for JMS adapters.
• Decouples work manager max thread constraint from SOA data source connection pool size.
• Provides optimal default data source connection pool size.

Database Resiliency

Database resiliency provides the capability to monitor the usage of the SOA INFRA schema tablespace. This feature is enabled by default. When tablespace usage goes beyond the configured threshold, SOA server stops accepting new requests and halts processing of messages in component queues. However, SOA server allows the inflight messages to complete processing even though the server is quiesced.

You can configure the following thresholds:

• Warning Threshold Percentage (default: 60): When tablespace allocated space reaches the warning threshold, a warning message is logged and a notification email is sent. This value must be less than the Quiescing and Unquiescing thresholds.
• Quiescing Threshold Percentage (default: 70): When tablespace allocated space reaches the quiescing threshold, a quiescing message is logged, the server is quiesced, and a quiescing email notification is sent.
• Unquiescing Threshold Percentage (default: 65): After quiescing when tablespace allocated space reduces to the unquiescing threshold, an unquiescing message is logged, the server is unquiesced, and an unquiesce email notification is sent.

Note:

When you use a Reference Configuration domain, database resiliency is enabled by default. You can disable this feature using the Enabled attribute of the DBAllocatedSpaceMetricResiliencyManager mbean.

Limitations of Database Resiliency

• Monitors tablespace allocated space and not the used space.
• You must manually perform actions like purge and reclaim to free space in the SOA INFRA schema tablespace when you receive email notifications.

How to Configure Email Notifications for Database Resiliency Thresholds

1. Log in to the Oracle WebLogic Server Administration console.

2. Under Domain Structure in the left pane, expand Services.

3. Click Mail Sessions, then select soaMailSession.

4. Click Configuration under Settings for soaMailSession on the right side.

5. Configure session username, password, and JavaMail properties.

6. Under Domain Structure, expand Diagnostics in the left pane.

7. Click Diagnostic Modules, then select Module-SOADFW.

8. Click the Policies and Actions tab, then select the Actions tab.

9. Click soaDBResiliencyDisableEmailNotification and select the SMTP Properties tab, then set the E-mail Recipients property.

   Repeat for soaDBResiliencyQuiescingEmailNotification, soaDBResiliencyUnQuiescingEmailNotification, and soaDBResiliencyWarningEmailNotification notifications.

Memory Resiliency

Memory resiliency provides the capability to monitor Java heap space and garbage collection events. It checks for low memory situations based on heap usage and garbage collection data.

When it encounters a low memory situation, it triggers throttling of message processing in the SOA server by controlling the threads in the default work manager. This largely helps in avoiding out-of-memory exceptions in SOA. After throttling, the server is monitored for low memory and when the server is out of low memory, throttling is released gradually by bringing the default work manager to its original capacity.

Note:

In a Reference Configuration domain, the memory resiliency feature is enabled by default. You can disable the feature using the Enabled attribute of the MemoryMetricResiliencyManager mbean.

Limitations of Memory Resiliency

• Memory resiliency does not guarantee no out-of-memory exceptions, but largely avoids the situation. Out-of-memory situations can happen under extreme high load where the memory resiliency feature does not receive events related to heap space and garbage collection.

• Memory resiliency supports only ParallelGC garbage collection, which is the default garbage collection of Java 1.8.

• The server returns to the original speed very slowly after it recovers from low memory.

• The default payload restriction size is enabled in a Reference Configuration domain.

• Memory resiliency throttles concurrent executions of BPEL, Mediator, and EDN messages. Other processes can still put pressure on heap usage and can trigger out-of-memory situations.

Using the DiffTool Utility for Checking Reference Configuration Domain Settings

You can use the DiffTool utility to check whether your SOA project properties match the Reference Configuration domain property values. The DiffTool utility provides a JSON report that lists the settings in the current domain and provides the configured settings for a Reference Configuration domain.

To run the DiffTool utility:

1. Open a command prompt and enter:

   cd $ORACLE_HOME/soa/common/tools/difftool

2. Enter the following command:

   $ORACLE_HOME/oracle_common/common/bin/wlst.sh soaDiffTool.py

   Optionally, enter additional arguments:

3. In the JSON report output, review the settings for the current domain and the settings provided for a configured Reference Configuration domain. For more information, see Configured Reference Configuration Domain Settings.

Configured Reference Configuration Domain Settings

Use the following tables as a reference for the configured Reference Configuration domain settings:

• Oracle WebLogic Settings

• Oracle Technology Adapters Settings

• Domain Level Settings

• Oracle Service Bus Settings

• Oracle SOA-Specific Settings

• Database Settings

The Reference Configuration domain default settings are good for most scenarios. However, you may see errors that require the tuning of the Oracle SOA-specific SOADataSource connection pool size (default value of 150) and the database processes (default value of 1500) parameters to support heavy loads. For example:

• No resources currently available in pool SOADataSource to allocate to applications
• TNS:listener does not currently know of service requested in connect descriptor

When increasing the processes parameter value, ensure that the database host can support this change. Otherwise, it may cause the database to crash with out-of-memory errors.

Oracle WebLogic Settings

The following table lists the configured Reference Configuration domain settings for Oracle WebLogic.

Table 9-1 Oracle WebLogic Settings

Parameter	Configured Value	Description and Configuration
JTA timeout	120	The transaction timeout value is in seconds. If the transaction is in active state after this time (counting from begin()), it is rolled back. If the transaction moves to prepared state, the timeout parameter does not apply and the transaction is retried until all the resources are committed. See Configure domain JTA settings in Administering Oracle WebLogic Server with Fusion Middleware Control.
Http Logging	Use Extended Log Setting	Extended log format allows you to customize the information that is recorded. You can set the attributes that define the behavior of HTTP access logs for each server instance or for each virtual host that you define. See Setting Up HTTP Access Logs by Using Extended Log Format in Administering Server Environments for Oracle WebLogic Server.

Oracle Technology Adapters Settings

The following table lists the configured Reference Configuration domain settings for Oracle Technology Adapters.

Table 9-2 Oracle Technology Adapters Settings

Parameter	Configured Value	Description and Configuration
Connection Pool Configurations	All adapters initial-capacity:0 Database Adapter initial-capacity:1 File Adapter max-capacity:1000 FTP, JMS, AQ, and MQ Adapters max-capacity:200 Database Adapter max-capacity:300 All adapters shrink-frequency-seconds:60	See Creating a Connection Pool in Understanding Technology Adapters.
Thread Configuration for inbound adapters	File/FTP Adapter (JCA) : ThreadCount=-1 MQ Adapter (JCA): InboundThreadCount=1 Database Adapter (JCA): NumberOfThreads=1 JMS Adapter (Binding Property): adapter.jms.receive.threads:1 AQ Adapter (Binding Property): adapter.aq.dequeue.threads=1	For the properties marked JCA, set the configuration in the JCA file. File Adapter: <property name="ThreadCount" value="-1"/> MQ Adapter: <property name="InboundThreadCount" value="1"/> Database Adapter: <property name="NumberOfThreads" value="1"/> For the properties that are marked Binding Property, set as binding properties in composite.xml in Oracle SOA Suite or as Dynamic Endpoint Properties in Oracle Service Bus. For example: <service name="Inbound"> <interface.wsdl interface="http://xmlns...#wsdl.interface Inbound_PortType)"/> <binding.jca config="Inbound_jms.jca"> <property name="adapter.jms.receive.threads">1</property> </binding.jca> </service>
Single Poll Cycle in JMS Adapter	adapter.jms.SinglePollCycle=true	Set as Binding Property for Oracle SOA Suite in composite.xml in Oracle SOA Suiteor as Dynamic Endpoint Properties in Oracle Service Bus. For example: <service name="Inbound"> <interface.wsdl interface="http://xmlns...#wsdl.interface Inbound_PortType)"/> <binding.jca config="Inbound_jms.jca"> <property name="adapter.jms.SinglePollCycle">truee</property> </binding.jca> </service>
Set MaxTransactionSize and MaxRaiseSize in Oracle Database Adapter	MaxRaiseSize=1 MaxTransactionSize=10	Set in the JCA file for the Database Activation Spec (inbound). <property name="MaxRaiseSize" value="1"/> <property name="MaxTransactionSizee" value="10"/>
PublishSize and ChunkSize for Oracle File and FTP Adapters	PublishSize=1 ChunkSize=1000	Configured in inbound File and FTP Activation Spec as JCA property as part of debatching. For example: <property name="PublishSize" value="1"/> See  File Debatching in Understanding Technology Adapters. ChunkSize is configured when used with File or FTP Adapter Chunked Interaction Feature. For example: <property name="ChunkSize" value="1000"/> See File ChunkedRead and Oracle File Adapter Chunked Read in Understanding Technology Adapters.
Inbound Retries	jca.retry.count=5 jca.retry.interval=2 jca.retry.backoff=2	Set as Binding Property in composite.xml in Oracle SOA Suite or as Dynamic Endpoint Property in Oracle Service Bus. For example: <service name="Inbound"> <interface.wsdl interface="http:// xmlns...#wsdl.interface(Inbound_PortType)"/> <binding.jca config="Inbound_db.jca"> <property name="jca.retry.count">5</property> <property name="jca.retry.interval">2</property> <property name="jca.retry.backoff">2</property> </binding.jca> </service>

Domain Level Settings

The following table lists the configured domain level Reference Configuration domain settings.

Table 9-3 Domain Level Settings

Parameter	Configured Value	Description and Configuration
XX:+HeapDumpOnOutOfMemoryError	-XX:+HeapDumpOnOutOfMemoryError	Tells the Java HotSpot VM to generate a heap dump when an allocation from the Java heap is not enough. As this option does cause any issues, you can use it for production systems where the OutOfMemoryError exception takes a long time to surface. Set in MW_HOME/soa/common/bin/setSOARefConfigEnv.sh (.cmd for Windows).
+UnlockCommercialFeatures	-XX:+UnlockCommercialFeatures	Used to unlock commercial features. Set in MW_HOME/soa/common/bin/setSOARefConfigEnv.sh (.cmd for Windows).
-Xms -Xmx	8g (Managed servers)	Flag Xmx specifies the maximum memory allocation pool for a Java virtual machine (JVM), while Xms specifies the initial memory allocation pool. Setting this enables your JVM to start with Xms amount of memory and can use a maximum of Xmx amount of memory. Set in MW_HOME/soa/common/bin/setSOARefConfigEnv.sh (.cmd for Windows).
-Xms -Xmx	4g (Admin Server)	Flag Xmx specifies the maximum memory allocation pool for a Java virtual machine (JVM), while Xms specifies the initial memory allocation pool. Setting this enables your JVM to start with Xms amount of memory and can use a maximum of Xmx amount of memory. Set in MW_HOME/soa/common/bin/setSOARefConfigEnv.sh (.cmd for Windows).
-Dweblogic.http.client.defaultReadTimeout	60000	Specifies the default read timeout for the protocol handler used by WebLogic URLConnection. Set in MW_HOME/soa/common/bin/setSOARefConfigEnv.sh (.cmd for Windows).
-Dweblogic.http.client.defaultConnectionTimeout	5000	Specifies the default connect timeout for the protocol handler used by WebLogic URLConnection. Set in MW_HOME/soa/common/bin/setSOARefConfigEnv.sh (.cmd for Windows).
-DHTTPClient.socket.connectionTimeout	5000	This property is a Fusion Applications Configuration rule for HTTPClient.socket.connectionTimeout. It sets the HTTP client connection timeout in milliseconds until the connection is established. Set in MW_HOME/soa/common/bin/setSOARefConfigEnv.sh (.cmd for Windows).
-Dweblogic.security.SSL.minimumProtocolVersion	TLSv1.2	At the start of the SSL handshake, the SSL peers determine the highest protocol version both peers support. However, you can configure WebLogic Server to limit the lowest supported versions of SSL and TLS that are enabled for SSL connections. Set in MW_HOME/soa/common/bin/setSOARefConfigEnv.sh (.cmd for Windows).
-DHTTPClient.socket.readTimeout	60000	This property is a Fusion Applications Configuration rule for HTTPClient.socket.readTimeout. It sets the HTTP client read timeout in milliseconds. Set in MW_HOME/soa/common/bin/setSOARefConfigEnv.sh (.cmd for Windows).
-Dweblogic.MaxMessageSize	30000000	The maximum number of bytes allowed in messages that are received over all supported protocols, unless overridden by a protocol-specific setting or a custom channel setting. Set in MW_HOME/soa/common/bin/setSOARefConfigEnv.sh (.cmd for Windows).
-Doracle.osb.dms	off	Turns off DMS monitoring in Oracle Service Bus. Set in MW_HOME/soa/common/bin/setSOARefConfigEnv.sh (.cmd for Windows).
XX:StringTableSize	-XX:StringTableSize=1000003	JVM Property to set the String pool map size. Set in MW_HOME/soa/common/bin/setSOARefConfigEnv.sh (.cmd for Windows).
-Dcom.ibm.mq.cfg.TCP.Connect_Timeout	5	Applicable to OSB MQ transport/SOA MQ Adapter only. The number of seconds to wait for the connection to IBM MQ server. Set in MW_HOME/soa/common/bin/setSOARefConfigEnv.sh (.cmd for Windows).
-Dcom.ibm.mq.cfg.MQRCVBLKTO	5	Applicable to OSB MQ transport/SOA MQ Adapter only. Once IBM MQ server connection is established, then it represents the number of seconds which the client will wait for the response. Set in MW_HOME/soa/common/bin/setSOARefConfigEnv.sh (.cmd for Windows).
-Dsoa.payload.threshold.kb	10000	Max payload size allowed in Oracle SOA Suite/Oracle Service Bus (applicable for only HTTP/MQ/JMS/transports in Oracle Service Bus). You will not be able to set this if -Dsoa.refconfig.enabled=false. Set in MW_HOME/soa/common/bin/setSOARefConfigEnv.sh (.cmd for Windows).
-Dsoa.refconfig.enabled	true	Enable Reference Configuration domain settings. This JVM property is a parent property for the SOA Reference Configuration domain. For example, if this property is false but -Dsoa.payload.threshold.kb is still set to 10000 then payload restriction will not kick in because -Dsoa.refconfig.enabled=false. Set in MW_HOME/soa/common/bin/setSOARefConfigEnv.sh (.cmd for Windows).
-Dsoa.attachment.threshold.kb	1000000	Max attachment size allowed in Oracle SOA Suite/Oracle Service Bus (applicable for only HTTP Business Service in Oracle Service Bus). This will have no effect if -Dsoa.refconfig.enabled=false Set in MW_HOME/soa/common/bin/setSOARefConfigEnv.sh (.cmd for Windows).

Oracle Service Bus Settings

The following table lists the configured Reference Configuration domain settings for Oracle Service Bus.

Table 9-4 Oracle Service Bus Settings

Parameter	Configured Value	Description and Configuration
SBDefaultRequestWorkManager	-	Work Manager property. All newly created proxy except MQ and JMS use this work manager by default for dispatch policy. See Work Manager
MaxThreadsConstraint-SBDefaultRequestWorkManager	200	SBDefaultRequestWorkManager is associated with the Work Manager maximum threads constraint. See Work Manager: Maximum Threads Constraint: Configuration
MinThreadsConstraint-SBDefaultRequestWorkManager	2	SBDefaultRequestWorkManager is associated with Work Manager minimum threads constraint. See Work Manager: Minimum Threads Constraint: Configuration
SBDefaultRequestWorkManagerMQJMS	-	Work Manager property. All newly created JMS and MQ proxies use this parameter by default for dispatch policy. See Create global Work Managers
MinThreadsConstraint-SBDefaultRequestWorkManagerMQJMS	2	SBDefaultRequestWorkManagerMQJMS is associated with Work Manager maximum threads constraint for JMS and MQ proxies. See Work Manager: Minimum Threads Constraint: Configuration
MinThreadsConstraint-SBDefaultResponseWorkManagerMQJMS	3	SBDefaultResponseWorkManager is associated with Work Manager minimum threads constraint for JMS and MQ proxies. See Work Manager: Minimum Threads Constraint: Configuration
HTTP Business Service	Connection timeout: 5 sec Read timeout: 30 sec Retry count: 1 Retry interval: 15 sec	For configuring Business Service, see Business Service Transport Protocol Configuration. For configuring Business Service to use HTTP Transport, see Configuring Business Services to Use the HTTP Transport.
JMS Business Service	Retry count: 1 Retry interval: 15 sec	For configuring Business Service, see Business Service Transport Protocol Configuration. For configuring Business Service to use JMS Transport, see Configuring Business Services to Use the JMS Transport .
MQ Business Service	Retry count: 1 Retry interval: 15 sec	For configuring Business Service, see Business Service Transport Protocol Configuration. For MQ Transport information, see Using the MQ Transport.
xbus.ha.dead_letter_queue.jmsprovider.ConnectionFactory	xbus.ha.dead_letter_queue.jmsprovider.ConnectionFactory Queue Name: ha_jms_dead_letter_queue JNDI name: ha_jms_dead_letter_queue	This property is used for backing out the messages to the queue in a Reference Configuration domain when the size of the incoming message into JMS transport is more than the allowed size, which is set through -Dsoa.payload.threshold.kb

Oracle SOA-Specific Settings

The following table lists the configured Reference Configuration domain settings for Oracle SOA.

Table 9-5 Oracle SOA-Specific Settings

Parameter	Configured Value	Description and Configuration
SOA Work Manager SOAIncomingRequests_maxThreads	60	Work Manager max thread constraint parameter. This parameter limits the number of concurrent threads that process incoming client requests. Log in to the Oracle WebLogic Server Administration Console. Select Environment from the left menu and then choose Work Managers. On the Summary of Work Managers page, search for SOAIncomingRequests_maxThreads
SOA Work Manager SOAInternalProcessing_maxThreads	145	Work Manager max thread constraint parameter. This parameter limits the number of concurrent threads for internal processes. Log in to the Oracle WebLogic Server Administration Console. Select Environment from the left menu and then choose Work Managers. On the Summary of Work Managers page, search for SOAInternalProcessing_maxThreads
SOALocalTxDataSource (No. of max connections)	150	Data source connection pool size. This parameter determines the total number of concurrent local database connections that are available for your SOA processes. Log in to the Oracle WebLogic Server Administration Console. Select Environment from the left menu and then choose Data Sources. On the data sources configuration page, select SOALocalTxDataSource page. Select the Connection Pool tab and scroll to find the Maximum Capacity attribute.
SOADataSource (No. of max connections)	150	Datasource connection pool size. This parameter determines the total number of concurrent XA database connections that are available for your SOA processes. Log in to the Oracle WebLogic Server Administration Console. Select Environment from the left menu and then choose Data Sources. On the data sources configuration page, select SOADataSource page. Select the Connection Pool tab and scroll to find the Maximum Capacity attribute.
Event delivery network (EDN) configuration: PollTimeoutMillisec (JMS adapter poll timeout) default_EdnConsumer_minThreads_1 (SOA_EDN_WM's min-thread-constraint) ThreadsPerSubscriber	PollTimeoutMillisec: 10ms default_EdnConsumer_minThreads_1: 4 ThreadsPerSubscriber: 1	PollTimeoutMillisec (default 10ms) allows users to specify the milliseconds used by an inbound poller to synchronously receive an event from a subscriber. This is the time after which a call from the poller times out if no event is received. To configure PollTimeoutMilliSec: Log in to the Oracle WebLogic Server Enterprise Manager. Select System MBeam Browser under WebLogic Domain. Search for EDNConfig MBean and change the PollTimeoutMilliSec attribute. EDN workmanager adheres to this min thread. When dealing with heavy loads for EDN, you may receive an exception error because EDN consumption capacity is not sufficient for handling the load. Increase the values for the default_EdnConsumer_minThreads_1 and ThreadsPerSubscriber EDN properties. To configure default_EdnConsumer_minThreads_1: Log in to the Oracle WebLogic Server Administration Console. Select Environment from the left menu and choose Work Managers. Search for default_EdnConsumer_minThreads_1 in the Summary of Work Managers screen.

Database Settings

The following table lists the configured Reference Configuration domain settings for database.

Table 9-6 Database Settings

Parameter	Configured Value	Description and Configuration
distributed_lock_timeout	1400	Specifies the amount of time (in seconds) for distributed transactions to wait for locked resources. Database bounce required: Yes Query: select name, value from v$parameter where name = 'distributed_lock_timeout'; Run MW_HOME/soa/common/tools/refconfig/soaDBParams.py (.cmd for Windows) with system user credentials.
db_securefile	ALWAYS	Specifies whether to treat LOB files as SecureFiles. Database bounce required: No Query: select table_name from user_lobs where SECUREFILE = 'YES' Run MW_HOME/soa/common/tools/refconfig/soaDBParams.py (.cmd for Windows) with system user credentials.
processes	600	Specifies the maximum number of operating system user processes that can simultaneously connect to Oracle. This value should allow for all background processes such as locks, job queue processes, and parallel execution processes. Database bounce required: Yes Query: select name,value from v$parameter where name = 'processes'; Run MW_HOME/soa/common/tools/refconfig/soaDBParams.py (.cmd for Windows) with system user credentials.