3 Configuring the SOA Infrastructure

You can configure the properties of the SOA Infrastructure, including Oracle SOA Suite and Oracle BPM Suite profiles, audit levels, payload validation, and default query duration. These property settings can apply to all SOA composite applications running in the SOA Infrastructure.

This chapter also describes how to configure local optimization, stop and start the managed server and SOA Infrastructure, and create global token variables.

• Configuring SOA Infrastructure Properties

• Stopping and Starting the Managed Server and SOA Infrastructure

• Changing the SOA Infrastructure Server URL Property Port in the System MBean Browser

• Configuring Log Files

• Changing the Driver Name to Support Custom XA Drivers

• Specifying a Nondefault XA Transaction Timeout Value for XA Data Sources

• Configuring Database-bound Processing Threads

• Configuring Local Optimization

• Managing Global Token Variables for Multiple SOA Composite Applications

• Preventing Faults from Building Up in SOA

For more information about the SOA Infrastructure, see Introduction to the SOA Infrastructure Application.

Configuring SOA Infrastructure Properties

You can configure the following SOA Infrastructure properties in the SOA Infrastructure Common Properties page:

• Oracle SOA Suite and Oracle BPM Suite profiles

• Audit levels

• Payload validation

• Time period during which to retrieve flow instances and faults data

• Universal Description, Discovery, and Integration (UDDI) registry

• Callback server and server URLs

• Analytics, BPEL sensors, and composite sensors

• Java Naming and Directory Interface (JNDI) data source

• Web service binding properties

The properties set at this level impact all deployed SOA composite applications, except those composites for which you explicitly set different audit level values at the composite application or service engine levels.

Additional advanced properties for the SOA Infrastructure can be configured through the System MBean Browser. You can access these properties from the More SOA Infra Advanced Configuration Properties link on the Common Properties page as described in this section or from the SOA Infrastructure menu by selecting Administration > System MBean Browser > Application Defined MBeans > oracle.as.soainfra.config.

SOA Infrastructure properties are stored in the Oracle Metadata Services (MDS) Repository associated with the SOA Infrastructure. For Oracle SOA Suite, the MDS Repository is configured by default to store its contents in the database.

Note:

For quartz jobs that use Database for persistence, the node to node communication is done through the Database. If one node is down, there is a failover response time configuration stored in Database from where the available node detects the failure and starts processing uncompleted job requests. In SOA, this failover response time is configured for 10 minutes. This implies that there will be a delay of 10 minutes to the escalation and expiration properties if the node goes down just before the expiration time.

To configure SOA Infrastructure properties:

1. Access this page through one of the following options:

   From the SOA Infrastructure Menu...	From the SOA Folder in the Navigator...	From the SOA Composite Menu...
   Select SOA Administration > Common Properties.	Right-click soa-infra. Select SOA Administration > Common Properties.	Select SOA Infrastructure Common Properties.

   The SOA Infrastructure Common Properties page is displayed.

   

   Note:

   • Some property fields are designated with an icon showing green and red arrows. If you change these properties (for example, Server URL), you must restart the SOA Infrastructure.

   • If you exit this page without clicking Apply, the changes are not saved.

   • If you make changes and want to reset these properties to their previous values, click Revert.

The properties of the SOA Infrastructure Common Properties page are described in the following sections:

• Configuring Oracle SOA Suite and Oracle BPM Suite Profiles

• Configuring the Audit Trail, Payload Validation, and Default Query Duration

• Configuring UDDI Registry Properties

• Configuring Callback Server and Server URLs

• Configuring Analytics and Sensors

• Configuring Data Sources and Web Service Binding Properties

• Configuring SOA Infrastructure Advanced Configuration Properties

Configuring Oracle SOA Suite and Oracle BPM Suite Profiles

Oracle SOA Suite profiles provide subsets of functionality. You select a profile and restart the SOA server to activate the selected SOA technologies. Only one SOA profile can be active in a domain at a given time. SOA profiles provide the following benefits:

• Reduce the overall memory footprint of the SOA Infrastructure.

• Make Oracle SOA Suite a more modular platform. You load only the functionality you need to use.

• Reduce overall class loading and overall startup time of the server.

A default profile is automatically set during installation. For Oracle SOA Suite installations (not using Oracle BPM Suite), the default profile is SOA Foundation. For Oracle BPM Suite installations, the default profile is BPM Basic. When you upgrade Oracle SOA Suite from Release 11g to Release 12c, the profile is set to SOA Classic. When you upgrade Oracle BPM Suite from Release 11g to Release 12c, the profile is set to BPM Classic.

Profiles are an advanced feature that must be configured with care. Ensure that you understand the following issues:

• Profile changes, if not done properly, put the system in an unstable state. Only a qualified SOA administrator must perform this operation.

• The SOA servers must be restarted after a profile change to reset the various component/application class loaders and ensure that the Oracle WebLogic Server instance does not hold onto resources for components that have been disabled by the profile change.

• Because SOA profiles define subsets of the overall SOA technology, take care when selecting the correct profile for an existing installation base of SOA composite applications. If a smaller profile is selected that does not support a required SOA technology, composite deployment and runtime errors can occur. For example, if you change the profile from SOA Foundation to BPEL Only, and you have a business flow instance that includes a human task, the human task in the composite becomes inoperable.

• Profiles are only supported on Oracle WebLogic Server.

• When you change a profile, the domain is queried to determine the set of installed templates at runtime, and uses this information to determine which profiles are valid, given the current installation.

To change a profile:

1. Click Change Profile.
2. Select the desired profile, and click OK.

   Profile Type	Profile Description	Adapter Set Provided
   BPM Classic	Contains the Oracle SOA Suite and Oracle BPM Suite functionality enabled in Release 11g (BPEL, BPMN, case management, Oracle Mediator, Oracle B2B, human workflow, and business rules). When you upgrade from Release 11g to 12c, this is the default profile.	The full set of adapters is included (file, FTP, database, JMS, MQSeries, AQ, E-Business Suite, User Messaging Service, socket, LDAP, Coherence, MSMQ, and JDE).
   SOA Foundation	Contains SOA Foundation functionality (BPEL, human workflow, Oracle Mediator, and business rules).	The limited set of adapters is included (file, FTP, database, JMS, MQSeries, AQ, E-Business Suite, and User Messaging Service).
   SOA Foundation With B2B	Contains SOA Foundation and the Oracle B2B functionality (BPEL, human workflow, Oracle Mediator, business rules, and Oracle B2B).	The full set of adapters.
   SOA Foundation With Healthcare	Contains SOA Foundation and the Oracle B2B functionality (BPEL, human workflow, Oracle Mediator, business rules, and Oracle B2B).	The full set of adapters.
   BPM Enterprise	Contains standard Oracle SOA Suite and Oracle BPM Suite functionality (BPEL, BPMN, case management, human workflow, Oracle Mediator, and business rules).	The full set of adapters.
   Orchestration	Contains BPEL and human workflow functionality.	The limited set of adapters.
   BPM Basic	Contains the standard Oracle SOA Suite platform, Oracle B2B, and Oracle BPM technologies (BPEL, BPMN, case management, human workflow, business rules, and Oracle B2B).	The limited set of adapters.
   SOA Classic	Contains the Oracle SOA Suite functionality enabled in Release 11g (BPEL, BPMN, case management, Oracle Mediator, Oracle B2B, human workflow, and business rules). When you upgrade from Release 11g to 12c, this is the default profile.	The full set of adapters.
   BPEL Only	Contains the BPEL service component. This is the minimal profile that only supports BPEL.	The limited set of adapters.
   SOA Foundation Enterprise	Contains the SOA Foundation functionality (BPEL, human workflow, Oracle Mediator, and business rules).	The full set of adapters.

3. Click Apply.

   Until you click Apply, you can click Revert to revert the profile change. In addition, no changes are made if you select different profiles (for example, to view their descriptions) and click Cancel in this dialog.

4. Restart Oracle WebLogic Server immediately.

   Any server that includes a SOA Infrastructure deployment must be restarted:

   • If the SOA Infrastructure is deployed on the administration server, then it must be restarted.

   • If the SOA Infrastructure is deployed on a managed server or a cluster of managed servers, then these servers must all be restarted.

   You must perform lifecycle management operations like composite undeployment, retire, activate etc. only when all managed servers in the cluster are running and accepting requests. You must not try any of these operations while a few managed servers are starting up and SOA platform is not on all the servers in the cluster.

Configuring the Audit Trail, Payload Validation, and Default Query Duration

You can configure the payload validation, audit trail, and default query duration for the SOA Infrastructure. Descriptions for each property are provided in the following table.

To configure the audit trail, payload validation, and default query duration:

1. Make changes appropriate to your environment.

   Element	Description
   Audit Level	Select the level of information to be collected by the message tracking infrastructure. This information is collected in the instance data store (database) associated with the SOA Infrastructure. This setting has no impact on what gets written to log files. Off: No business flow instance tracking and payload tracking information is collected. Drilling down into a flow shows the components and their status. Using this setting limits database growth, and also helps reduce latency and improve throughput. Production: Flow and audit event information is collected and stored in the database. Drilling down into a flow provides the flow trace. The flow trace shows the exact sequence of component interaction, and also shows component statuses. Drilling down into a BPEL instance shows the execution of BPEL activities, and their statuses. As the flow-trace audit trail may not be required for all composites, you may want to set the audit level to Off at the SOA Infrastructure level, and set the audit level to Production for the required composites Development: This option collects payload details in addition to flow and audit events. This setting is not recommended for a production environment, as it will impact performance and result in rapid database growth. This level is useful largely for testing and debugging purposes only. For more information about reducing the audit level for SOA composite applications and the data written to the Oracle SOA Suite schema, see Reducing Audit Levels.
   Payload Validation	Select to enable validation of incoming and outgoing messages. Nonschema-compliant payload data is intercepted and displayed as a fault. By default, this checkbox is not selected.
   Default Query Duration	Specify the time period for retrieved instances and fault data, or accept the default value of 24 hours. This property controls the amount of instance and fault data fetched by default by all out-of-the-box queries. This value is also displayed as the default time range value on pages with query/search functionality (for example, the Dashboard page regions that include query functionality, the Flow Instances pages, Error Hospital pages, the Resequencer pages, and so on). You can override this value on the corresponding page, as needed. Note: It is highly recommended that you set a time period duration because it has a significant impact on the performance of multiple Oracle Enterprise Manager Fusion Middleware Control pages and queries.

2. Click Apply.
3. If you make changes and want to reset these properties to their previous values, click Revert.

Configuring UDDI Registry Properties

You can integrate SOA composite applications running in the SOA Infrastructure with the UDDI registry. The UDDI registry provides a standards-based foundation for locating published services and managing metadata about services (security, transport, or quality of service). You can browse and select published services that meet your needs.

The User and Password properties are applicable if the UDDI registry is secured. These are only used for the secure HTTP configuration of Oracle Service Registry (OSR). The Inquiry URL property is public.

To configure UDDI registry properties:

1. Make changes appropriate to your environment.

   Element	Description	Example
   Inquiry URL	Enter the URL of the master registry you want to query. The URL must not refer to the slave registry itself. Otherwise, you can lose some data. The inquiry URL obtains full-standard UDDI version 3 structures. This is the same UDDI inquiry URL that you specified in the Create UDDI Registry Connection wizard.	http://master.mycompany.com:8888/registry/uddi/inquiry
   User	Enter the registry inquiry user.	admin
   Password	Enter the password for the master registry inquiry user.	Enter a password that uses good security practices.

   For information about setting the endpoint reference and service key, see Changing the Endpoint Reference and Service Key for Oracle Service Registry Integration.

2. Click Apply.
3. If you make changes and want to reset these properties to their previous values, click Revert.

Configuring Callback Server and Server URLs

The Server URLs section displays the following properties. If not explicitly set here, these values are determined at runtime by querying the Oracle WebLogic Server cluster, the web server, or the local server properties.

To configure callback server and server URLs:

1. Make changes appropriate to your environment.

   Element	Description
   Callback Server URL	Enter the callback server URL. This setting applies to all SOA composite application service or reference callbacks. This setting typically takes the format of http://host:port and is used to construct the SOAP service URL (for example, http://host:port/endpoint-context-uri for a service callee to asynchronously send back responses to the caller).
   Server URL	Enter the server URL. This URL is published as part of the SOAP address of a service in the concrete WSDL file. Note: SOAP optimization is automatically configured. Therefore, if you upgrade to Release 12c and are using the optimized shortcut approach in existing applications, optimized calls are activated only when the hostname value (as referred to in the WSDL URL in the composite.xml file) matches the Server URL value. Either set both values to the hostname (for example, myhost) or to the full domain name (for example, myhost.domain.com). If these values do not match, a regular SOAP call is performed instead of an optimized local call. For information about local optimization, see Configuring Local Optimization.

   Note:

   If you change the Callback Server URL and Server URL values (for example, when moving from a test to a production environment), you must restart Oracle WebLogic Server for the WSDLs to be regenerated.

2. Click Apply.
3. If you make changes and want to reset these properties to their previous values, click Revert.

Configuring Analytics and Sensors

The Analytics and Sensors Configuration section enables you to manage the collection of analytics, BPEL sensors, and composite sensors. By default, all selections are enabled.

Note the following order of precedence when disabling or enabling a selection on the SOA Infrastructure Common Properties page:

• Disabling a selection on the Common Properties page disables the collection of data for that selection for all SOA composite applications. For example, if you disable composite sensors on the Common Properties page, composite sensor details are not collected for any flow instances created after this change.

• Enabling a selection on the Common Properties page enables you to disable that setting at the individual SOA composite application level. For example, if you enable composite sensors on the Common Properties page and disable composite sensors for an individual SOA composite application (for example, named LoanFlow) on its home page under Settings > Enable/Disable Analytics & Sensors, composite sensor details are not collected for any instance of the LoanFlow SOA composite application after this change. However, all other flow instances continue to collect composite sensor details.

To configure analytics and sensors:

1. Make changes appropriate to your environment.

   Element	Description
   Analytics	Use to manage the collection of analytics in SOA composite applications. When enabled, analytics enable you to perform the following tasks: Measure a business indicator at a certain point in the process or in a section of the process. Capture BPEL process metrics that are sent to Oracle BAM Server, and then used for analysis and graphic display.
   BPEL Sensors	Use to manage the collection of BPEL sensor details in SOA composite applications. When enabled, BPEL sensors collect data for any fault, activity, and variable sensors defined in the composite.
   Composite Sensors	Use to manage the collection of composite sensor details in SOA composite applications. When enabled, composite sensors perform the following tasks: Monitor incoming and outgoing messages. Specify composite sensor details in the search utility of the Flow Instances page of a SOA composite application in Oracle Enterprise Manager Fusion Middleware Control. This action enables you to locate a particular instance. Publish JMS data computed from incoming and outgoing messages.

2. Click Apply.
3. If you make changes and want to reset these properties to their previous values, click Revert.

For information about setting analytics and sensors in an individual SOA composite application, see Disabling and Enabling the Collection of Analytic, BPEL Sensor, and Composite Sensor Data.

Configuring Data Sources and Web Service Binding Properties

A data source enables you to retrieve a connection to a database server.

To configure data sources and web service binding properties:

1. Expand the Advanced section.

   The Data Sources section displays the following properties.

   
   Description of the illustration soa-infra-common-props-adv.png
2. Make changes appropriate to your environment.

   Element	Description	Example
   Server Data Source JNDI	Displays the JNDI location for the server data source. Click Configure to go to the data source configuration page of the Oracle WebLogic Server Administration Console. Global transaction support should be disabled for this data source.	jdbc/SOALocalTxDataSource
   Server Transaction Data Source JNDI	Displays the JNDI location for the server transactional data source. Click Configure to go to the data source configuration page of the Oracle WebLogic Server Administration Console. You must configure the data source for global transactions.	jdbc/SOADataSource
   Nonfatal Connection Retry Count	Enter the maximum number of times a nonfatal connection error can be retried before failing. These type of errors occur for any connection error with the dehydration store (for example, Oracle Real Application Clusters failover, database shutdown, and so on).	10

   The Web Service Binding Properties section displays the following options.

3. Make changes appropriate to your environment.

   Element	Description	Example
   Oracle SSL Ciphers	Enter the list of supported Oracle ciphers. A cipher suite is a set of algorithms that provide security for data transmissions. Before data can flow through an SSL connection, both sides of the connection must negotiate common algorithms to use.	SSL_RSA_WITH_RC4_128_MD5
   Oracle Wallet Password	Enter the wallet password for the keystore.	Enter a password that uses good security practices.
   Use Chunking	Select to enable chunking of data for SOAP over HTTP deliveries.	- -
   Chunk Size	Specify a chunk size. The value must be less than or equal to 999. The size is used for SOAP over HTTP deliveries and is specified in bytes.	500

4. Click Apply.
5. If you make changes and want to reset these properties to their previous values, click Revert.

Configuring SOA Infrastructure Advanced Configuration Properties

To change advanced parameters, click More SOA Infra Advanced Configuration Properties. This opens the System MBean Browser. The properties that display include, but are not limited to, the following. Descriptions are provided for each property.

• AuditConfig: The status of BPEL message recovery. This property includes the following key:

  • excludeBpelMaxCreationTime key: Enables you to set the time period for excluding messages that require recovery. For more information, see Monitoring the Overall Status of the SOA Infrastructure or Individual SOA Folder.

• CreateWSCallTrackingMBean: Controls the creation of an MBean for tracking the elapsed time of web service calls. If the elapsed time threshold is exceeded, an incident is created. When set to true, you can create a watch. This setting applies to all SOA composite applications in the SOA Infrastructure. For more information, see Creating Watches and Notifications.

• GlobalTxMaxRetry: The maximum number of times an invocation exception can be retried.

• GlobalTxRetryInterval: The number of seconds between retries for an invocation exception.

• HttpServerURL: The HTTP protocol URL published as part of the SOAP address of a process in the WSDL file.

• HttpsServerURL: The HTTPS protocol URL published as part of the SOAP address of a process in the WSDL file.

• KeystoreLocation: The path to the Oracle SOA Suite keystore.

• UddiCacheLifetime: The UDDI endpoint cache life span.

Stopping and Starting the Managed Server and SOA Infrastructure

You can stop and start the SOA Infrastructure in Oracle Enterprise Manager Fusion Middleware Control for maintenance or for configuration restarts. To do so, stop and start the managed server on which the SOA Infrastructure is installed. This restarts both the managed server and the SOA Infrastructure.

Note:

• Starting with 11g Release 1 (11.1.1.4.0), you can no longer stop and start the SOA Infrastructure from the soa-infra menu in the navigator.

• You can also have a developer configuration that only includes an administration server, and no managed servers.

For more information about server startup issues, see Server Troubleshooting.

To stop and start the managed server and SOA Infrastructure:

1. Access this page through one of the following options:

   From the WebLogic Domain Menu...	From the WebLogic Domain Folder in the Navigator...
   Select Control.	Right-click the managed server (for example, soa_server1). Select Control.

2. To shut down the managed server and SOA Infrastructure, select Shut Down.

3. Click OK when prompted to shut down the managed server and SOA Infrastructure.

4. Wait for shutdown to complete.

5. To start the managed server and SOA Infrastructure, select Start Up.

For information on stopping and starting managed servers with Node Manager, see Administering Node Manager for Oracle WebLogic Server.

For information on starting and stopping managed servers with WLST commands, see Administering Oracle Fusion Middleware.

SOA Composite Application States and SOA Infrastructure Shutdown

SOA composite application states are not updated to indicate that they are down after SOA Infrastructure shutdown. If you attempt to access the composite, you receive an error message stating that composite details cannot be retrieved:

soa-infra runtime connection error  An error happened while connecting to
soa-infra runtime at  t3://address:8001/soa-infra.

This message may lead you to believe that another issue exists in the system. However, this is not the case.

These composite states display as up or, in some cases, pending because this metric indicates whether the composite is enabled, and is independent of whether the SOA Infrastructure is started. In addition, the composite is still active and can receive requests on other managed servers in a cluster.

Restarting the SOA Infrastructure Does Not Activate Endpoints When a Retired Composite is Activated

If a SOA composite application with adapter endpoints is in a retired state, the endpoints are not activated if you perform the following actions:

• Restart the SOA Infrastructure

• Activate the SOA composite application

This is because files, records, and so on are not picked up by the endpoint adapters. As a workaround, redeploy the SOA composite application after restarting the SOA Infrastructure.

SOA Infrastructure Startup Failure When cwallet.sso Includes the SOA Map

When cwallet.sso has the SOA map, you receive an error message similar to the following when attempting to start the SOA Infrastructure.

Caused By: java.security.UnrecoverableKeyException: Password verification 
failed 
        at 
sun.security.provider.JavaKeyStore.engineLoad(JavaKeyStore.java:769) 
        at 
sun.security.provider.JavaKeyStore$JKS.engineLoad(JavaKeyStore.java:38) 
        at java.security.KeyStore.load(KeyStore.java:1185) 
        at oracle.j2ee.ws.saaj.util.SSLUtil.loadKeyStore(SSLUtil.java:73) 
        at 
oracle.j2ee.ws.saaj.util.SSLUtil.getKeyManagerFactory(SSLUtil.java:88) 
        at oracle.j2ee.ws.saaj.util.SSLUtil.getKeyManagers(SSLUtil.java:97) 
        at 
oracle.j2ee.ws.saaj.util.SSLUtil.createSSLSocketFactory(SSLUtil.java:50) 
        at 
oracle.integration.platform.common.SSLSocketFactoryManagerImpl.getSSLSocketFac 
tory(SSLSocketFactoryManagerImpl.java:58) 
        at oracle.fabric.common.wsdl.WSDLManager.init(WSDLManager.java:356) 
        at oracle.fabric.common.wsdl.WSDLManager.<init>(WSDLManager.java:101) 
        at 
oracle.fabric.common.metadata.MetadataManagerImpl.getWSDLManager(MetadataManag 
erImpl.java:283) 
        at 
oracle.fabric.composite.model.CompositeModel.getWSDLManager(CompositeM 

Perform the following steps to resolve this issue.

1. Perform one of the following actions:

   • Delete the SOA map in cwallet.sso.

   • Remove $DOMAIN_HOME/config/fmwconfig/default-keystore.jks. Oracle Web Services Manager (OWSM) uses this file.

2. Restart the SOA Infrastructure.

Changing the SOA Infrastructure Server URL Property Port in the System MBean Browser

In addition to the SOA Infrastructure Common Properties page described in Configuring SOA Infrastructure Properties, you can also change the SOA Infrastructure ServerURL property port in the System MBean Browser of Oracle Enterprise Manager Fusion Middleware Control.

When changing the port, note the following details:

• If the SOA Infrastructure and managed Oracle WebLogic Server port numbers are different, you receive a ConnectException error when trying to connect to Oracle BPM Worklist. Ensure that these port numbers match.

• You cannot change the SOA Infrastructure port from the Oracle WebLogic Server Administration Console. Only the port for the managed Oracle WebLogic Server can be changed from the Oracle WebLogic Server Administration Console.

To change the SOA Infrastructure port:

1. Access this page through one of the following options:

   From the SOA Infrastructure Menu...	From the SOA Folder in the Navigator...	From the SOA Composite Menu...
   Select SOA Administration > Common Properties.	Right-click soa-infra. Select SOA Administration > Common Properties.	Select SOA Infrastructure Common Properties.

2. In the Name column, click ServerURL.

   The Attribute: ServerURL page appears.

3. In the Value field, change the port.

   
   Description of the illustration soa-serverurl-mbean-browser.png

4. Click Apply.

5. Change the managed Oracle WebLogic Server port in the Oracle WebLogic Server Administration Console to the same value.

   In environments in which a load balancer is used in front of an Oracle WebLogic Server cluster, the ServerURL property host and port can be different from the Oracle WebLogic Server host and port. This is typical for enterprise deployment environments in which a load balancer distributes requests across the managed servers in the Oracle WebLogic Server cluster. For more details, see the Enterprise Deployment Guide for Oracle SOA Suite.

Configuring Log Files

Oracle SOA Suite components generate log files containing messages that record all types of events, including startup and shutdown information, errors, warning messages, access information on HTTP requests, and additional information.

To configure log files:

1. Access this page through one of the following options:

   From the SOA Infrastructure Menu...	From the SOA Folder in the Navigator...
   Select Logs > Log Configuration.	Right-click soa-infra. Select Logs > Log Configuration.

   The Log Configuration page displays the following details:

   • A View list for selecting the type of loggers for which to view information:

     • Persistent: Loggers that become active when a component is started. Their configuration details are saved in a file and their log levels are persisted across component restarts.

     • Active runtime: Loggers that are automatically created during runtime and become active when a particular feature area is exercised (for example, oracle.soa.b2b or oracle.soa.bpel). Their log levels are not persisted across component restarts.

   • A table that displays the logger name, the Oracle Diagnostic Logging (ODL) level for setting the amount and type of information to write to a log file, the log file, and the log level state.

2. Specify search criteria (for example, soa), and click the Search icon.

   Oracle SOA Suite loggers are displayed.

   
   Description of the illustration soa-log-levels.png

3. Perform the following log file tasks on this page:

   1. In the Logger Name column, expand a logger name. This action enables you to specify more specific logging levels within a component.

   2. In the Oracle Diagnostic Logging Level columns, select the level and type of information to write to a log file.

   3. In the Log File column, click a specific log file to create and edit log file configurations.

      For more information about ODL log files and the level and type of logging information to write to a log file, see Administering Oracle Fusion Middleware.

4. Click the Log Files tab.

   This page enables you to create and edit log file configurations, including the log file in which the log messages are logged, the format of the log messages, the rotation policies used, and other parameters based on the log file configuration class.

   
   Description of the illustration soa-log-files.png

   For information on setting logging levels and Oracle SOA Suite logging files to view, see Setting Logging Levels for Troubleshooting.

Configuring the Logging File Encoding Property

The oracle-soa-handler log handler property of the soa-diagnostic.log file has no encoding property specified in the SOA_Domain/config/fmwconfig/servers/server_soa/logging.xml file. Instead, the soa-diagnostic.log file is written in the operating system's default encoding format. This can cause the following problems:

• Non-ASCII error messages can become unreadable because logging information is written to soa-diagnostic.log in the server's default encoding format.

• On Windows operating systems, writing in the default encoding format can lead to non-ASCII data loss.

To avoid this problem, specify a value of UTF-8 for the oracle-soa-handler log handler property in the logging.xml file.

<?xml version='1.0'?>
<logging_configuration>
 <log_handlers>
  <log_handler name='wls-domain'
 class='oracle.core.ojdl.weblogic.DomainLogHandler' level='WARNING'/>
  <log_handler name='oracle-soa-handler'
 class='oracle.core.ojdl.logging.ODLHandlerFactory'>
   <property name='path' value='c:\soa1210.1411\user_
projects\domains\soa/servers/server_soa/logs/soa-diagnostic.log'/>
   <property name='maxFileSize' value='10485760'/>
   <property name='maxLogSize' value='104857600'/>
   <property name='supplementalAttributes' value='J2EE_APP.name,J2EE_
MODULE.name,WEBSERVICE.name,WEBSERVICE_PORT.name,composite_instance_id,component_
instance_id,composite_name,component_name'/>
    <property name='encoding' value='UTF-8'/>   
  </log_handler>
 </log_handlers>
...

Log files are written with ODL. You can view the content of log files from Oracle Enterprise Manager Fusion Middleware Control.

For more information about logging, see Administering Oracle Fusion Middleware.

Configuring Logging to Diagnose Performance Issues in Oracle Enterprise Manager Fusion Middleware Control Pages

Oracle SOA Suite can log performance metrics for API calls. You can trace the performance of costly API calls to the Oracle Enterprise Manager Fusion Middleware Control page that made them. This tracing is useful when an API call does not perform efficiently. The view id is logged with other information to the following file:

FMW_HOME/user_projects/domains/domain_name/servers/weblogic_name/logs/weblogic_name-soa-tracking.trc

For example, you can enable logging at the FINE level for the root logger associated with the weblogic_name-soa-tracking.trc file, reproduce the problem to diagnose, and set the logging level back to SEVERE. The content of the log can be analyzed to pinpoint the underlying operations performed by Oracle SOA Suite.

To configure logging to diagnose performance issues:

1. Access this page through one of the following options:

   From the SOA Infrastructure Menu...	From the SOA Folder in the Navigator...
   Select Logs > Log Configuration.	Right-click soa-infra. Select Logs > Log Configuration.

   The Log Configuration page is displayed.

2. In the Logger Name column, expand oracle.soa > oracle.soa.sql.trc.fabric.

3. Set the logging level to FINE.

   
   Description of the illustration soa-log-level-fine.png

4. Click Apply.

   The Oracle Enterprise Manager Fusion Middleware Control page that generated the API call is logged to the weblogic_name-soa-tracking.trc file. For this example, /ai/soa/composite (SOA composite application home page) is identified as the page.

   [2012-08-07T23:21:04.488-07:00] [soa_server1] [TRACE:32] []
   [oracle.soa.sql.trc.fabric.toplink_session.tracking_session] [tid:
   [ACTIVE].ExecuteThread: '1' for queue: 'weblogic.kernel.Default
   (self-tuning)'] [userId: weblogic] [ecid:
   6fec0e67fbf81939:-7d87fd84:138e67064fb:-8000-0000000000000dd6,1:24469]
   [SRC_CLASS: oracle.integration.platform.instance.store.ToplinkSessionLogger]
   [APP: soa-infra] [SOA.toplink.session_name: tracking_session]
   [SOA.logging.category: query] [SOA.call_origin_category: /ai/soa/composite]
   [SOA.call_origin: em] [SRC_METHOD: log] execute_query

Changing the Driver Name to Support Custom XA Drivers

The default SOA Infrastructure data source is always XA-enabled. If your data sources require support for custom drivers, you must change the driver name on Oracle WebLogic Server.

To change the driver name through one of the following methods:

• Edit in Oracle WebLogic Server Administration Console.

  1. Log in to Oracle WebLogic Server Administration Console.

  2. Under Domain Structure on the left side of the page, select Services > Data Sources > SOADataSource > Connection Pool.

  3. For the Driver Class Name, change the value to a custom data source (for example, oracle.jdbc.xa.client.myDataSource).

  4. Restart the server.

• Edit the soaDataSource-jdbc.xml file.

  1. Open the soaDataSource-jdbc.xml file on Oracle WebLogic Server.

  2. Change the SOADataSource driver name from .jdbc.OracleDriver to oracle.jdbc.xa.client.myDataSource.

     <?xml version="1.0" encoding="UTF-8"?>
     <jdbc-data-source
     /. . .
     . . .
     /  <name>SOADataSource</name>
      <jdbc-driver-params>
           <url>jdbc:oracle:thin:myhost.us.example.com:1537:co0yf470</url>
           <driver-name>*oracle.jdbc.xa.client.myDataSource*</driver-name>
        <properties>
          <property>
            <name>user</name>
            <value>fusion_soainfra</value>
          </property>
        </properties>
     /  . . .
      . . ./
      </jdbc-driver-params>
     /. . .
     . . ./
     </jdbc-data-source>

Specifying a Nondefault XA Transaction Timeout Value for XA Data Sources

The default XA transaction timeout value for XA data sources is 0 seconds. You can change the default value in the Oracle WebLogic Server Administration Console. Follow these steps.

To specify a nondefault XA transaction timeout value for XA data sources:

1. Log in to Oracle WebLogic Server Administration Console.
2. Under Domain Structure on the left side of the page, select Services > Data Sources.
3. In the Name column of the Data Sources table, select EDNDataSource (for event delivery network transactions) or SOADataSource (for all other types of transactions).
4. Under the Configuration tab at the top, click the Transaction subtab.
5. In the XA Transaction Timeout field, enter a value in seconds.
6. Select the Set XA Transaction Timeout checkbox. You must select this checkbox for the new XA transaction timeout value to take effect.
7. Click Save.

Configuring Database-bound Processing Threads

When client requests come in at a high rate, the requests collect in a queue and wait for the availability of database connections. To handle more concurrent incoming requests, you can change the following properties:

• The SOADataSource property in the Oracle WebLogic Server Administration Console

• The percentages used to calculate the maximum number of threads with the SOAMaxThreadsConfig property in the System MBean Browser

The incomingRequestsPercentage and internalProcessingPercentage elements of SOAMaxThreadsConfig are defined so that combined processing tasks are less likely to overwhelm the number of database connections. The thread limit number used for these maximum threads constraints is calculated based on the maximum capacity value of the SOADataSource property in the Oracle WebLogic Server Administration Console.

If you change the maximum capacity for the SOADataSource property, a background process is initiated to readjust the maximum threads number defined for both the incomingRequestsPercentage and internalProcessingPercentage elements. The automatic adjustment must acquire the Oracle WebLogic Server configuration editing lock before it can proceed with the operation. If you have already acquired the lock, you must release it to allow the automatic adjustment to proceed.

You can adjust the percentage allocated for internal processing versus incoming requests. The default percentage allocation enables the internal processing tasks to take up to 65% of the database connection pool size. Incoming requests take up to 15% of data source pool size, and the remaining 20% account are for adapter and Event Delivery Network processing.

Changing the Maximum Capacity for the SOADataSource Property

To change the maximum capacity for the SOADataSource property:

1. Log in to Oracle WebLogic Server Administration Console.

2. In the Domain Structure, select Services > Data Sources.

3. At the top of the page, click Connection Pool.

4. In the Name column, select SOADataSource.

5. In the Maximum Capacity field, update the value (for example, to 300 to accommodate loads with 200 threads). The default value is 50.

   Note:

   For GridLink data sources, the maximum capacity of the connection pool is by default double the maximum capacity of the connection pool of the normal data source.

6. Click Save.

Configuring the SOAMaxThreadsConfig Property

To configure the SOAMaxThreadsConfig property:

1. Access this page through one of the following options:

   From the SOA Infrastructure Menu...	From the SOA Folder in the Navigator...	From the SOA Composite Menu...
   Select SOA Administration > Common Properties.	Right-click soa-infra. Select SOA Administration > Common Properties.	Select SOA Infrastructure Common Properties.

2. Click More SOA Infra Advanced Configuration Properties.

3. Expand SOAMaxThreadsConfig.

4. Make changes appropriate to your environment.

   
   Description of the illustration soa-infra-maximum-threads.png

   For example, make the following changes to accommodate these thread values:

   • incomingRequestsPercentage: 20 (to accommodate 10 threads)

   • internalBufferPercentage: 50 (to accommodate 25 threads)

   • internalProcessingPercentage: 30 (to accommodate 15 threads)

5. Click Apply.

6. If you make changes and want to reset these properties to their previous values, click Revert.

Configuring Local Optimization

Local optimization is the process of one SOA composite application invoking another SOA composite application through direct Java invocations in an environment in which both composites are on the same SOA server (JVM).

Direct Java invocations are generally more efficient than SOAP over HTTP calls. Therefore, whenever the conditions are met for direct Java invocations, Oracle SOA Suite optimizes the service calls for the co-located composites.

Condition Checks for Using Local Optimization

Oracle SOA Suite performs the following condition checks to determine if local optimization is possible.

• It must be a composite-to-composite invocation. This is the most fundamental criteria that makes direct Java calls possible when both the client and target services are implemented based on the same SOA Infrastructure (that is, the same SOA server).

• The composite implementing the reference (target) service must be active. This condition requires the target composite to be up and running, which in turn ensures that the reference service is available.

  Note:

  The state of the target composite must be on and active. A stopped or retired state is not eligible for local optimization.

• The client and target composites must be co-located on the same server. This is an obvious requirement for direct Java invocations. It is also a critical step in which Oracle SOA Suite compares the server (on which the client composite is deployed) host configuration with the host and port values specified in the reference (target) service endpoint URI. If the host and port values match, it can be concluded that the client and target composites are located on the same server. However, the comparison is not necessarily straightforward given that working with both standalone and clustered server setups and potential load balancer configurations is necessary. Therefore, here are the step-by-step condition checks that determine the correct server configuration on all platforms:

  • Checks the Server URL configuration property value on the SOA Infrastructure Common Properties page, as described in Configuring SOA Infrastructure Properties.

  • If not specified, checks the FrontendHost and FrontendHTTPPort (or FrontendHTTPSPort, if SSL is enabled) configuration property values from the cluster MBeans.

  • If not specified, checks the FrontendHost and FrontendHTTPPort (or FrontendHTTPSPort, if SSL is enabled) configuration property values from the Oracle WebLogic Server MBeans.

  • If not specified, uses the DNS-resolved Inet address of localhost.

  • Checks if the port value specified in the reference service endpoint URL matches the configured server port value. If no port value is specified in the endpoint URL, Oracle SOA Suite assumes 80 for HTTP and 443 for HTTPS URLs.

  • If the port values match, the server URL (that is, http(s)://host:port, where host and port are obtained from the checks mentioned above) is then compared to the server URL in the reference endpoint address. The URLs are resolved to canonical values and the comparison also takes into account the cases in which the endpoint URL host is localhost or 127.0.0.1.

  • Oracle SOA Suite concludes that the composites are co-located if the server URL comparison returns a value of true.

• The security policy configurations, if applied on either or both the client and server composites, must allow for local optimization. For information about policy configurations and local optimization, see Policy Attachments and Local Optimization in Composite-to-Composite Invocations.

You can confirm if a call went over local optimization in the Trace section of the Flow Trace page. The (Local Invocation) text for the reference and service of the invoking and invoked composites is displayed, as shown in Figure 3-1.

Figure 3-1 Local Optimization Details in the Trace Section of the Flow Trace Page

Description of "Figure 3-1 Local Optimization Details in the Trace Section of the Flow Trace Page"

For more information about the Flow Trace page, see Monitoring the Flow Trace of a Business Flow Instance.

Overriding or Forcing Local Optimization

The following configuration properties are provided for either overriding or forcing local optimization.

Property	Description
oracle.webservices.local.optimization	By default, Oracle SOA Suite prefers local optimization. However, you can override this behavior with the oracle.webservices.local.optimization binding property in the composite.xml file. When this property is set to false, local optimization is not performed and cross-composite calls are performed through SOAP and HTTP. Use this property where appropriate. For information about setting this property, see Policy Attachments and Local Optimization in Composite-to-Composite Invocations.
oracle.soa.local.optimization.force	You can override the oracle.webservices.local.optimization property and force optimization to be performed by setting the oracle.soa.local.optimization.force property to true. Use this property in the following scenarios: The server configuration is sufficiently complicated (for example, there are fire wall or proxy settings in an intranet), which may cause the co-location checks described in Condition Checks for Using Local Optimization to not deliver the correct result. You clearly understand the semantics of local optimization, the system setup qualifies for local optimization, and local optimization is absolutely preferred. The oracle.soa.local.optimization.force property has a default value of false. When this property is set to true, Oracle SOA Suite skips the condition checks described in Condition Checks for Using Local Optimization, except for policy configuration checking, which is necessary to ensure and enforce the integrity of service invocations. Another important note about this property is that Oracle SOA Suite always honors the setting of this property (if policy checks allow the optimization). However, if local invocation fails due to nonapplication faults or exceptions (that is, runtime errors mostly related to the direct Java invocation), the value of this setting is ignored for subsequent invocations on the configured endpoint and for all the valid endpoint addresses configured on the endpoint. To enable the oracle.soa.local.optimization.force property: Add oracle.soa.local.optimization.force as a binding component level property in the reference section of the composite being invoked. For example, if composite comp_comp2 invokes comp_comp1, then define this property in the reference section of the composite.xml file of comp_comp2. <reference name="Service1" ui:wsdlLocation="http://localhost:8001/soa-infra/services/default/comp_ comp1!1.0/BPELProcess1.wsdl"> <interface.wsdl interface="http://xmlns.oracle.com/comp_comp/comp_ comp1/BPELProcess1#wsdl.interface(BPELProcess1)" callbackInterface="http://xmlns.oracle.com/comp_ comp/comp_comp1/BPELProcess1#wsdl.interface(BPELProcess1Callback)"/> <binding.ws port="http://xmlns.oracle.com/comp_comp/comp_ comp1/BPELProcess1#wsdl.endpoint(bpelprocess1_client_ep/BPELProcess1_pt)" location="http://localhost:8001/soa-infra/services/default/comp_ comp1!1.0/bpelprocess1_client_ep?WSDL"> <property name="oracle.webservices.local.optimization">false</property> <property name="oracle.soa.local.optimization.force">true</property> </binding.ws> To force local optimization on the reference service callback: Add the oracle.soa.local.optimization.force property to the <callback> element in the <service> definition of the corresponding reference service. For example, if composite1 invokes composite2, add oracle.soa.local.optimization.force property in the <service> definition of compsite2 as follows. This forces the asynchronous callback from composite2 to composite1 to be optimized locally: <service ui:wsdlLocation="composite2.wsdl"> . . . <callback> <binding.ws port="http://xmlns.oracle.com/example#wsdl.endpoint(FooService/FooPort)"> <property name="oracle.soa.local.optimization.force">true</property> </binding.ws> </callback> </service> There can be other scenarios for forcing optimization that are not described in this section.
oracle.soa.local.force.reenable.timemillis Note: This property is available in 12c (12.2.1.4) only if you have installed patch 32690550. Sign in to My Oracle Support and search for the patch number to locate and download the patch.	When this property is set to a value, local optimization will be retried after a failure for the specified amount of time (in milliseconds). The default value is 600000 (10 minutes).

Note:

If both oracle.webservices.local.optimization and oracle.soa.local.optimization.force are set to false, local optimization is not performed.

For information about optimization and WS-AtomicTransaction (WS-AT) transactions, see WS-AT Transactions are Not Supported When Optimization is Enabled in Developing SOA Applications with Oracle SOA Suite.

Local Optimization Logging

Oracle SOA Suite provides NOTIFICATION:1(INFO) level logging for every critical decision made for local optimization versus SOAP processing. For more details or debugging information, set the oracle.integration.platform.blocks.local and oracle.integration.platform.blocks.soap loggers at the TRACE:1(FINE) level in Oracle Enterprise Manager Fusion Middleware Control.

Local Optimization Calls Use Case

This local optimization calls use case describes the following:

• How local optimization calls work in an environment in which composite A calls a co-located composite B on the same server, and composite B is unreachable (Table 3-1).

• What happens when you create a load balancer address with a port value that is not the port on which the Oracle WebLogic Servers are listening (Table 3-2).

Table 3-1 Local Optimization Calls When a Composite is Unreachable

Scenario	Description
What happens when a local optimization call fails?	A check of composite B is performed before trying a local optimization call. If the check fails (composite B is unreachable), an exception is thrown in the SOA Infrastructure that is converted to a BPEL fault. The BPEL fault contains information about composite B being unreachable.
Is it possible to retry the co-located call?	After the basic check is performed, a local optimization call is tried. If that call fails, it is reinvoked over SOAP. However, the following conditions must be met for the reinvocation over SOAP to occur: The oracle.soa.local.optimization.force WS-binding property must be set to true to force local optimization. This condition is provided for backward compatibility. The exception must not be a business exception.
If a retry of the co-located call is possible (for example, the fault policy is set to retry on the composite or endpoint), is the call optimized again or does it attempt to leave the local container and access the load balancer?	If the call fails the first time you attempt to send it locally, the information is cached (that it failed locally). For subsequent calls, the call is sent over SOAP (the local optimization call is not retried this time).

Table 3-2 Creating a Load Balancer Address with a Port Value That is Not the Port on which the Oracle WebLogic Servers are Listening

Scenario	Description
If you want to create a load balancer address with a port value that is not the port on which the Oracle WebLogic Servers are listening, can you specify the server URL (in the SOA Infrastructure Common Properties page) and the frontend host/port (in the Oracle WebLogic Server HTTP tab) as the address of the load balancer?	Yes. The server URL or frontend host/port are more identifiers of the address for the local optimization rules than the actual addresses to which to send network requests.
Does local optimization not use the port to make a call (for example, composite A calling composite B over port 2011)?	Yes, the port is used only to make comparisons to see if the target is co-located, so as to make a local call.

Managing Global Token Variables for Multiple SOA Composite Applications

Configuration plans are composite-specific. Therefore, when you move a SOA composite application from one environment to another, some values require substitution in each configuration plan. To avoid substituting values in each plan, you can define global token variables for specific URIs in SOA composite applications in Oracle Enterprise Manager Fusion Middleware Control.

Global token variables provide the following benefits:

• If multiple SOA composite applications invoke different services hosted on a specific server, you can use a single global token variable to reference this server across the composites. This simplifies development because individual configuration plans are not required; only a single set of token values must be updated. For example, instead of updating the host name of the server in ten different configuration plans, you set the name globally with global token variables. The value is retrieved and replaces the value of the global token variable for the host name in the binding.ws element of the composite.xml file of the deployed SOA composite application.

• Usage of global token variables means that Oracle SOA Suite metadata deployed on the runtime server does not include any environment-specific values.

• In a clustered environment, global token variable changes are made on the administration server and propagated to all managed servers.

The following options for managing global token variables are available:

• Manage (create, edit, and delete) global token variables through the Token Configurations page in Oracle Enterprise Manager Fusion Middleware Control.

• Tokens are only supported for the host, port, and protocol at the ws.binding location and any property under the reference tag.

• Use a predefined global token variable named serverURL.

Note:

• Do not create a token name that contains special characters such as dashes (for example, host-name). During invocation, special characters cause the SOA composite application to fail with a Null Pointer Exception error.

• You can only create tokens used in the composite.xml file.

• The use of global token variables in the import element of the composite.xml file is not supported.

Managing Global Token Variables in the Token Configurations Page

You can manage global token variables on the Token Configurations page. This page enables you to do the following:

• Append variables from a local mdm-url-resolver.xml file to variables from the system's mdm-url-resolver.xml file, and then make appropriate edits.

• Manage variables in the system's mdm-url-resolver.xml file.

To manage global token variables on the Token Configurations page:

1. Access this page through one of the following options:

   From the SOA Infrastructure Menu...	From the SOA Folder in the Navigator...
   Select SOA Administration > Token Configurations.	Right-click soa-infra. Select SOA Administration > Token Configurations.

   The Token Configurations page is displayed.

2. Select the global token variable configuration action to perform:

   To...	Go to Step...
   Select to append variables from a local mdm-url-resolver.xml file to variables from the system's mdm-url-resolver.xml file.	3
   Manage variables in the system's mdm-url-resolver.xml.	4

3. Perform the following steps to append variables from a local file:

   1. Click Bulk Append Tokens.

   2. Click Browse to select the mdm-url-resolver.xml file from the local file system. The local file must adhere to the following format to be successfully uploaded. In this example, global token variables are defined for host name, port, and protocol.

      <?xml version="1.0" encoding="UTF-8"?>
      <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
      <properties>
         <comment>
            URL Resolver file used by the Metadata manager to resolve $<variable>
            in URLs
         </comment>
          <entry key="host">mymachine.us.example.com</entry>
          <entry key="port">8001</entry>
          <entry key="protocol">http</entry>
      </properties> 
      

   3. Click Append.

      The contents of the local file are appended to the contents of the system's mdm-url-resolver.xml file. Global token variables that already exist in the system's mdm-url-resolver.xml file are not overwritten.

   4. If you want to edit the variables, click Modify Configuration File, and go to Step 4.

4. Perform the following steps to manage variables in the system's mdm-url-resolver.xml file:

   1. Click Modify Configuration File.

      If you first selected Bulk Append Tokens and uploaded a file, the global token variables in the local mdm-url-resolver.xml file and the system's mdm-url-resolver.xml file are displayed in a tabular token name and value format. Columns can be sorted either in ascending or descending order. There is no duplication of variables; any variables in the local file that already exist in the system file are not displayed.

      If you first selected Modify Configuration File, the global token variables from the system's mdm-url-resolver.xml file are displayed in a tabular token name and value format.

      
      Description of the illustration global-token-variables.png

   2. Select the global token variable to manage, and perform a specific task.

      Note:

      After making changes, you must click Save before switching to Bulk Append Tokens mode or navigating away from this page. These actions cause uncommitted changes to be lost.

      Element	Description
      	Click to invoke the Add Token dialog for adding a new token name and value. If you attempt to add a token name that already exists, you are prompted with a message asking you to specify a different name. Either enter a different name or close this dialog and click the Edit icon to change the existing name. Click OK to save your changes in the Add Token dialog. Click Save to save your changes in the system's mdm-url-resolver.xml file.
      	Click to invoke the Edit Token dialog for editing a selected token name, value, or both. Click OK to save your changes in the Edit Token dialog. Click Save to save your changes in the system's mdm-url-resolver.xml file.
      	Click to remove an existing token name and value. Click OK to confirm. Click Save to save your changes to the system's mdm-url-resolver.xml file.
      	Click to commit all changes you made to the token configuration. This persists any new, edited, or removed token names and values. This action commits your changes in the system's mdm-url-resolver.xml file.
      	Click to undo all changes you have made since you last clicked Save. Click Yes when prompted to confirm.

   3. Restart the SOA Infrastructure after adding, modifying, or deleting token values. For information, see Stopping and Starting the Managed Server and SOA Infrastructure .

      Your updates are propagated across the cluster.

   4. For information about how global token variables are substituted at runtime, see section How Global Token Variables are Substituted at Runtime.

How Global Token Variables are Substituted at Runtime

Note:

When you deploy a SOA composite application in Oracle Enterprise Manager Fusion Middleware Control that uses global token variables, a warning message is displayed asking you to verify that all tokens are configured in the system's mdm-url-resolver.xml file. For more information, see Deploying SOA Composite Applications.

The token names and the replacement values that you specified in the Token Configurations page are added to the system's mdm-url-resolver.xml file in the following directory:

$MIDDLEWARE_HOME/user_projects/domains/domain_name/config/fmwconfig/
mdm-url-resolver.xml

For example, assume four global token variable names and values are defined through the Token Configurations page.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
   <comment>
      URL Resolver file used by the Metadata manager to resolve $<variable> in
      URLs
    </comment>
    <entry key="myprotocol">http</entry>
    <entry key="myhost">mymachine.us.example.com</entry>
    <entry key="myport">8001</entry>
</properties> 

When the composite.xml for the deployed SOA composite application is loaded during runtime and the resources indicated by URIs within the file are retrieved, any values of global token variables within the URIs are replaced with the values specified in the Token Configurations page.

For example, the following composite.xml file specifies a URI using these tokens in the binding.ws element:

<?xml version="1.0" encoding="UTF-8"?> 
<composite...>
. . .
. . .
<reference name="Service" ui:wsdlLocation="...">
    . . .
    <binding.ws port="..."
     location="${myprotocol}://${myhost}:${myport}/soa-infra/services/default/
      mycomposite/bpelprocess1_client_ep?WSDL" soapVersion="1.1">
    </binding.ws>
</reference>
. . .
</composite>

When the WSDL definition file is retrieved during runtime, the tokens are replaced by the values in the mdm-url-resolver.xml configuration file to create the following URI:

http://mymachine.us.example.com:8001/soa-infra/services/default/myComposite/
 bpelprocess1_client_ep?WSDL

Using Predefined Global Token Variables

You can use a predefined global token variable named serverURL in resource URLs. During runtime, this token is replaced by the setting for the Server URL property of the SOA Infrastructure Common Properties page in Oracle Enterprise Manager Fusion Middleware Control.

To use predefined global token variables:

1. In the Server URL field of the SOA Infrastructure Common Properties page, enter a value (for example, my.host.com:8080). A restart of the server is required when changing this property. Figure 3-2 provides details.

   Figure 3-2 Server URL Field of the SOA Infrastructure Common Properties Page

   
   Description of "Figure 3-2 Server URL Field of the SOA Infrastructure Common Properties Page"
2. Enter the serverURL token in the composite.xml file.

   http://${serverURL}/somePath/someReource.xml
   

   This results in the following URI after the token is replaced during deployment:

   http://my.host.com:8080/somePath/someResource.xml
   

For more information about the Server URL property and the SOA Infrastructure Common Properties page, see Configuring SOA Infrastructure Properties.

Preventing Faults from Building Up in SOA

Resiliency or Circuit Breaker enables you to configure the system to automatically suspend upstream endpoints when a downstream endpoint is down in a SOA composite. This prevents fault buildup in the server and relieves you from having to bulk-recover faulted instances. The upstream endpoints are automatically resumed after the downstream endpoint comes back. For Web Services and REST Services, a new message arriving after the suspension/retry interval brings the service back up.

Note:

This SOA Suite feature is part of Oracle Integration Continuous Availability. Please refer to the Oracle Fusion Middleware Licensing Information for more details on Oracle SOA Suite for Middleware Options.

Enable Resiliency (Circuit Breaker) globally by configuring it at the SOA Infrastructure level. Once enabled, all downstream endpoints are monitored in all composites. If a downstream endpoint experiences errors that exceed the threshold, specified by you in the Resiliency configuration settings, then the upstream endpoints for that downstream endpoint are automatically suspended. So, for example, if a Reference file adapter fails to write to the directory, the upstream web service can be automatically suspended. The system will periodically check if the downstream file adapter is back, and re-enable the web service when the adapter comes back.

The following types of upstream endpoints can be automatically suspended:

• Web Services: Incoming requests are rejected for the duration that the Web service is suspended.

  Starting in 12.2.1.1.0, if the Web Service has multiple operations, then only the operation where the message originated from is suspended.

• REST Services: Starting in 12.2.1.1.0, upstream REST services can be automatically suspended. If the REST Service has multiple operations, then only the operation where the message originated from is suspended.

• Adapters: JMS, AQ, DB, File, Apps, SAP, MQ, UMS, and FTP adapters can be automatically suspended in this release.

• EDN Subscribers: The EDN subscriber closest to the downstream endpoint gets suspended. In the 12.2.1 release, all subscribers in a component (BPEL or Mediator) were suspended when the circuit breaker was triggered. In 12.2.1.1.0, only the subscriber where the message originated from is suspended.

Note:

• A downstream endpoint can have many upstream endpoints. Only upstream endpoints that are actively funneling in data to the downstream endpoint are suspended.

• The circuit breaker and the adapter polling run simultaneously in separate threads. When circuit breaker is triggered, it signals to the adapter polling thread to suspend polling. However, if the adapter has already started a polling cycle when the circuit breaker sends the signal, the adapter continues to process the polled messages. This can result in more errors being generated by downstream endpoints than the number configured in resiliency Failure Rate before the adapter polling thread is suspended. In addition, for the Oracle Database Adapter, add JCA property <property name="AlwaysRollbackOnFailure" value="true"/> to the .jca file generated by Oracle JDeveloper for the adapter to trigger the circuit breaker.

Viewing and Resuming Suspended Services

Services suspended as a result of Resiliency kicking in appear on the SOA Infrastructure Dashboard page, under the Resiliency — Suspended Services section.

The Resiliency settings take care of automatically resuming any suspended service when the downstream endpoint comes back up.

You can click on the Dashboard suspension message to see the details of the suspended service. The details of the resiliency parameters (x errors in y minutes) that triggered the suspension are displayed. The name of the downstream endpoint and the SOA composite are also displayed. You can click Resume to manually resume the service.

The following example shows an upstream Web Service (Mediator1_ep) being suspended, as the downstream endpoint (FileWrite) has failed 2 times in 1 minute.

The following example shows a suspended EDN subscriber. Both the component name and the subscriber details are shown.

Resiliency related messages are also written to the log. You can search for strings like “CircuitBreaker” in the Log Messages page to filter out Resiliency-related messages.

Configuring Resiliency at the Global Level

Use the Resiliency Configuration page to enable or disable resiliency, and to specify global resiliency settings.

1. Under the SOA Infrastructure menu, select SOA Administration > Resiliency Configuration.
   The Resiliency Configuration page appears.Figure 3-3 shows the Resiliency Configuration page.

   Figure 3-3 Resiliency Configuration Page

   
2. Select the Enabled check box to enable resiliency.
   When you enable resiliency, downstream endpoints are monitored for errors, and when these errors exceed the specified threshold, upstream endpoints are automatically suspended.
   The other resiliency configuration parameters, like Failure Rate and Retry Interval, are now enabled.
3. Specify a Failure Rate: Enter the number of errors and the duration in minutes.
   For example, if you specify 10 errors in 5 minutes, then a downstream endpoint failing 10 times in a span of 5 minutes triggers the resiliency feature.
4. Specify a Retry Interval in minutes.
   • If you select Disable Auto Retry, then automatic retries are disabled. You would need to resume the upstream endpoint manually.
   Any suspended upstream endpoint is temporarily re-enabled after every Retry Interval to check if the downstream endpoint is back up. So, if you specify a Retry Interval of 10 minutes, then a suspended upstream endpoint is re-enabled every 10 minutes to check if the downstream endpoint is back up. If the downstream endpoint is still down, then the upstream endpoint is suspended again.

5. Note:

   This step is optional.
   Click Add Notification to configure SMS, e-mail, and IM (instant messaging) notifications for the administrator.
   You can notify the administrator when an upstream endpoint is suspended, or when an endpoint comes back up.
   1. Under Send Notification To, enter the subscriber ID for the administrator.
      The subscriber ID can be an email address, phone number, or IM identifier, depending on the chosen communication channel.
   2. Under Via, select the communication channel.
      You can click Add Notification, identified by the plus sign (+), to add another notification channel.

      You can also click Delete Notification, identified by the red X, to remove an existing notification channel.

6. Note:

   This step is optional.
   Click More Resiliency Configuration Properties to configure additional resiliency properties. See Global Resiliency Properties and Endpoint Resiliency Properties for details on the properties that can be configured.
7. Click Apply on the Resiliency Configuration page to save your changes.
   • If you click Revert, then all changes made to this page are reverted.

You have now enabled resiliency at the global level.

Overriding Global Resiliency Settings for a Downstream Endpoint

You can tweak the resiliency settings for a downstream endpoint, and these settings will override the global Resiliency settings for that endpoint.

For example, if you do not wish to monitor a downstream file adapter for write failures, you can disable resiliency for that particular adapter. Use the following steps to configure the resiliency settings for a downstream endpoint in Oracle Enterprise Manager Fusion Middleware Control:

1. From the SOA Composite page for the composite containing the endpoint, click the endpoint name under Services and References.
   For example, if you are tweaking resiliency settings for a file adapter, click the name of the file adapter under Services and References.
   The dashboard for the endpoint appears.
2. Click Properties to switch to the Properties tab.
   A list of properties appears for the component.
3. If you cannot see the Resiliency properties, click the Add button identified by the plus (+) sign.
   See Global Resiliency Properties and Endpoint Resiliency Properties for the list of available Resiliency properties.
4. Modify the values for the properties that you wish to change.

Note:

You can also override the resiliency properties for a downstream endpoint in JDeveloper.

Global Resiliency Properties and Endpoint Resiliency Properties

You can modify the ResiliencyConfig MBean attribute in the System MBean Browser to globally set advanced configuration properties for Resiliency. You can also modify the properties for a Reference endpoint to override the global Resiliency settings for the endpoint.

Table 3-3 ResiliencyConfig MBean Attribute Keys and Endpoint Properties

MBean Key	Reference Endpoint Property	Description
circuitBreakerEnabled	circuitbreaker.disabled	Enables or disables Resiliency.
failureRate	circuitbreaker.failure.rate	The threshold count of errors that trigger Resiliency.
failureRateTime	circuitbreaker.failure.rate.time	The time window within which the errors (failureRate) should occur for Resiliency to kick in.
resiliencyNotificationConfigList		The list of email addresses, phone numbers, and IM identifiers to notify when an upstream endpoint is suspended, or when an upstream endpoint is resumed.
resumeInitialDelay	circuitbreaker.resume.initial.delay	The time duration, in ms (milliseconds), to wait between processing successive messages when resuming an endpoint. This guards against failure buildup in case the downstream endpoint goes down again.
resumeRampupTime	circuitbreaker.resume.rampup.time	The time duration, in minutes, after which the initial delay is reduced to 0. This equates to the time duration after which you are reasonably confident that the downstream endpoint is up, and the system can start pumping messages without delay. The initial delay is adjusted every 5 minutes.
retryTimeInterval	circuitbreaker.retry.interval property for a Reference endpoint.	Periodic interval, in minutes, at which the downstream endpoint is tested by temporarily re-enabling the upstream endpoint, and letting trickle messages through.

You can set the above properties for composite references in JDeveloper by selecting the reference in the composite and clicking the Add button under the Composite Bindings section.