This chapter describes how to configure the properties of the SOA Infrastructure, including audit levels, composite instance states, and payload validation. These property settings can apply to all SOA composite applications running in the SOA Infrastructure. It also describes how to configure local optimization, stop and start the managed server and SOA Infrastructure, and create global token variables.
This chapter includes the following sections:
Section 3.2, "Stopping and Starting the Managed Server and SOA Infrastructure"
Section 3.3, "Changing the SOA Infrastructure Server URL Property Port in the System MBean Browser"
Section 3.5, "Changing the Driver Name to Support Custom XA Drivers"
Section 3.6, "Specifying a Nondefault XA Transaction Timeout Value for XA Data Sources"
Section 3.8, "Managing Global Token Variables for Multiple SOA Composite Applications"
For more information, see Section 1.2.1, "Introduction to the SOA Infrastructure Application."
You can configure the following properties for the SOA Infrastructure:
Audit level
Composite instance state to capture
Payload validation
Universal Description, Discovery, and Integration (UDDI) registry
Callback server and server URLs
Display of recent instances, faults, and count metrics on pages
Search criteria for the retrieval of recent instances and faults
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.
To configure SOA Infrastructure properties:
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... |
---|---|---|
|
|
|
The SOA Infrastructure Common Properties page displays the following properties.
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.
Descriptions for the properties at the top of the page are provided in the following table.
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.
For more information about reducing the audit level for SOA composite applications and the data written to the Oracle SOA Suite schema, see Section B.2.3, "Reducing Audit Levels." |
Capture Composite Instance State |
Select to capture the SOA composite application instance state. Enabling this option may result in additional runtime overhead during instance processing. This option provides for separate tracking of the running instances. All instances are captured as either running or not running. This information appears later in the State column of the composite instances tables for the SOA Infrastructure and SOA composite application, where:
Valid states are running, completed, faulted, recovery needed, stale, terminated, and state not available. The running and completed states are captured only if this checkbox is selected. Otherwise, the state is set to unknown. The conditional capturing of these states is done mainly to reduce the performance overhead on SOA Infrastructure runtime. Note: If this property is disabled and you create a new instance of a SOA composite application, a new instance is created. However, the instance does not display as running, faulted, stale, terminated, completed, or requiring recovery in the Dashboard page table of the composite application. This is because capturing the composite state of instances is a performance-intensive process. For example, if you enable this property and create a SOA composite application instance in the Test Web Service page, a new instance appears in the Dashboard page of the composite application. If you click Show Only Running Instances in the Dashboard page, the instance is displayed as running. If you then disable this property and create another instance of the same composite application, a new, running instance is created. However, if you then select Show Only Running Instances, the new instance is not listed in the running instances table. In addition, to terminate a running instance, the instance must have a state (for example, running, faulted, and so on). This activates the Abort button on the Instances page of a SOA composite application. If this checkbox is not enabled before creating an instance, the Abort button is inactive, and you cannot terminate the instance. For more information about reducing the audit level by disabling instance state tracking, see Section B.2.3, "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. |
Make changes appropriate to your environment.
The UDDI Registry Properties section displays the following 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.
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. |
|
User |
Enter the registry inquiry user. |
|
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 Section 36.1.3, "Changing the Endpoint Reference and Service Key for Oracle Service Registry Integration."
Make changes appropriate to your environment.
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.
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 |
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: In 10.1.x releases, you manually configured SOAP optimization with the For information about local optimization, see Section 3.7, "Configuring Local Optimization." |
Make changes appropriate to your environment.
The Data Display Options section displays the following properties for improving the time it takes to load pages.
Note:
Any changes to these properties impact all SOA farms associated with this Oracle Enterprise Manager instance.
Element | Description |
---|---|
Disable fetching of instance and fault count metrics. Each metric can still be retrieved on demand. |
Select to disable the display of instance and fault count metrics on the Dashboard pages of the SOA Infrastructure, SOA composite applications, service engines, and service components. Instead, these metrics are replaced with links that you click to retrieve the instance and fault count metrics when you need this information. This setting can improve the time it takes to load pages. If you click a link to retrieve instance and fault count metrics, and Oracle Enterprise Manager Fusion Middleware Control times out, increase the transaction timeout property. For more information, see Section B.3.1, "Resolving Connection Timeouts" and Section B.7.1, "Optimizing the Loading of Pages with Instance and Fault Metrics." |
Restrict display of instances and faults to the last time_period |
Select this checkbox and specify a time period during which to retrieve recent instances, faults, and count metrics for display on the following pages:
By default, this checkbox is selected and the time period duration is set to 24 hours (one day). If this checkbox is not selected, all instances and faults (including count metrics) in the SOA Infrastructure since the last purging are displayed. 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. The time period you specify appears by default in the Fault Time From field on faults pages on which you can search for faults and the Start Time From field on instances pages on which you can search for instances. |
For additional details, see Section B.7.1, "Optimizing the Loading of Pages with Instance and Fault Metrics."
Expand the Advanced section.
The Data Sources section displays the following properties. A data source enables you to retrieve a connection to a database server.
Make changes appropriate to your environment.
The Web Service Binding Properties section displays the following options.
Make changes appropriate to your environment.
Click Apply.
If you make changes and want to reset these properties to their previous values, click Revert.
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 keys:
bpelRecoveryStatus key: If there are BPEL messages requiring recovery in the Recovery page of the BPEL process service engine, this setting enables a BPEL Message Recovery Required inline warning message and recovery icon to display in the Trace table of the Flow Trace page and at the top of the home pages of the SOA Infrastructure and SOA composite applications. By default, this key is set to All. If this key is set to Off, no message recovery information is displayed. For more information, see the following sections:
- Section 4.3, "Monitoring SOA Infrastructure Recent Instances and Faults and Deployed Composites"
- Section 14.1, "Monitoring the Audit Trail and Process Flow of a BPEL Process Service Component"
excludeBpelMaxCreationTime key: Enables you to set the time period for excluding messages that require recovery. For more information, see Section 4.3, "Monitoring SOA Infrastructure Recent Instances and Faults and Deployed Composites."
bpelRecoveryAlertDurationInDays key: Limits the BPEL Message Recovery Required inline warning message to be displayed only when recoverable BPEL messages have been created in the last seven days. The default setting of seven days can be changed. You cannot set this property to negative values such as -1
or to 0
. In such cases, the key uses its default value (seven days). To disable the alert message, use the bpelRecoveryStatus key. The duration value is not applicable to the flow trace alert message.
CreateWSCallTrackingMBean: Controls the creation of a 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 Section 12.5, "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.
HttpProxyPassword: The password for HTTP proxies that require authentication.
HttpProxyUsername: The user name for HTTP proxies that require authentication.
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.
As described in Section 3.1, "Configuring SOA Infrastructure Properties," you can disable the retrieval of instance and fault count metrics in the Data Display Options section of the SOA Infrastructure Common Properties page. You can also change this property through the System MBean Browser.
To disable instance and fault count metrics retrieval with the System MBean Browser.
Select Application Defined MBeans > emom.props > Server:AdminServer > Application: em > Properties > emoms.properties.
Note that emoms.properties is only available for selection if you previously modified the Disable fetching of instance and fault count metrics option of the Data Display Options section of the SOA Infrastructure Common Properties page.
In the Name column of the Attributes tab, click Properties.
In the Value column, expand Element_20.
In the Element column, enter false
to disable metrics retrieval.
Click Apply.
Restart the SOA Infrastructure. A restart is not required if you instead change the Disable fetching of instance and fault count metrics option through the Data Display Options section of the SOA Infrastructure Common Properties page.
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.
Notes:
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 Section B.8, "Server Troubleshooting."
To stop and start the managed server and SOA Infrastructure:
Access this page through one of the following options:
From the WebLogic Server Menu... | From the WebLogic Domain Folder in the Navigator... |
---|---|
|
|
To shut down the managed server and SOA Infrastructure, select Shut Down.
Click OK when prompted to shut down the managed server and SOA Infrastructure.
Wait for shutdown to complete.
To start the managed server and SOA Infrastructure, select Start Up.
For information on stopping and starting managed servers with Node Manager, see Oracle Fusion Middleware Node Manager Administrator's Guide for Oracle WebLogic Server.
For information on starting and stopping managed servers with WLST commands, see Oracle Fusion Middleware Administrator's Guide.
After the SOA Infrastructure is started, it may not be completely initialized to administer incoming requests until all deployed composites are loaded. Therefore, the response metrics that are displayed on some Oracle Enterprise Manager Fusion Middleware Control pages may not reflect their actual status. This is most apparent when the SOA Infrastructure is in a cluster with multiple managed servers and a large number of deployed composites.
During the initialization stage, Oracle Enterprise Manager Fusion Middleware Control does not prevent you from executing operations such as composite deployment, composite undeployment, and others, even though these operations may not complete successfully. Instead, a warning message is displayed at the top of the Oracle Enterprise Manager Fusion Middleware Control pages shown in Table 3-1. Do not perform operations such as composite deployment, composite undeployment, and others while this message is displayed. Once initialization completes, the message is no longer displayed. You see this after you refresh the page. You can then perform operations.
Table 3-1 SOA Infrastructure Initialization Message
This Warning Message Is Displayed... | At the Top of These Pages... |
---|---|
Initializing SOA Even though the soa-infra target is up, some SOA Fabric components and composite applications are still loading. You may need to allow some time for the initialization to complete, and later click the Refresh Page icon. It is not adivsable to execute any operations on this soa-infra until this warning goes away. |
|
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://152.61.150.106: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.
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.
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.
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.
Restart the SOA Infrastructure.
In addition to the SOA Infrastructure Common Properties page described in Section 3.1, "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:
From the SOA Infrastructure menu, select Administration > System MBean Browser.
Under Application Defined MBeans, expand oracle.as.soainfra.config > Server: server_soa > SoaInfraConfig > soa-infra.
where server_soa is the name of the server provided during post installation configuration. By default, this name is soa_server1.
In the Name column, click ServerURL.
The Attribute: ServerURL page appears.
In the Value field, change the port.
Click Apply.
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 Oracle Fusion Middleware Enterprise Deployment Guide for Oracle SOA Suite.
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:
Access this page through one of the following options:
From the SOA Infrastructure Menu... | From the SOA Folder in the Navigator... |
---|---|
|
|
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.
Perform the following log file tasks on this page:
In the Logger Name column, expand a logger name. This action enables you to specify more specific logging levels within a component.
In the Oracle Diagnostic Logging Level columns, select the level and type of information to write to a log file.
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 Oracle Fusion Middleware Administrator's Guide.
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.
For information on setting logging levels and Oracle SOA Suite logging files to view, see Section B.1, "Setting Logging Levels for Troubleshooting."
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 o
racle-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 Oracle Fusion Middleware Administrator's Guide.
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:
Access this page through one of the following options:
From the SOA Infrastructure Menu... | From the SOA Folder in the Navigator... |
---|---|
|
|
The Log Configuration page is displayed.
In the Logger Name column, expand oracle.soa > oracle.soa.sql.trc.fabric.
Set the logging level to FINE.
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
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.
Log in to Oracle WebLogic Server Administration Console.
In the left pane, select Domain Structure.
Select Services > JDBC > Data Source > SOADataSource > Connection Pool.
For the Driver Class Name, change the value to a custom data source (for example, oracle.jdbc.xa.client.myDataSource
.
Restart the server.
Edit the soaDataSource-jdbc.xml
file.
Open the soaDataSource-jdbc.xml
file on Oracle WebLogic Server.
Change the SOADataSource
driver name from oracle.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:co0yd570</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>
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:
Log in to Oracle WebLogic Server Administration Console.
Under Domain Structure on the left side of the page, select Services > JDBC > Data Sources.
In the Name column of the Data Sources table, select EDNDataSource (for event delivery network transactions) or SOADataSource (for all other types of transactions).
Under the Configuration tab at the top, click the Transaction subtab.
In the XA Transaction Timeout field, enter a value in seconds.
Select the Set XA Transaction Timeout checkbox. You must select this checkbox for the new XA transaction timeout value to take effect.
Click Save.
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.
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 Section 3.1, "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 Section 7.7.2, "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
For more information about the Flow Trace page, see Section 14.1, "Monitoring the Audit Trail and Process Flow of a BPEL Process Service Component."
Two configuration properties are provided for either overriding or forcing local optimization.
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 Section 7.7.2, "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 Section 3.7.1, "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.
There can be other scenarios for forcing optimization that are not described in this section.
Note:
If oracle.webservices.local.optimization
is set to false
and oracle.soa.local.optimization.force
is set to false
, local optimization is not performed.
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 Section 3.7.1, "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 to force 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>
For information about optimization and WS-AtomicTransaction (WS-AT) transactions, see Section "WS-AT Transactions are Not Supported When Optimization is Enabled" of Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
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.
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-2).
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-3).
Table 3-2 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:
|
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-3 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 |
Yes, the port is used only to make comparisons to see if the target is co-located, so as to make a local call. |
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
.
Notes:
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.
You can manage global token variables on the Token Configuration 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 token variables on the Token Configurations page:
Access this page through one of the following options:
From the SOA Infrastructure Menu... | From the SOA Folder in the Navigator... |
---|---|
|
|
The Token Configurations page is displayed.
Select the global token variable configuration action to perform:
Perform the following steps to append variables from a local file:
Click Bulk Append Tokens.
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>
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.
If you want to edit the variables, click Modify Configuration File, and go to Step 5.
Perform the following steps to manage variables in the system's mdm-url-resolver.xml
file:
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. 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.
Select the global token variable to manage, and perform a specific task.
Note:
After making changes, you must click Commit before switching to Bulk Append Tokens mode or navigating away from this page. These actions cause uncommitted changes to be lost.
Element | Description |
---|---|
|
|
|
|
|
|
|
|
|
Restart the SOA Infrastructure after adding, modifying, or deleting token values. For information, see Section 3.2, "Stopping and Starting the Managed Server and SOA Infrastructure."
Your updates are propagated across the cluster.
For information about how global token variables are substituted at runtime, see section Section 3.8.2, "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 Section 7.1, "Deploying SOA Composite Applications."
The token names and the replacement values that you specified in the Token Configuration 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 were defined through the Token Configuration 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 Configuration 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
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:
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
Enter the serverURL
token in the composite.xml
file.
${serverURL}/somePath/someResource.xml
The serverURL
token includes the protocol (http
or, if SSL is enabled, https
).
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 Section 3.1, "Configuring SOA Infrastructure Properties."