This chapter includes the following sections:
Use the auditing and monitoring tools that JDeveloper provides to analyze the health and performance of your applications. These tools help you improve the quality of your code. You can use the JDeveloper auditing feature to analyze Java code for conformance to programming standards.
Auditing is concerned with programming standards, rather than syntactic correctness. You can audit code even when it is not compilable or executable.
You can use the HTTP Analyzer to facilitate debugging your application in terms of the HTTP traffic sent and received between your projects' web service clients and services and between your Java applications and web resources.
Auditing is the static analysis of code for adherence to rules and metrics that define programming standards. A software code audit is a comprehensive analysis of source code in a programming project with the intent of discovering bugs, security breaches or violations of programming conventions.
A rule is a qualitative test for the presence or absence of some feature. For example, common Java coding style requires that class names be capitalized. A violation occurs when a rule is not adhered to.
A metric is a quantitative measurement of size or complexity. For example, a method that is too long, or covers too many cases should delegate some of its functionality to other methods. An over-threshold anomaly occurs when the specified upper bound is exceeded.
You can create and customize profiles, choose the rules to be used, and set parameters for individual rules. Browse the audit rules and metrics to learn more about them.
JDeveloper's audit and metrics features are extensible. Audit and metrics are two facets of a source code analysis and transformation framework that can be customized and extended. The public API for both audit and metrics is the oracle.jdeveloper.audit
package.
To audit Java code:
Run the auditor on source files to produce an audit report. For more information, see How to Run Audit to Generate an Audit Report.
Use Code Assist to audit while editing. Code Assist enables background audits while you edit. Audit violations are highlighted as you edit. You can apply automated corrections.
Audit from the command line to produce an audit report. For more information, see Auditing Java Code from the Command Line.
Display the Issues window. The Issues Window is one of the JDeveloper features that helps you to audit your code. It displays audit violations in the document selected in the File List and provides information to help you resolve the issues.
An audit report displays rule violations and measurements organized as a tree. A row of the tree corresponds to either a construct or a violation, and includes any measured values for the construct or theoretical violation. A construct is a method, class, file, project, or workspace.
Audit rules are static, qualitative, analyses of code.
In an auditing profile, individual rules can be enabled and configured by setting their properties. When a code construct does not satisfy a rule, a rule violation is reported. Some rules define automatic fixes that you can choose to apply.
The rules contain the properties shown in Table 11-1.
Table 11-1 Rule Properties
Property | Description |
---|---|
Default fix |
The fix that will be used for violations of this rule are when Apply Default Fix is applied to a construct. |
Pattern |
A regular expression used as a filter to find unconventional identifiers. |
Severity |
Use to sort rule violations in the audit report. |
Visibility |
A threshold based on the accessibility keyword. Violations will be reported only if they occur in classes or methods having at least the chosen visibility. |
Audit metrics are static, quantitative analyses of code. In an auditing profile, individual metrics can be enabled and configured. Metrics are configured by setting a threshold: when a code construct exceeds the threshold, an over-threshold measurement is reported in the audit report.
JDeveloper measures the metrics shown in Table 11-2.
Table 11-2 Audit Metrics
Metric | Description |
---|---|
Depth of Inheritance Tree (DIT) |
The depth of the inheritance tree of a class. By convention, j |
Number of Statements (NOS) |
The size, in Java statements, of a method, class, or other construct. |
Cyclomatic complexity (V(G)) |
The branching complexity of a method. Constructs which enclose methods, such as classes and projects, are assigned the maximum complexity measured for an enclosed method. Values above 10 are generally considered problematic. |
You can use auditing tools to view audit reports and to investigate and correct rule violations and over-threshold measurements. A new tab will be created in the Log window when auditing starts, and the audit report will be displayed in it.
Auditing is the static analysis of code for adherence to rules and metrics that define programming standards. Auditing finds defects that make code difficult to improve and maintain. The JDeveloper auditing tools help you find and fix such defects. Code can be audited even when it is not compilable or executable.
An audit report is a set of rule violations and metrics measurements presented as a tree organized into constructs. A construct is a method, class, package, file, project, or workspace. If the audit profile includes rules, the table will have a Severity column that shows the designated severity of the constructs. If the audit profile includes metrics, the table will have an additional column for each metric showing the measurements for the constructs.
To sort the report by the contents of a column, click the column header. To reverse the sort order, click again.
From the Log window toolbar you can perform the operations shown in Table 11-3.
Table 11-3 Audit Window Toolbar Icons
Icon | Name | Description |
---|---|---|
|
Refresh |
Click to rerun the audit on the same selection with the same profile. |
|
Cancel |
Click to terminate a running audit. Note that this may give partial results. |
|
Export |
Click to open the Export Results Dialog, from which you can save the report to a file. You may save the results in XML, HTML, or plain text. |
|
Expand All |
Click to expand all the container nodes in the report, exposing all the rows. |
|
Collapse All |
Click to collapse all the container nodes in the report, hiding all but the top-level constructs. |
|
Group By |
Click to open the Group By dialog, from which you can specify the types of container constructs that will be shown. Grouping by constructs enables you to organize the results better, track defects and violations quickly, and analyze the results easily. |
|
Show Anomalies Only |
Toggle the display of measurements that are within acceptable limits. The threshold is a settable property of metrics. |
|
Show Suppressed Issues |
Toggle to show the suppression scheme issues. |
|
Fix |
Choose a fix for a rule violation from the dropdown menu. For an individual rule violation, choose among the fixes defined for that violation's type. For a group construct, the only choice is Apply Default Fixes, which applies the default fix defined for its type, if any. |
|
Show Error Issues |
Toggle to show just the number of errors in the selected file, or to list the errors in the file |
|
Show Warning Issues |
Toggle to show just the number of warnings in the selected file, or to list the warnings in the file. |
|
Show Incomplete Issues |
Toggle to show just the number of incomplete issues in the selected file, or to list the incomplete issues in the file. |
|
Show Advisory Issues |
Toggle to show just the number of advisory issues in the selected file, or to list the advisory issues in the file. |
Select one or more constructs (container nodes) or rule violations (leaf nodes) and right-click to open the context menu. From the context menu you can perform the operations shown in Table 11-4 on the selected constructs or rule violations.
Table 11-4 Audit Window Context Menu Items
Name | Description |
---|---|
Create <construct> |
Choose to apply the specified fix (constant, static field, instance field, variable, or method). |
About <construct> Rule |
Choose to display an explanation of the rule that applies to this rule violation. |
Hide <Rule> Issues |
Choose to remove all violations of the selected rule from the report. |
Show Hidden Issues |
Choose to restore all previously hidden issues. |
Show Anomalies Only |
Click to toggle the display of measurements that are within acceptable limits. |
Show Error Issues |
Click to toggle the display of the number of errors in the selected file, or to list the errors in the file |
Show Warning Issues |
Click to toggle the display of the number of warnings in the selected file, or to list the warnings in the file. |
Show Incomplete Issues |
Click to toggle the display of the number of incomplete issues in the selected file, or to list the incomplete issues in the file. |
Show Advisory Issues |
Click to toggle to show the display of the number of advisory issues in the selected file, or to list the advisory issues in the file. |
Show Suppressed Issues(X) |
Click to toggle the display of measurements that are within acceptable limits. |
Cancel |
Choose to terminate a running audit. |
Refresh |
Choose to rerun the audit. |
Group By |
Choose to open the Group By dialog, from which you can specify the types of container constructs that will be shown. |
Expand All |
Click to expand all the container nodes in the report, exposing all the rows. |
Collapse All |
Click to collapse all the container nodes in the report, hiding all but the top-level constructs. |
Go to Source |
Choose to open the source file at the point of the rule violation. If you wish, you can edit the file and correct the violation. |
Export |
Choose to open the Export Results Dialog, from which you can save the report to a file. |
JDeveloper's auditing tools help you find and fix defects that make code difficult to improve and maintain. You can audit code even when it is not compilable or executable. The focus of an audit is defined by a profile, which is a set of audit rules and metrics.
To audit Java Code:
You can save the finished audit report as an XML file or as a formatted HTML or text file. For more information, see How to Save an Audit Report. Formats are defined by XSL stylesheet files in the /jdev//audit/stylesheets
directory (this directory is not created until audit is run). To create a custom format, adapt a copy of one of the predefined stylesheet files, and add it to the directory.
You can audit a workspace, a project, or a source file from the command line by invoking ojaudit.exe
, which is included in your JDeveloper installation, in the jdev_install
/jdeveloper/jdev/bin
directory.
Synopsis
ojaudit option... file...
Table 11-5 contains the parameters you can use during the audit.
Table 11-5 Command Line Parameters
Parameter | Description |
---|---|
|
Specifies the workspace ( |
- |
Sets the class path for files to audit, if a project is not being audited. |
|
Disables the specified rule or metric in profile. To supply multiple values, repeat this option. This option requires the use of |
|
Enables the specified rule or metric in the profile. To supply multiple values, repeat this option. |
|
Sets the character encoding for the report. If absent, the character encoding specified for the project is used (see the Compiler page of the project's Project Properties dialog). |
|
Sets the issue severity that the Auditor will regard as failure. |
|
Applies default fixes to the code. This option modifies source files. |
|
Prints help for the command help and exits. |
|
Lists all audited files in the audit report including those that have no issues. |
|
Specifies the maximum file size, in Mb, to audit. |
|
Enables the specified metric. |
|
Disables the specified metric. This option requires the use of |
|
Disables the specified audit rule. This option requires the use of |
|
Sets an empty audit report title. |
|
Specifies the pathname of the output file. If omitted, output is written to standard output. |
|
(required) Specifies the profile to use. It is either one of the profiles defined in JDeveloper (as set in the Audit > Audit Profiles page of the Tools > Preferences dialog), or the path name of an exported Audit profile file. Case and whitespace are ignored when searching for a matching profile. |
|
Print defined profile names and exit. |
|
Sets the output file for the merged profile. |
- |
The project context to use for parameters that are source files. If all parameters are projects or workspaces, this option is not required. |
- |
Suppresses the copyright message. |
-role name |
Sets the active JDeveloper customization role. |
-rule name |
Enables the specified rule. |
-seal |
Seals the specified profiles. This option requires the use of |
-rulehelp |
Prints the available rules and exits. |
|
Set source path for files to audit, if a project is not being audited |
|
The XSLT stylesheet to apply to the report. The name can either be a style sheet defined in JDeveloper, or a pathname to a style sheet file. If absent, the output will be an XML file. Case and whitespace are ignored when searching for a matching predefined stylesheet. |
|
Print defined style sheet names and exit. |
|
The title to use for the report. If absent when |
|
Causes all execution messages to be displayed. |
- |
Prints the command's version and exits. |
|
Sets the working set for files to audit. This option requires the use of |
|
Prints the available working sets for the workspace and exits. |
|
Sets the workspace context for files to audit. |
|
Changes the format of an existing XML report. This option requires the use of |
|
Sets the output file as a plain XML report. This option requires the use of |
|
Includes options and parameters from the audit file. |
Note the following considerations:
Unless the file
specified is a workspace or project, you must specify -project
, -sourcepath
, or -classpath
.
If a project depends on other projects in the workspace, you must specify -workspace
.
The options -profile
and -style
accept a name or a URL. Case and whitespace in the name are ignored.
The options -enable
and -disable
accept an ID or a label. Case and whitespace in the name are ignored.
The options -rule
and -metric
are synonymous of -enable. The options -norule
and -nometric
are synonymous of -disable
.
An audit profile defines the focus of an audit by specifying the rules, code assists, and metrics that will be used to analyze Java code. You can activate and deactivate rules, code assists, and metrics for an audit profile from the Audit Profiles preferences page. While several profiles are predefined, you can create others by modifying an existing profile. You can modify an audit profile by enabling or disabling rules, code assists, and metrics, or by changing their configuration.
Certain audit profiles are used by default with some JDeveloper processes and features, as shown in Table 11-6.
Table 11-6 Audit Profile
Profile | Description |
---|---|
Code Assist Rules |
Used by the Source Editor, Issues window, Application Overview, and File List. |
Compile Rules |
Used at the end of a compile when Audit While Compiling is selected in the Audit page of the Preferences dialog |
Audit Rules |
Used by the Source Editor, Issues window, Application Overview, and File List. This is the initial default for the Audit command. However, this is not permanent because the Audit dialog remembers whatever profile was last selected. |
Javadoc Rules |
Used by the Source Editor. |
ADF Best Practice Rules |
Used for ADF applications. |
JDeveloper provides predefined profiles, each with different combinations of the available rules, code assists, and metrics:
ADF Best Practice Rules
All Metrics
All Rules
Audit Rules
Code Assist Rules
Compile Rules
Javadoc Rules
By saving the audit profile with the Sealed option selected in the Audit Profile page, you seal the current audit profile, which means that only the rules selected for that profile are enabled the next time that specific audit profile is loaded. Any new rules that are present since the profile was last saved are disabled (regardless of their default state). New rules can be introduced in a number of ways, such as when new extensions are installed when JDeveloper is updated. In the course of developing a project, sealing the audit profile preserves the project environment, preventing new audit issues from being introduced.
A suppression scheme describes a scheme for suppressing issues (that is, audit violations) discovered through a project audit. When auditing a project, you can view suppression issues in the Audit Log window. You can enable (the default state) or disable suppression schemes from being audited through the Audit Profile dialog. Disabling suppression schemes can reduce auditing time and reduce output in the Log window.
To disable a suppression scheme:
You can delete an existing audit profile, but not a predefined profile. That any custom profile you created with the Save As command, you can delete.
To delete an existing audit profile:
You can import or export audit profiles. This enables you to share profiles, for example, or to maintain a checked in profile used by ojaudit
and a nightly build. Audit profiles are imported or exported as XML files.
To import or export an audit profile:
When you audit your Java programs, you can generate an audit report. An audit report is a list of rule violations and over-threshold measurements. In the audit report, you can investigate these problems, and manually or automatically correct them.
To generate an audit report:
An object is marked serializable by implementing the java.io.Serializable
interface, which signifies that the object can be flattened into bytes and subsequently inflated in the future.
To turn off serialization on a field of an object, tag the field of the class of the object with the Java's transient keyword. If a class is marked as serializable, but contains unserializable fields that are not marked as transient, then the class is not serializable. You can run an audit to detect these unserializable fields.
To set audit rules:
There is an identifier called serialVersionUID
that enables versioning. You can run an audit that flags all classes that implement java.io.Serializable
but do not also have the serialVersionUID
.
To set audit rules:
JDeveloper generates a report of all audit rule violations. Use the audit report to investigate and correct rule violations and over-threshold measurements. As shown in Figure 11-2, audit reports are displayed as tabbed panes of the Log window. In this window, you can choose a fix for a rule violation from a drop-down menu. For an individual rule violation, choose among the fixes defined for that violation's type.
Figure 11-2 Audit Report
Use refresh to rerun an audit using the same profile. You may wish to perform a refresh after you have made changes and fixes to your code.
To refresh an audit report:
Click in the Log Window toolbar, or right-click and choose Refresh.
The Export Audit Results dialog clears, and a new audit begins. If you want to stop the audit, click in the Log's toolbar.
To inspect an audit rule violation:
Figure 11-3 About Rule Dialog
You can rearrange the audit report columns into left or right positions.
To organize audit report columns:
Drag the column headers left or right to your preferred position.
Audit report rows are rule violations or measurements, or groups of violations and measurements. The report is organized as a tree. A row of the tree corresponds to either a construct or a violation, and includes any measured values for the construct or a theoretical violation. A construct is a method, class, file, package directory, project, or workspace.
You can choose the constructs that are shown in the report.
To organize audit report rows:
You specify filters to prune the set of Java classes whose violations are shown. You can filter by package names, class names, or both. A filter consists of one or more patterns separated by commas.
A pattern can contain the following special characters:
* matches any number of characters
? matches any single character
! at the beginning of a pattern denotes an exclusion pattern
The set of classes that passes a filter is determined by considering the patterns in order. A non-exclusion pattern adds all classes that match the pattern to the set, an exclusion pattern removes all classes that match the pattern from the set. Table 11-7 contains the filters you can specify
Table 11-7 Filters
Name | Description |
---|---|
Package |
Enter filter patterns that will apply to all but the last element of fully qualified class names. If this field is empty it has no effect. |
File |
Enter filter patterns that will apply only to the last element of fully qualified class names. If this field is empty it has no effect. |
Apply |
Click to apply the given Package and File filters to the report's rows. |
Clear |
Click to erase the Package and File filters, and to restore the report's rows. |
You can save an audit report as an XML file or as a formatted HTML or text file. Formats are defined by XSL stylesheet files in the directory, jdev_install/jdev
/system/audit
/stylesheets
(this directory is not created until audit is run). To create a custom format, adapt a copy of one of the predefined stylesheet files, and add it to the directory.
To save an audit report:
Click in the Log Window toolbar, or right-click and choose Export.
The Export Audit Results dialog display. Choose a title, format, and destination for the report, and click OK.
You can fix an audit rule violation manually by editing the source, or for some rules, by selecting an automated fix. For an individual rule violation, choose among the fixes defined for that violation's type. For a group construct, the only choice is Apply Default Fixes, which applies the default fix defined for its type, if any.
To fix an audit rule violation manually:
In the audit report, select the rule violation (a leaf node in the Constructs tree).
Right-click and choose Go to Source.
An editor for the source file opens with the cursor positioned at the location of the rule violation.
Edit the code to correct the cause of the violation.
To apply an automated fix to an audit rule violation:
You can apply automated fixes to all the rule violations in a construct. Default fixes will be applied to each rule violation in the construct that has a Default Fix
property with a value other than None
.
To fix a construct's audit rule violations:
You can suppress the display of all the rule violations of a given type in the audit report. This may make the report easier to read, since it hides all violations of a particular rule. It is not possible to suppress individual rule violations.
To hide audit rule violations:
In the audit report, select a rule violation (a leaf node in the Constructs tree).
Right-click, and choose Hide rule Issues.
All of the violations of the audit rule are removed from the audit report. The removed rules are not tallied in their parent construct's summaries. Empty constructs are removed if Show Over Threshold Only is enabled. If not, just the violations are removed.
To restore hidden audit rule violations:
Metrics reports display measurements for the constructs in the analyzed code. You can focus the report on over-threshold measurements by hiding the others. The threshold is a settable property of metrics.
To show only over-threshold measurements:
In the Log window toolbar, click the over Show Anomalies Only icon. Click again to show all measurements.
Removed measurements are not tallied in their parent construct's summaries. Empty constructs are removed if Show Over Threshold Only is enabled. If not, just the violations are removed.
The HTTP Analyzer allows you to monitor HTTP traffic, for example, to:
Monitor request/response traffic between a web service client and the service.
Monitor HTTP requests between Java applications and web resources.
The HTTP Analyzer acts as a proxy between code in JDeveloper and the HTTP resource that the code is communicating with, and helps you to debug your application in terms of the HTTP traffic sent and received.
When you run the HTTP Analyzer, there are a number of windows that provide information for you.
When you open the HTTP Analyzer from the Tools menu, the HTTP Analyzer Log window opens, illustrated in Figure 11-4. By default its position is at the bottom center of JDeveloper, alongside the other log windows.
Figure 11-4 HTTP Analyzer Log Window
When HTTP Analyzer runs, it outputs request/response messages to the HTTP Analyzer log window. You can group and reorder the messages:
To reorder the messages, select the Sequence tab, then sort using the column headers (click on the header to sort, double-click to secondary sort).
To group messages, click the Correlation tab.
To change the order of columns, grab the column header and drag it to its new position.
Table 11-8 HTTP Analyzer Log Window Toolbar Icons
Icon | Name | Function |
---|---|---|
|
Analyzer Preferences |
Click to open the HTTP Analyzer Preferences dialog where you can specify a new listener port, or change the default proxy. An alternative way to open this dialog is to choose Tools > Preferences, and then navigate to the HTTP Analyzer page. |
|
Create New Request |
Click to open the HTTP Analyzer Test window, where you enter payload details, and edit and resend messages. |
|
Start HTTP Analyzer |
Click to start the HTTP Analyzer running. The monitor runs in the background, and only stops when you click Stop or exit JDeveloper. If you have more than one listener defined clicking this button starts them all. To start just one listener, click the down arrow and select the listener to start. |
|
Stop HTTP Analyzer |
Click to stop the HTTP Analyzer running. If you have more than one listener running, clicking this button stops them all. To stop just one listener click the down arrow and select the listener to stop. |
|
Send Request |
Click to resend a request when you have changed the content of a request. The changed request is sent and you can see any changes in the response that is returned. |
|
Open WS-I log file |
Click to open the Select WS-I Log File to Upload dialog, where you can navigate to an existing WS-I log file. For more information, see Monitoring and Analyzing Web Services. |
|
Save Packet Data |
Click to save the contents of the HTTP Analyzer Log Window to a file. |
|
WS-I Analyze |
Click to invoke the WS-I Analyze wizard which allows you to examine a web service at packet level. For more information, see Monitoring and Analyzing Web Services. |
|
Select All |
Click to select all the entries in the HTTP Analyzer Log Window. |
|
Deselect All |
Click to deselect all the entries in the HTTP Analyzer. |
|
Clear Selected History (Delete) |
Click to clear the entries in the HTTP Analyzer. |
An empty HTTP Analyzer test window appears when you click the Create New Request button in the HTTP Analyzer Log window. A test window showing details of the request/response opens when you choose Test Web Service from the context menu of a web service container in the Applications window, or when you double-click a line in the HTTP Analyzer Log Window, illustrated in Figure 11-5. By default, its position is in the center of JDeveloper, in the same place that the source editor appears.
Figure 11-5 HTTP Analyzer Test Window
The test window allows you examine the headers and parameters of a message. You can test the service by entering a parameter that is appropriate and clicking Send Request.
The tabs along the bottom of the test window allow you choose how you see the content of the message. You can choose to see the message as:
The SOAP structure, illustrated in Figure 11-5.
The HTTP code, for example:
<?xml version="1.0" encoding="UTF-8"?> <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://annotation/"> <env:Header/> <env:Body> <ns1:getDeptInfo> <arg0/> </ns1:getDeptInfo> </env:Body> </env:Envelope>
The hex content of the message, for example:
[000..015] 3C 3F 78 6D 6C 20 ... 3D 22 31 <?xml version="1 [016..031] 2E 30 22 20 65 6E ... 22 55 54 .0" encoding="UT [032..047] 46 2D 38 22 3F 3E ... 6E 76 65 F-8"?> <env:Enve [048..063] 6C 6F 70 65 20 78 ... 76 3D 22 lope xmlns:env="
The raw message, for example:
POST http://localhost:7101/WebService-Annotation-context-root/MyCompanyPort HTTP/1.1 SOAPAction: "" Content-Type: text/xml; charset=UTF-8 Host: localhost:7101 Content-Length: 277 <?xml version="1.0" encoding="UTF-8"?> <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://annotation/"> <env:Header/> <env:Body> <ns1:getDeptInfo> <arg0/> </ns1:getDeptInfo> </env:Body> </env:Envelope>
When you open the HTTP Analyzer from the Tools menu, the HTTP Analyzer Instances window appears. By default, its position is at the bottom center of JDeveloper, as a tab alongside the HTTP Analyzer log window. This window provides information about the instances of the HTTP Analyzer that are currently running, or that were running and have been stopped. The instance is identified by the host and port, and any rules are identified. You can start and stop the instance from this window.
Figure 11-6 HTTP Analyzer Instances Window
You create a new instance in the HTTP Analyzer page of the Preferences dialog, which opens when you click .
Table 11-9 HTTP Analyzer Instances Window Toolbar Icons
Icon | Name | Function |
---|---|---|
|
Analyzer Preferences |
Click to open the HTTP Analyzer page of the Preferences dialog where you can specify a new listener port, or change the default proxy. |
|
Create New Request |
Click to open a new instance of the HTTP Analyzer Test window, where you enter payload details, and edit and resend messages. |
|
Start HTTP Analyzer |
Click to start the HTTP Analyzer running. The monitor runs in the background, and only stops when you click Stop or exit JDeveloper. If you have more than one listener defined clicking this button starts them all. To start just one listener, click the down arrow and select the listener to start. |
|
Stop HTTP Analyzer |
Click to stop the HTTP Analyzer running. If you have more than one listener running, clicking this button stops them all. To stop just one listener click the down arrow and select the listener to stop. |
When you start the HTTP Analyzer, all Java processes and application server activity with JDeveloper will send their traffic via the HTTP Analyzer, using the proxy settings in the HTTP Analyzer page of the Preferences dialog, which opens when you click the Start HTTP Analyzer button in the Instance or Log window. By default, the HTTP Analyzer uses a single proxy on an analyzer instance (the default is 8099
), but you can add additional proxies of your own if you need to.
Each analyzer instance can have a set of rules to determine behavior, for example, to redirect requests to a different host/URL, or to emulate a web service.
By default, the HTTP Analyzer uses a single proxy on an analyzer instance (the default is 8099), but you can add additional proxies of your own if you need to.
To set HTTP Analyzer preferences:
You can have more than one instance of HTTP Analyzer running. Each will use a different host and port combination, and you can see a summary of them in the HTTP Analyzer Instances window.
To add an additional HTTP Analyzer Instance:
You can use external web browsers to route messages through the HTTP Analyzer so that you can see the traffic between the web browser and client. This section describes how you can use a profile in Firefox so that when you start the HTTP Analyzer and run an HTML or JSP or JSF page from within JDeveloper, a new instance of Firefox using the Debugger profile is started.
Note:
The steps below use the command firefox
, which is correct for Linux. If you are using Windows, use firefox.exe
.
To configure a Firefox profile for the HTTP Analyzer:
Click OK. When you start the HTTP Analyzer and run an HTML or JSP or JSF page from within JDeveloper, a new instance of Firefox using the Debugger profile is started.
You can use the HTTP Analyzer with secured services or applications, for example, web services secured by policies. JDeveloper comes with a set of preconfigured credentials, HTTPS Credential
, which is always present. You cannot delete or edit HTTPS Credential
, but you can copy it to create a new credential of the same type.
When you run the service or application the analyzer uses the supplied credentials for perform the appropriate action.
The HTTP Analyzer can use the following types of credential:
HTTPS encrypts an HTTP message prior to transmission and decrypts it upon arrival. It uses a public key certificate signed by a trusted certificate authority. When the integrated application server is first started, it generates a DemoIdentity
that is unique to your machine, and the key in it is used to set up the HTTPS channel.
The client keystore identity is used for configuring HTTPS. The server keystore identity is used when the HTTP Analyzer is acting as a server; it is not used when connecting to a remote server.
For more information about keystores and keystore providers, see Understanding Security for Oracle WebLogic Server. When the default credential HTTPS Keystore is selected, you need to specify the keystores that JDeveloper and the HTTP Analyzer should use when handling HTTPS traffic. Two keystores are required to run the HTTP Analyzer:
The client keystore, containing the certificates of all the hosts to be trusted by JDeveloper and the Analyzer (client trust) when it makes onward connections.
The server keystore, containing a key that the Analyzer can use to authenticate itself to calling clients (server keystore).
The client keystore is only required when mutual authentication is required.
You can create extra HTTPS keystores in addition to the default one provided by JDeveloper.
Username token is a way of carrying basic authentication information. You supply a username/password to provide authentication.
X509 is a PKI standard for single sign-on, where certificates are used to provide identity, and to sign and encrypt messages. You enter details of an X509 certificate. When you supply a valid keystore and the password for the keystore, the client key aliases are populated.
If JDeveloper has any problems finding and opening the keystore, error messages will be displayed.
A Secure Token Service (STS) is a web service that issues and manages security tokens over HTTPS. You enter the Security Token Server provider URL and optionally a policy URL.
Note:
The client truststore must contain the server public key, otherwise when the HTTP Analyzer requests the SAML token it will fail.
OAuth is an open authentication protocol that allows users to approve application to act on their behalf without sharing their password. You can test resources protected by OAuth protocol security using a valid OAuth credential, for example, to test resources that use Twitter feeds.
Note:
To access resources owned by users with a service provider you must first register with the service provider.
Use to test JRF web services. jps-config.xml
contains the security information that the HTTP Analyzer needs to access the service.
You can import of data from jps-config.xml
into a credential record. You provide the location of jps-config.xml
and enter the name of a CSF key and JDeveloper creates a credential record with the necessary data read from jps-config.xml
and from the underlying wallet file.
Data imported from jps-config.xml
is populated in the X509 Certificates tab and in the Username Token tab.
Once saved, the credential record can be used repeatedly in the HTTP Analyzer and during web service proxy generation as the source for the keystore, keys and other required data.
JDeveloper comes with a set of HTTPS Keystore credentials called HTTPS Credential
. You can:
Configure the client keystore for HTTPS Credential
if mutual authentication is required.
Create a new credential of one of the supported types.
Create a new credential based on an existing credential.
Delete a credential. Note that you cannot delete HTTPS Credential
.
To configure credentials:
The HTTP Analyzer allows you to view the content of request and response HTTP messages.
To monitor HTTP packets:
If you are using the HTTP Analyzer to examine how a web service developed in JDeveloper works, the HTTP Analyzer starts automatically when you choose Test Web Service from the context menu of the web service in the Applications window.
You can use the HTTP Analyzer when you are debugging Web pages, such as HTML, JSP, or JSF pages. This allows you to directly examine the traffic that is sent back and forth to the browse.
To debug Web pages using the HTTP Analyzer:
You can edit the contents of a HTTP request and resend it. You can then examine the response to see whether the changes you expect have occurred.
To send a request:
In the Request pane of the HTTP Analyzer Test window, enter parameter values.
Click the Send Request button.
The processed value is returned in the Response pane.
To edit and resend a request:
You can set rules so that the HTTP Analyzer runs using behavior determined by those rules. You can set more than one rule in an HTTP Analyzer instance. If a service's URL matches a rule, the rule is applied. If not, the next rule in the list is checked. If the service does not match any of the rules the client returns an error. For this reason, you should always use a Pass Through rule with a blank filter (which just passes the request through) as the last rule in a list to catch any messages not caught by the preceding rules.
The types of rule available are:
Pass Through Rule
Forward Rule
URL Substitution Rule
Tape Rule
The Pass Through simply passes a request on to the service if the URL filter matches. When you first open the Rule Settings dialog, two Pass Through Rules are defined:
The first has a URL filter of http://localhost:631
to ignore print service requests.
The second has a blank URL filter, and it just which just passes the request to the original service. This rule should normally be moved to end of the list if new rules are added.
The Forward rule is used to intercept all URLs matched by the filter and it forwards the request on to a single URL.
The URL Substitution rule allows you to re-host services by replacing parts of URL ranges. For example, you can replace the machine name when moving between the integrated application server and Oracle WebLogic Server.
The tape rule allows you to run the HTTP Analyzer in simulator mode, where a standard WS-I log file is the input to the rule. When you set up a tape rule, there are powerful options that you can use:
Loop Tape, which allows you to run the tape again and again.
Skip to matching URL and method, which only returns if it finds a matching URL and HTTP request method. This means that you can have a WSDL and an endpoint request in the same tape rule.
Correct header date and Correct Content Size, which allow you change the header date and content size of the message to current values so that the request does not fail.
An example of using a tape rule would be to test a web service client developed to run against an external web service.
To test a web service client developed to run against an external web service:
Note:
Tape Rules will not work with SOAP messages that use credentials or headers with expiry dates in them.
You can set rules so that the HTTP Analyzer runs using behavior determined by those rules. Each analyzer instance can have a set of rules to determine behavior, for example, to redirect requests to a different host/URL, or to emulate a web service.
To set rules for an HTTP Analyzer instance:
This section contains information about using the HTTP Analyzer with web services developed in JDeveloper. In general, you can use HTTP Analyzer to examine the content of web services in the same way as using it to examine any packets across HTTP.
Note:
You cannot use the HTTP Analyzer to test JAX-RPC web services that have WebLogic Server 9.x policies attached. WebLogic 9.x policies have been deprecated in JAX-RPC.
JDeveloper allows you to test web services using the HTTP Analyzer to examine the network traffic of a proxy connecting to a web service developed in JDeveloper.
To test a web service:
You can examine the contents of the HTTP headers of the request and response packets to see the SOAP structure, the HTTP content, the Hex content or the raw message contents by choosing the appropriate tab at the bottom of the HTTP Analyzer Test window.
You can use the HTTP Analyzer to interact with RESTful web services. Representational State Transfer (REST) describes any simple interface that transmits data over a standardized interface (such as HTTP) without an additional messaging layer, such as SOAP. REST provides a set of design rules for creating stateless services that are viewed as resources, or sources of specific information, and can be identified by their unique URIs. A client accesses the resource using the URI, a standardized fixed set of methods, and a representation of the resource is returned. The client is said to transfer state with each new resource representation.
When using the HTTP protocol to access RESTful resources, the resource identifier is the URL of the resource and the standard operation to be performed on that resource is one of the HTTP methods: GET
, PUT
, DELETE
, POST
, or HEAD
.
The HTTP Analyzer has support for Hypermedia as the Engine of Application State (HATEOAS), and so you can examine and test RESTful web services using the HTTP Analyzer.
Java API for RESTful Web Services (JAX-RS) provides support for creating Web services according to the REST architectural style. JAX-RS uses annotations to simplify the development of RESTful Web services. By adding annotations to your Web service, you can define the resources and the actions that can be performed on those resources. WebLogic Server supports Jersey 2.x (JAX-RS 2.0 RI). Information about Jersey 2.x is available at: https://jersey.java.net/download.html
.
JAX-RS 2.0 API Specification (Rev a) is available at: https://jax-rs-spec.java.net/nonav/2.0-rev-a/apidocs/index.html
.
A Web Application Description Language (WADL) is an XML file created by Jersey that provides a description of the resources in the servlet. For more information about WADL, see https://wadl.dev.java.net/
.
An outline of testing a RESTful service using WADL is given here, with more detailed steps in the procedure below. Not all RESTful services work this way. The HTTP Analyzer reads a WADL created by Jersey for the RESTful web service, and you examine the WADL in the HTTP Analyzer Test window. From the WADL, you can open an instance of the HTTP Analyzer Test window directly from a method, and test the method by entering a parameter and posting it to the service. The HTTP Analyzer redirects the response to a new URL which it displays, and when you click on it another instance of the HTTP Analyzer Test window opens with the response. Once you have finished, you use the WADL to locate the new resource that the HTTP Analyzer created to test the service and delete it.
The following example provides an example of a WADL document which uses POST
, GET
and DELETE
.
<?xml version = '1.0' encoding = 'UTF-8' standalone = 'yes'?> <application xmlns="http://research.sun.com/wadl/2006/10"> <doc xmlns:jersey="http://jersey.dev.java.net/" jersey:generatedBy="Jersey: 1.1.0-ea 04/30/2009 04:46 PM"/> <resources base="http://localhost:7101/RESTDemo-ContainerProject-context-root/jersey/"> <resource path="buckets"> <method name="POST" id="createNewBucket"> <request> <representation mediaType="*/*"/> </request> <response> <representation mediaType="*/*"/> </response> </method> <method name="GET" id="getBuckets"> <response> <representation mediaType="application/buckets+xml"/> </response> </method> <resource path="/{id}"> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:int" style="template" name="id"/> <method name="DELETE" id="delete"> <response> <representation mediaType="*/*"/> </response> </method> <method name="GET" id="getBucket"> <response> <representation mediaType="*/*"/> </response> </method> </resource> </resource> </resources> </application>
To test a REST web service
Testing a REST web service requires that you:
examine the RESTful service
test the service
work with the resource
To examine the RESTful service:
Run the REST web service on the integrated application server.
Right-click the web service node in the Applications window, and choose Test Web Service. JDeveloper automatically:
Starts the integrated application server, if it is not already running.
Compiles and binds the web service application to the integrated application server instance, which is the Integrated WebLogic Server node in the Application Servers window.
Displays a Log window for the integrated application server (if there is not one already open).
Click the HTTP Content tab in the HTTP Analyzer Test window. RESTful web services do not use SOAP, so you will not use the SOAP Structure tab.
In the Log window for the integrated application server, click the link next to Target Application WADL. A second instance of the test window opens. Notice that the URL displays the WADL, and the Method is GET.
Click Send Request. The GET method is used to return the content of the WADL so that it is displayed in the Response pane.
If necessary, use the left arrow to maximize the width of the pane to see the code more clearly.
To view the WADL file at anytime, click Open WADL to the right of the RESTful web service URL. A read-only version of the WADL file opens in the source editor, enabling you to view the a summary of the RESTful web service resources and methods, or the WADL source. For more information, see Accessing the RESTful Web Service WADL.
To test the RESTful service:
In the WADL displayed in the Response pane, press Ctrl+mouse-click to use the Go to declaration feature to reveal parts of the HTTP message that can be accessed. Click on a POST method that is now revealed as a link. This opens a new instance of the test window.
Enter a parameter in the Request pane, and click Send Request. The POST method is used, and the Request pane displays a 201 Created HTTP
status code along with the location of the URL that contains the response.
Click on the URL in the Response pane. Another instance of the test window opens. Notice that the URL displays the redirected URL, and the Method is GET. Click Send Request, and the response to the parameter you entered is displayed in the Request pane.
Note:
When you click on the WADL, the correct content-type and accept headers will be generated.
To work with the resource:
Select the test window instance for the WADL, and navigate to the GET
method. Press Ctrl+mouse-click to open a new instance of the test window. Notice that the URL displays the redirected URL, and the Method is GET
.
You can update the resource by choosing PUT from the Method list, and click Send Request.
In order to delete this resource, choose DELETE from the Method list, and click Send Request.
The HTTP Analyzer will pass unsecured WebSockets requests via a proxy.
The content of the request response stream will be available in the HTTP Analyzer after you close and reopen the message. The WebSockets messages are those with a response code of 101
.
The HTTP Analyzer works with Fast Info set, but it will default to sending soap/xml instead unless you override the Content-Type
in the HTTP headers.
SOAP 1.1 Change the Content-Type
to application/fastinfoset
.
SOAP 1.2 Include the action name, for example
application/soap+fastinfoset;action="http://project1/HelloWorldSOAP12/helloRequest
This section contains information to help resolve problems that you may have when running the HTTP Analyzer.
If you have an application waiting for a response, do not start or stop the HTTP Analyzer. Terminate the application before starting or stopping the HTTP Analyzer.
When you use the HTTP Analyzer, you may need to change the proxy settings in JDeveloper. For example:
If you are testing an external service and your machine is behind a firewall, ensure that the JDeveloper is using the HTTP proxy server.
If you are testing a service in the integrated application server, for example when you choose Test Web Service from the context menu of a web service in the Applications window, ensure that JDeveloper is not using the HTTP proxy server.
If you run the HTTP Analyzer, and see the message
500 Server Error The following error occurred: [code=CANT_CONNECT_LOOPBACK] Cannot connect due to potential loopback problems
you probably need to add localhost|127.0.0.1
to the proxy exclusion list.
To set the HTTP proxy server and edit the exception list: