This chapter includes the following sections:
You can test and debug SOA composite applications with the SOA debugger in Oracle JDeveloper. The SOA debugger reduces the development cycle for a SOA composite application by providing a troubleshooting environment within Oracle JDeveloper. This eliminates the lengthy process of building a SOA composite application in Oracle JDeveloper, deploying it to the SOA Infrastructure, starting Oracle Enterprise Manager Fusion Middleware Control to test or view audit trails and flow traces, and then returning to Oracle JDeveloper to repeat the exercise. Instead, you can set breakpoints in Oracle JDeveloper for troubleshooting on the following components:
Binding components and service components in SOA composite applications
Synchronous and asynchronous BPEL processes
Oracle BPM processes
Oracle Service Bus pipelines (See Section "Debugging Oracle Service Bus Applications" of Developing Services with Oracle Service Bus)
Note the following guidelines when using the SOA debugger:
The SOA composite application name and the Oracle JDeveloper project name must be the same.
Any SOA composite application encountered during a debugging session must reside in the currently active workspace in Oracle JDeveloper.
Debugging is limited to design view in Oracle JDeveloper. You cannot run the SOA debugger in Oracle Enterprise Manager Fusion Middleware Control.
Debugging is a localized user experience. If you want to switch to other tasks (for example, search for instances or initiate new instances of the same composite from Oracle Enterprise Manager Fusion Middleware Control), close the debugging session.
You cannot set breakpoints on REST services.
The breakpoints that you create for debugging in a SOA composite application in one installation of Oracle JDeveloper are not available to other Oracle JDeveloper installations. You must create the breakpoints again for debugging.
During a debugging session in which you are using the embedded Integrated WebLogic Server, you cannot use the version of Oracle Enterprise Manager Fusion Middleware Control included with the embedded server to generate new instances or query instances. For information about the Integrated WebLogic Server, see Installing SOA Suite and Business Process Management Suite Quick Start for Developers.
You cannot debug cross-language features, such as a Java
exec activity, XSLT and XQuery transformations, and so on.
You can debug SOA composite applications on servers on which Oracle SOA Suite is installed. For example, if Oracle SOA Suite runs on managed servers, clients must connect using the managed server host and port.
Only one client at a time can connect to the SOA debugger.
You cannot debug multiple instances of the same SOA composite application at a given time even though Oracle JDeveloper does not restrict you from this action. This is not the correct approach. The SOA debugger is a development tool. It is your responsibility to ensure that only a single instance is debugged at any given time.
Adapter endpoint errors are not displayed in the SOA debugger in Oracle JDeveloper. Those errors are logged in the log file.
You can only debug if the server is in development mode. Debugging in production mode is not supported.
Oracle B2B and Oracle SOA for Healthcare service and reference binding components cannot be debugged with the SOA debugger even though you can set debugging points on both components.
SOA composite application-to-SOA composite application debugging is not supported.
This section describes how to create breakpoints and debug SOA composite applications in Oracle JDeveloper.
Do not attempt to debug SOA composite applications with very large payloads. Attempting to do so results in the SOA debugger breakpoints hanging in the outbound direction.
To start the SOA debugger:
Start the Integrated WebLogic Server. For information about starting the Integrated WebLogic Server with the Start Server Instance option, see Section "Installing Oracle SOA Suite Quick Start for Developers" of Installing SOA Suite and Business Process Management Suite Quick Start for Developers.
Start the SOA debugger in either of the following ways. This is limited to single composite debugging.
Click the debugger icon above the SOA Composite Editor, as shown in Figure 49-1.
Figure 49-1 Debugger Icon in SOA Composite Editor
Right-click the SOA composite application in the Applications window, and select Debug. Figure 49-2 provides details.
Figure 49-2 Debug Menu Option for a SOA Composite Application in the Applications Window
The SOA Debugger Connection Settings dialog is displayed, as shown in Figure 49-3. This dialog enables you to define the SOA debugging server to use.
Figure 49-3 SOA Debugger Connection Settings Dialog
Enter values appropriate to your environment, and click OK. Table 49-1 provides details.
Table 49-1 SOA Debugger Connection Setting Dialog
Select the debugging server to which to connect. By default, the name of the local host is displayed. This is the embedded Integrated WebLogic Server in Oracle JDeveloper. You can also enter a remote server. When a project is imported from a different host, the host that was used there is displayed here.
Enter the port on which the debugging agent listens. The default value is
export SOA_DEBUG_FLAG="true" export SOA_DEBUG_PORT="5004"
Specify in minutes how long the client should wait while attempting to establish a debugging session before stopping. The default value is
Skip this dialog next time
Select to skip this dialog the next time you begin a debugger session. The settings you previously defined are used.
You can display this dialog again by right-clicking the project in the Applications window. Select Project Properties > Run/Debug > Edit > Tool Settings > Debugger > Remote, and select the Show Dialog Box Before Connecting Debugger check box.
You can also edit these properties by right-clicking the project in the Applications window, and selecting Project Properties > Run/Debug > Edit > Tool Settings > Debugger > Remote.
A check is made to determine if the SOA composite application selected for debugging is deployed. Table 49-2 provides details.
Table 49-2 Check to Determine if the SOA Composite Application is Deployed
|If the SOA Composite Application Is...||Then...|
The following message is displayed on the right handle of the service binding component:
Use context menu to initiate WS debugging
See Figure 49-5 for an example of this message.
You are ready to begin debugging. Go to How to Set Breakpoints and Initiate Debugging.
The Deployment Action page of the Deploy Project_Name wizard is displayed, and you must deploy the composite.
You are ready to begin a debugging session when the following message is displayed in the Log window:
Debugger attempting to connect to remote process at host_name 5004 Debugger connected to remote process at host_name 5004 Debugger process virtual machine is SOA Debugger.
Breakpoints are the intentional pausing locations in a SOA composite application that you set for debugging purposes. You can set breakpoints on the following components:
Service binding components
Inbound and outbound parts of BPEL process activities and BPM process service components
Reference binding components such as web services and JCA adapters
Oracle Service Bus services (see "Debugging Oracle Service Bus Applications" of Developing Services with Oracle Service Bus)
Components on which breakpoints are set are designated with red request (outbound) icons, reply (inbound) icons, or request-reply (outbound-inbound) icons. Figure 49-4 provides an example of a SOA composite application in which breakpoint icons have been set.
Figure 49-4 SOA Composite Application with Breakpoints Set
To set breakpoints and initiate debugging:
Select the component on which to set the breakpoint, as shown in Table 49-3.
To set a breakpoint on a service binding component.
Right-click the right handle of the service on which the following message is displayed.
Use context menu to initiate WS debugging
This action invokes the context menu shown in Figure 49-5.
Figure 49-5 SOA Debugger Breakpoint Menu Options
Select the appropriate breakpoint interaction option shown in Table 49-4.
Table 49-4 Breakpoint Interaction Options
Create Breakpoints Pair
Set for a request-reply (outbound-inbound) interaction. This is useful for scenarios in which both the request and reply are important.
Create Request Breakpoint
Set for a request (outbound) interaction. This is useful for scenarios in which only the request is important.
Create Reply Breakpoint
Set for a reply (inbound) interaction. This is useful for scenarios in which only the reply is important.
Initiate WS Debugging
Initiate a debugging session. For example, the debugging session encompasses an initiating SOAP request from a web service to a BPEL process to an adapter reference binding component.
Red icons representing your interaction choice are added.
For example, if you select Create Breakpoints Pair, request and reply breakpoint icons are added. Figure 49-6 provides details.
Figure 49-6 Request and Reply Breakpoint Icons on a Service Binding Component
Go to Step 5.
To set a breakpoint on a reference binding component.
Right-click the applicable reference binding component (for example, a web service or a database adapter), and select one of the breakpoint options described in Table 49-4.
For example, if you select Create Breakpoints Pair for several references, request and reply breakpoint icons are added. Figure 49-7 provides details.
Figure 49-7 Breakpoints Set on Reference Binding Components
Go to Step 5.
To set a breakpoint on a service component (for this example, a BPEL process is selected).
Select Edit, as shown in Figure 49-8.
Figure 49-8 Request and Reply Breakpoint Icons on a BPEL Process
This opens the BPEL process in Oracle BPEL Designer.
Right-click the BPEL activity on which to set a breakpoint, and select Toggle Breakpoint. Figure 49-9 provides details.
Figure 49-9 Breakpoint Setting for a BPEL Process
An icon is added to the activity. These breakpoint icons are only red dots because the flow is always in one direction. It is recommended that you always set a breakpoint on the first activity within an asynchronous BPEL process.
To disable the breakpoint, right-click and select Toggle Breakpoint again. The red dot is removed. To display a list of all breakpoints set in the BPEL process, right-click the activity and select Breakpoints. You can also enable and disable breakpoints from this dialog.
Go to Step 5.
To begin debugging of the SOA composite application, right-click the right handle of the service binding component shown in Figure 49-5, and select Initiate WS Debugging from the menu.
This invokes the HTTP Analyzer.
Enter the request message data to send, and click Send Request or click HTTP Content to copy and paste the contents from an XML file. You can either enter data field-by-field or copy and paste an XML document. Figure 49-10 provides details.
Figure 49-10 SOA Debugger Message Data
The debugger stops at the first breakpoint you set (for this example, on the service binding component).
In the Log window at the bottom of Oracle JDeveloper, click Data.
Expand the message contents. Figure 49-11 provides details. You can double-click a value to change it. For non-XML variables, right-click and choose View value (for example, the return message from a database adapter).
Figure 49-11 Message Contents After Debugger Invocation
When you create a breakpoint, a corresponding frame is created in the Structure window, as shown in Figure 49-12. This frame was created for the request-reply entry point on the service binding component.
A frame is a location. A stack of frames is a bread crumb trail of the locations that lead you to your current location. This is equivalent to a stack trace. It shows you where you are and how you got there. Frames are created independent of breakpoints. When you stop at a breakpoint, all frames that have been created in the Structure window are displayed. A stack frame also contains the data that existed at that point of time. Clicking a different stack frame in the Structure pane also updates the Data tab.
For example, if you have a web service connected to a BPEL process connected to a reference, if you set a breakpoint on the reference, you see a stack that generally looks as follows:
If you click the web service frame, the SOAP payload in the Data tab is displayed. If you then click the BPEL invoke frame, the various BPEL variables and other details are displayed in the Data tab.
You can step over the frame and begin debugging at a different location, such as a different breakpoint (for this example, the LoanProcess BPEL process). As you proceed with debugging, the following frames are created. Frames are where variables are located.
Scope frame: Contains scope variables.
Process frame: Contains global variables.
Variables are visible to a process from the top frame through the bottom frame. Frames are displayed in the Structure window.
Figure 49-12 Frames in Structure Window
To step through a debugging session:
Figure 49-13 Step Options in Oracle JDeveloper
Table 49-5 describes each option.
Table 49-5 Step Options in Oracle JDeveloper Main Menu
Ends or detaches from a debugging session.
Steps over a frame.
This places you at the next breakpoint (for example, the receive activity in the BPEL process on which a breakpoint was set in Figure 49-9). If there are no breakpoints, it steps over all the frames and goes back to the first frame.
You can also press F8 to step over a frame.
Steps into the next valid location.
This can be a new frame or the same frame, but in a different location.
You can also press F7 to step into a frame.
Steps out of a frame.
This option is only used to process a BPEL scope or sequence activity. After completion of scope processing, it pauses at the next scope or activity in the process. You can also press Shift-F7.
Resumes a step operation.
You can also press F9 to resume.
Figure 49-14 Empty Payload
This is because the breakpoint on the receive activity has not been executed, as shown in Figure 49-15.
Figure 49-15 Empty Payload Before Receive Activity Breakpoint Execution
This executes the receive activity shown in Figure 49-16.
Figure 49-16 Populated Payload After Receive Activity Breakpoint Execution
The contents of the request message to the web service call are shown in Figure 49-18.
Figure 49-18 Request Message Payload Contents
Figure 49-19 Request Message Payload Contents
If you step through the copy rules of an assign activity, the SOA debugger displays a window showing which copy rule it is on within the assign activity. The window has a table showing all the copy rules and there is a breakpoint icon next to the copy rule at which the debugger is stopped.
If you set a breakpoint on an adapter (for example, a database adapter), the SOA debugger steps out of the BPEL process service component and goes to the SOA Composite Editor.
To end or detach from a debugging session:
Figure 49-20 End or Detach from a Debugging Session
The Terminate Debugger Process dialog is displayed.
Table 49-6 Breakpoint Menu Options
Removes the debugger without ending the debugging process.
Ends the debugging process.
You can remove individual breakpoints or all breakpoints.
To remove breakpoints:
Right-click an activity on which a breakpoint has been set and select Toggle Breakpoint.
Click the Breakpoints icon above Oracle BPEL Designer and select the activity on which to remove a breakpoint in the Breakpoints dialog.
Figure 49-21 Breakpoints Icon in Oracle BPEL Designer
This invokes the Breakpoints dialog, as shown in Figure 49-22.
Figure 49-22 Breakpoints Dialog
You can view adapter properties under the Data tab in the Log window.
To view adapter properties:
Figure 49-23 JCA Adapter Properties
The process is stopped to check on the existence of the customer. Adapter endpoint properties are displayed. Figure 49-24 provides details. The SQL syntax to be executed is also displayed.
Figure 49-24 Adapter Output
Figure 49-25 Request Message Contents Being Passed
Figure 49-26 Reply Message Contents Being Returned
A process instance is always run by a single logical thread, whether it is a synchronous or asynchronous process (the process ID can be thought of as the thread). The SOA debugger sees and uses the logical thread. If a process has a flow or flowN activity, then several logical threads run the flow or flowN activity.
To view threads:
The Threads tab is displayed in the Structure window.
The thread value for the request is 40, as shown in the Structure window in Figure 49-27.
Figure 49-27 Request Thread Value
You can test HTTP requests and responses in a SOA composite application with the HTTP Analyzer in Oracle JDeveloper. The HTTP Analyzer enables you to examine the content of HTTP request/response package pairs. You can edit the content of a request package, resend it, and observe the response packet returned. For more information about the HTTP Analyzer, see the "Auditing and Monitoring Java Projects" chapter of Developing Applications with Oracle JDeveloper.
To test the SOA composite application with the HTTP Analyzer:
Figure 49-29 Component to Test in the Application Servers Window
The HTTP Analyzer is displayed.
Figure 49-30 HTTP Analyzer
If successful, output similar to that shown in Figure 49-31 is displayed in the right pane.
Figure 49-31 Response HTTP Headers
You can also use the Test Web Service page to perform testing. For more information, see Section "Initiating a Test Instance of a Business Flow" of Administering Oracle SOA Suite and Oracle Business Process Management Suite.
Audit trail data often accounts for a large percentage of the state data persisted to the database. To reduce the amount of persisted state data, you can specify finer-grained levels of auditing at the BPEL process activity level. These settings take precedence over the audit trail settings configured at the service component, SOA composite application, BPEL process service engine, and SOA Infrastructure levels.
You perform the following procedures:
Create and configure an audit policy XML file that defines the level of auditing to perform on BPEL activities in the SOA composite application.
Create and configure an audit policy binding XML file that binds the audit policy to the BPEL process.
Place the files in the same directory location as the
composite.xml file or in a separate directory that you identify with properties in the
Deploy the SOA composite application to the SOA Infrastructure.
View the audit trail of the BPEL process activities in the flow trace of the SOA composite application in Oracle Enterprise Manager Fusion Middleware Control.
Note the following guidelines:
The audit policy supports the auditing of both standard BPEL 1.1 and 2.0 activities and scopes and BPEL extension activities, such as emails, notifications, and all others. Within a parent scope, you can configure specific child scopes to be audited, and other child scopes to not be audited.
The supported auditing levels are shown in Table 49-7.
Table 49-7 Auditing Levels
Logging matches the SOA Infrastructure audit level that you set on the SOA Infrastructure Common Properties page in Oracle Enterprise Manager Fusion Middleware Control. This is the default setting.
Minimal information for business flow instances is collected. For example, the BPEL process service engine does not capture the payload. Therefore, the payload details are not available in the flow audit trails. This level is optimal for most standard operations and testing.
Complete information for BPEL process activities is collected. This option allows both composite instance tracking and payload tracking. This setting may have an impact on performance because the payload is stored at each step in the message flow. This setting is useful for debugging purposes.
No logging is performed. Composite instance tracking information and payload tracking information are not collected.
Support is provided for wild-card matching of process names and revision numbers in the fault policy binding file. For example:
Order* applies to BPEL process service components included in the composite named
<process auditPolicy="noLoops" name="Order*"/>
1* applies to composite revisions
<process auditPolicy="noAssign" name="*" revision="1.*"/>
The following example shows the audit policy schema to use:
<?xml version="1.0" encoding="UTF-8"?> <xs:schema targetNamespace="http://schemas.oracle.com/bpel/auditpolicy" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://schemas.oracle.com/bpel/auditpolicy" elementFormDefault="qualified"> <!-- activity can have a type or a name as optional attribute.--> <!-- Audit rules apply to all activities if no specific type or name is --> <!-- provided --> <xs:complexType name="Activity"> <xs:attribute name="type" type="xs:QName" use="optional"/> <xs:attribute name="name" type="tns:idType" use="optional"/> <xs:attribute name="auditLevel" type="tns:auditLevelType" use="required"/> </xs:complexType> <xs:simpleType name="idType"> <xs:restriction base="xs:string"> <xs:minLength value="1"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="auditLevelType"> <xs:restriction base="xs:string"> <xs:enumeration value="off"/> <xs:enumeration value="minimal"/> <xs:enumeration value="production"/> <xs:enumeration value="development"/> </xs:restriction> </xs:simpleType> <xs:element name="auditPolicy"> <xs:complexType> <xs:sequence> <xs:element name="activity" type="tns:Activity" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <xs:attribute name="id" type="tns:idType" use="required"/> <xs:attribute name="version" type="xs:string" default="1.0"/> </xs:complexType> <!-- we restrict users to provide mulitple rules for same activity --> <xs:key name="UniqueActivity"> <xs:selector xpath="tns:activity"/> <xs:field xpath="@type"/> <xs:field xpath="@name"/> </xs:key> </xs:element> </xs:schema>
The following example shows the audit policy binding schema to use.
<?xml version="1.0" encoding="UTF-8"?> <xs:schema targetNamespace="http://schemas.oracle.com/bpel/auditpolicyBinding" xmlns:tns="http://schemas.oracle.com/bpel/auditpolicy" xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"> <xs:complexType name="Process"> <xs:attribute name="auditPolicyId" type="tns:idType" use="optional"/> <xs:attribute name="name" type="tns:idType" use="optional"/> <xs:attribute name="revision" type="tns:idType" use="optional"/> </xs:complexType> <xs:simpleType name="idType"> <xs:restriction base="xs:string"> <xs:minLength value="1"/> </xs:restriction> </xs:simpleType> <xs:element name="auditPolicyBinding"> <xs:complexType> <xs:sequence> <xs:element name="process" type="tns:Process" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <xs:attribute name="version" type="xs:string" default="1.0"/> </xs:complexType> <xs:key name="UniqueActivity"> <xs:selector xpath="tns:process"/> <xs:field xpath="@name"/> <xs:field xpath="@revision"/> </xs:key> </xs:element> </xs:schema>
This section describes how to create and configure the audit policy and audit policy binding files.
To audit SOA composite applications at the BPEL activity level:
audit-policy.xml) that defines the audit level settings for the BPEL activities. The file can have any name and must follow the schema described in the preceding section.
<auditPolicies xmlns="http://schemas.oracle.com/bpel/auditpolicy" xmlns:bpel="http://schemas.xmlsoap.org/ws/2003/03/business-process/" xmlns:bpelx="http://schemas.oracle.com/bpel/extension" version="1.0"> <auditPolicy name="whilePolicy"> <!-- enabling this will cause all assign activities to not log --> <!-- anything to the audit trail --> <activity type="bpel:assign" auditLevel="production"/> <!-- enabling this will cause all scope activities and all --> <!-- enclosed activities to not log anything to the audit trail --> <activity type="bpel:scope" auditLevel="production"/> <!-- enabling this will cause all while activities to log with --> <!-- minimak level --> <activity type="bpel:while" auditLevel="production"/> <activity type="bpel:reply" auditLevel="production"/> <activity type="bpel:flow" auditLevel="production"/> <activity type="bpel:switch" auditLevel="off"/> <activity type="bpel:terminate" auditLevel="production"/> <activity type="bpel:empty" auditLevel="development"/> <activity type="bpel:wait" auditLevel="production"/> <activity type="bpel:throw" auditLevel="off"/> <activity type="bpel:catchAll" auditLevel="production"/> <activity type="bpel:sequence" auditLevel="off"/> <activity type="bpel:receive" auditLevel="production"/> </auditPolicy> </auditPolicies>
To enable BPEL extensions to be audited, enter
bpelx:exec with an appropriate auditing level (for example,
<activity type="bpelx:exec" auditLevel="production"/>
audit-binding.xml) that binds the audit policy to the BPEL process. The file can have any name and must follow the schema described in the previous section. This example uses the wildcard option to enable all BPEL processes that begin with
myProcessto be audited. Several other auditing options have been commented out.
<auditPolicyBindings xmlns="http://schemas.oracle.com/bpel/auditpolicyBinding" version="1.0"> <!-- enabling this will cause all processes in the domain to use this --> <!-- policy audit --> <!-- <process auditPolicyName="whilePolicy" name="BPELProcess*"/> --> <!-- enabling this will cause all processes that start with the name --> <!-- myProcess to use the audit policy 'noLoops' --> <process auditPolicyName="noLoops" name="myProcess*"/> <!-- enabling this will cause all processes --> <!-- process auditPolicyName="noAssign" name="*"/> --> </auditPolicyBindings>
audit-binding.xmlfiles in the
<property name="oracle.composite.bpelAuditPolicyFile">audit-policy.xml</property> <property name="oracle.composite.bpelAuditBindingFile">audit-binding.xml</property>