21 Developing and Securing Web Services

This chapter describes how JDeveloper enables you to develop, deploy, test, and monitor web services; secure web services using policies; and manage the Web Service Definition Language (WSDL) files. Learn how to discover web services using Universal Description, Discovery and Integration (UDDI) and create web service clients.

This chapter includes the following sections:

About Developing and Securing Web Services

Web services consist of a set of messaging protocols and programming standards that expose business functions over the Internet using open standards. A web service is a discrete, reusable software component that is accessed programmatically over the Internet to return a response.

If you use web services in your application, you use JDeveloper to perform the following tasks:

  • Configure JDeveloper to develop and run web services

  • Create web service clients by performing one or more of the following tasks:

    • Find web services in a Universal Description, Discovery and Integration (UDDI) registry

    • Create a client and proxy classes to access an existing web service to incorporate it into an application

  • Create web services by performing one or more of the following tasks:

    • Create web services from the underlying Java implementation (bottom up)

    • Create Simple Object Access Protocol (SOAP) web services from the WSDL (top-down)

  • Manage WSDL files for SOAP services

  • Secure web services using policies

  • Test and debug web services

  • Deploy web services to the Integrated WebLogic Server or Oracle WebLogic Server

  • Monitor and analyze deploy web services

  • Publish web services to a UDDI registry

The following sections provide more information about developing and securing web services using JDeveloper:

Developing Java EE Web Services Using JDeveloper

JDeveloper supports the web service technologies and standards defined in Table 21-1 for developing and securing Java EE web services.

Table 21-1 Java EE Web Service Technologies and Standards Supported by JDeveloper

Web Service Technology Web Service Standard Description

Simple Object Access Protocol (SOAP)

Java API for XML-Based Web services (JAX-WS) 2.2

You can create SOAP web services, using JAX-WS, from Java classes and the remote interface of EJBs. The web service creation wizards create the deployment files for you, so once you have created your web service the final step is to deploy it to application servers.

Alternatively, you can create a JAX-WS web service starting with a WSDL, as a top-down web service.

The JAX-WS implementation in WebLogic Server is extended from the JAX-WS Reference Implementation (RI) developed by the Glassfish Community (see http://jax-ws.java.net/index.html).

For more information, see Creating JAX-WS Web Services and Clients.

Representational State Transfer (REST)

Java API for RESTful Web Services (JAX-RS) 2.0

REST describes any simple interface that transmits data over a standardized interface (such as HTTP) without an additional messaging layer, such as SOAP.

Using JAX-RS, you can develop web services that are based on REST, referred to as “RESTful web services," from Java classes.

WebLogic Server supports the following JAX-RS Reference Implementations (RIs):

  • Jersey 2.5.1 (JAX-RS 2.0 RI)—This implementation is offered as a shared library and provides a production quality implementation of the JSR-339 JAX-RS 2.0 specification, defined at: http://jcp.org/en/jsr/detail?id=339.

The Jersey 2.5.1 (JAX-RS 2.0 RI) shared library is auto-deployed to the Integrated WebLogic Server.

Note: RESTful web services and clients that are built using Jersey 2.5.1 (JAX-RS 2.0 RI) are secured using OWSM policies. For more information about securing RESTful web services and clients built using Jersey 2.5.1 (JAX-RS 2.0 RI), see "Securing RESTful Web Services and Clients" in Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server.

For more information, see Creating RESTful Web Services and Clients.

Note:

Support for the Jersey 1.18 (JAX-RS 1.1RI) client APIs of WebLogic Server is deprecated. However, support is maintained for backward compatibility. For more information about compatibility with earlier Jersey/JAX-RS releases, see Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server

For guidelines to consider when choosing between SOAP and REST technologies, see “How Do I Choose Between SOAP and REST?" in Oracle Fusion Middleware Understanding WebLogic Web Services for Oracle WebLogic Server.

Securing Java EE Web Services Using JDeveloper

To secure Java EE web services using JDeveloper you can attach one of the policy types defined in the following table.

Table 21-2 Types of Policies for Securing Java EE Web Services

Type of Policy Description

Oracle Web Services Manager (OWSM) Policy

Policy provided by OWSM. For more information about OWSM and the predefined policies, see Understanding Oracle Web Services Manager.

You can attach OWSM security policies only to Java EE web services.

You manage OWSM policies from Oracle Enterprise Manager Fusion Middleware Control. For more information, see Oracle Fusion Middleware Securing Web Services and Managing Policies with Oracle Web Services Manager.

WebLogic Web Service Policy

Policy provided by WebLogic Server. You can attach WebLogic web service policies to JAX-WS web services only. For more information about the WebLogic web service policies, see Oracle Fusion Middleware Securing WebLogic Web Services for Oracle WebLogic Server.

You manage WebLogic web service policies from WebLogic Administration Console.

Note:

For Java EE 7, Java API for RESTful Web Services (JAX-RS) 2.0 adds support of the Jersey 2.5.1 Java API for RESTful Web Services (JAX-RS) 2.0 Reference Implementation (RI) as a pre-built shared library. RESTful web services and clients that were built using Jersey 2.5.1 (JAX-RS 2.0 RI) are secured with Oracle Web Services Manager (OWSM) security policies.

It is recommended that you use OWSM policies over WebLogic web service policies whenever possible. You cannot mix your use of OWSM and WebLogic web service policies on the same web service.

For more information, see:

Discovering and Using Web Services

You can quickly create a client to an existing web service in order to use it in your application. For more information, see:

In addition, JDeveloper incorporates a UDDI browser and you can define connections to UDDI registries, for example, to one within your organization. For more information, see Working with Web Services in a UDDI Registry.

Using JDeveloper to Create and Use Web Services

This following information will help you understand more about web services, and how you can use JDeveloper to create, configure, and use them.

How to Use Proxy Settings and JDeveloper

By default, JDeveloper does not use a proxy when connecting to the Internet. If you have problems making connections from JDeveloper, you may need to change the proxy server settings you use.

When you use the HTTP Analyzer, the analyzer itself is a proxy and any traffic to be monitored by it is routed through it, just as though it was a normal proxy server. If you already have a proxy set in JDeveloper, the analyzer will make sure that the traffic goes through the original proxy after it has been passed through the analyzer.

Note:

JDeveloper does not support NTLM proxy servers.

The following sections describe how to enable and disable proxy setting using JDeveloper:

Using the Default Browser Proxy Settings

You may find it convenient to use the proxy settings that are configured for the default browser.

To use the default browser proxy settings:

  1. Choose Tool > Preferences, and select Web Browser and Proxy.

    For more information at any time, click F1 or Help from the Web Browser and Proxy dialog.

  2. Select the Web Browsers tab and select the desired default browser from the list.
  3. Select the Proxy Settings tab to configure proxy settings.
  4. Select Use System Default Proxy Settings.
  5. Click OK.

Configuring Custom Proxy Settings

You can configure custom proxy settings. This is useful if you need to exclude specific IP addresses or host names from the list.

For example, if you are connecting to an IP address behind a proxy server, and your machine is also behind the same proxy server, then make sure that the web proxy preferences exclude the IP address you are trying to connect to.

To configure custom proxy setting:

  1. Choose Tool > Preferences, and select Web Browser and Proxy.

    For more information at any time, click F1 or Help from the Web Browser and Proxy dialog.

  2. Select the Proxy Settings tab to configure proxy settings.
  3. Select Manual Proxy Settings and enter the host and port name of the proxy server.
  4. List any host names or IP addresses that you want to exclude in the No Proxy for field.
  5. Click OK.

Disabling the Use of a Proxy Server When Accessing the Internet

You can disable the use of a proxy when accessing the Internet. This is the default behavior.

To disable the use of a proxy server when accessing the Internet:

  1. Choose Tool > Preferences, and select Web Browser and Proxy.

    For more information at any time, click F1 or Help from the Web Browser and Proxy dialog.

  2. Select the Proxy Settings tab to configure proxy settings.
  3. Select No Proxy.
  4. Click OK.

How to Set the Context Root for Web Services

The context root (also referred to as context path) appears as part of the web service endpoint for a generated web service, so it is important that it is set to an appropriate value.

The web service context root is the string that comes after the host:port portion of the web service URL. For example, if the deployed WSDL of a WebLogic web service is as follows: http://hostname:7001/financial/GetQuote?WSDL

The context path for this web service is financial.

At the project level, you can set the context root that will be assigned to the deployed Java EE web application on Integrated WebLogic Server. The context root value defaults to:

applicationname-projectname-context-root

To set the context root for web services:

  1. In the Applications window, right-click the project and choose Project Properties to open the Project Properties dialog.

    For more information at any time, click F1 or Help from the Project Properties dialog.

  2. Select Java EE Application.
  3. Select whether you want to use personal project settings or common project settings:

    • To use personal project settings, select Use Custom Settings and click the Customize Settings button.

    • To use common project settings, select Use Project Settings.

  4. Update the Java EE Web Context Root field to define the context root that will be assigned to the application when running or deploying the contents of the project as a Java EE web application on Integrated WebLogic Server.
  5. Click OK.

How to Configure Connections to Use with Web Services

You can develop simple web services that you can test using the Integrated WebLogic Server. However, to develop more complex web services, and to deploy web services, you will need the appropriate connections.

  • To deploy a web service to Oracle WebLogic Server, you need an application server connection as described in Deploying Web Services.

  • To find web services using a Universal Description, Discovery and Integration (UDDI) registry, you need to create a connection to the registry. For more information, see How to Define UDDI Registry Connections.

How to Work with Type Mappings

Objects that can be passed to and from web services have to be able to be serialized to an XML type, and then deserialized back to their original type. Objects that are automatically handled are Java primitive types and certain Java standard types. If you want to create a web service using objects that are not automatically serialized, you can write your own custom serializer.

The objects that can be passed to and from web services are objects that conform to the JavaBean conventions. For the purposes of web services, a JavaBean is any Java class that conforms to the following restrictions:

  • Must have a public default (zero argument) constructor.

  • Must expose all attributes of interest as accessors.

  • Order of the accessors for the properties (setMethod() and getMethod()) must not matter.

  • Accessors must be written in mixed case with a lower case first letter. For example, if an attribute is called name the accessors must be called getName and setName.

For more information, refer to the JavaBean spec at http://www.oracle.com/technetwork/java/javase/tech/index-jsp-138795.html.

For web services, each property of the object must be of one of the Java types that maps to an XML schema simple type. For a list of XML Schema data types and their corresponding Java data types, see “XML-to-Java Mapping for Built-in Data Types" in Oracle Fusion Middleware Developing JAX-WS Web Services for Oracle WebLogic Server. In addition, a service method can accept and return a single piece of XML element data, passed as an org.w3c.dom.Element.

JAX-WS web services use Java Architecture for XML Binding (JAXB), described at http://jcp.org/en/jsr/detail?id=222, to manage all of the data binding tasks. Specifically, JAXB binds Java method signatures and WSDL messages and operations and allows you to customize the mapping while automatically handling the runtime conversion. This makes it easy for you to incorporate XML data and processing functions in applications based on Java technology without having to know much about XML.

You can use the JAXB binding language to define custom binding declarations or specify JAXB annotations to control the conversion of data between XML and Java.

WebLogic Server provides two data binding and JAXB providers:

  • EclipseLink MOXy, the default in this release of WebLogic Server, is a fully compliant JAXB implementation. In addition to offering the standard JAXB features, EclipseLink MOXy provides useful extensions, such as the ability to use an external metadata file to configure the equivalent of JAXB annotations without modifying the Java source it refers to, and XPath based mapping. The JAXB enhancements can be used in the annotations on a service endpoint interface (SEI) or one of the value types used by the SEI. Users of JAXB in standalone mode can also take advantage of these features.

    Some of the additional extensions offered by EclipseLink MOXy include:

    • Extensions for mapping JPA entities to XML

    • Bidirectional mapping

    • Virtual properties

    • Ability to bootstrap from metadata and generate in-memory domain classes (Dynamic MOXy)

    For a web service, the EclipseLink MOXy extensions can be leveraged on the server side only, and only in the Java to WSDL scenario, in which the SEI and value types can use the extended EclipseLink functionality. For more information about these extensions and EclipseLink MOXy, see The EclipseLink MOXy (JAXB) User's Guide at http://wiki.eclipse.org/EclipseLink/UserGuide/MOXy.

    No configuration is required to use the EclipseLink MOXy providers.

  • Glassfish RI JAXB, which is the default Glassfish JAXB implementation, and was the default JAXB offering in WebLogic Server in previous releases. The Glassfish RI JAXB proprietary features will not work with EclipseLink MOXy. If desired, you can enable the Glassfish RI JAXB data binding and JAXB providers at the server or application level. For more information, see “Using the Glassfish RI JAXB Data Binding and JAXB Providers" in Oracle Fusion Middleware Developing JAX-WS Web Services for Oracle WebLogic Server.

For more information about using JAXB with JAX-WS web services, see “Using JAXB Data Binding" in Oracle Fusion Middleware Developing JAX-WS Web Services for Oracle WebLogic Server.

How to Choose Your Deployment Platform

The first time you create a web service in a project this dialog appears, and the version you select is used for all web services you create in the project.

For SOAP web services, this dialog also appears when you right-click an existing WSDL and select Create Web Service, and then choose to create a new web service project from that WSDL.

The first time you create a web service in a project, you are offered a choice of deployment platforms, as defined in Table 21-3 andTable 21-4 for SOAP and RESTful web services, respectively. The platform you choose determines the options available to you in the wizard, and the libraries that are added to the WAR/EAR file for deployment.

Note:

Java EE 7 is supported.

Table 21-3 lists the deployment platforms available for SOAP web services.

Table 21-3 Deployment Platforms for SOAP Web Services

Deployment Platform Description

Java EE 6 with support for JAX-WS Annotations

Generates a web service that takes advantage of the JAX-WS web services API, released as part of Java EE 1. 6. This option provides support for deploying to WebLogic Server with Java annotations using the JAX-WS annotation specification.

Java EE 6 with support for JAX-WS RI

Generates a JAX-WS web service for deploying to any container that supports the JAX-WS Reference Implementation. You can see more about the JAX-WS Reference Implementation at http://jax-ws.java.net/index.html.

Table 21-4 lists the deployment platforms available for RESTful web services.

Table 21-4 Deployment Platforms for RESTful Web Services

Deployment Platform Description

JAX-RS 1.0 Style

Generates a RESTful web service that is compatible with Jersey 1.18 (JAX-RS 1.1 RI).

JAX-RS 2.0 Style

Generates a RESTful web service that is compatible with Jersey 2.5.1 (JAX-RS 2.0 RI).

The Jersey 2.5.1 (JAX-RS 2.0 RI) shared library is auto-deployed to the Integrated WebLogic Server.

Note: You can attach OWSM policies to RESTful web services and clients that are built using Jersey 1.18 (JAX-RS 1.1 RI) RESTful web services and clients that are built using Jersey 2.5.1 (JAX-RS 2.0 RI) are secured using OWSM policies. For more information about securing RESTful web services and clients built using Jersey 2.5.1 (JAX-RS 2.0 RI), see "Securing RESTful Web Services and Clients" in Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server.

How to Work with Web Services Code Insight

When typing annotations in a Java class, the web services Code Insight completes annotations. The tool is also available for WSDL documents in the XML editor (when typing in the Source tab).

You can configure how fast Code Insight responds. You can access the Code Insight page in JDeveloper from Tools > Preferences > Code Editor > Code Insight.

When you create a JAX-WS web service from a Java class by adding annotations in the source editor, the Code Insight features of Quick Fixes and Code Assists are available to help you.

For example, when you create a web service from a Java class by manually adding the @WebService annotation, a ragged line appears under the annotation. Click the Audit Fix icon and choose Configure Project for Web Services.

From the Select Deployment Platform dialog, select one of the following JAX-WS platforms for your service:

  • Java EE 6, with support for JAX-WS Annotations. In this case, JDeveloper adds:

    • import javax.jws.WebService; statement to the class

    • web.xml file to the project

  • Java EE 6, with support for JAX-WS RI. In this case, JDeveloper adds:

    • import javax.jws.WebService; statement to the class

    • sun-jaxws.xml and web.xml files to the project

Note:

Java EE 7 is supported.

Other examples include:

  • You can add policy annotations to a JAX-WS web service and use JDeveloper to complete the policy you want. For example, if you enter @Pol, then click Alt+Enter you can choose whether to use @Policy, for a single policy, or @Policies for multiple policies. The appropriate import statement is also added to the class.

  • If you are working on a WSDL document in the source editor, you can use code completion to help you enter schema elements. For example, if you enter < and wait a second, a popup appears from which you can select the entry you want.

  • If the WSDL and web service source files get out-of-sync, you can regenerate the web service from source.

  • If you rename a Java class in the Java class, click the Audit fix icon and select how you would like to reconcile the discrepancy.

Working with Web Services in a UDDI Registry

Universal Description, Discovery and Integration (UDDI) is one of the standards and protocols that underpin web services. It provides a common standard for publishing and discovering information about web services. It contains a UDDI browser that searches a UDDI registry using search criteria that you specify to find web services that are described by WSDL. For more information about UDDI including the specification, see the UDDI OASIS standards at http://uddi.xml.org/.

The following sections describe how to work with web services in a UDDI registry:

How to Define UDDI Registry Connections

You can define connections to UDDI registries, for example, to browse your organization's internal UDDI registry. In addition, all defined UDDI registry connections are accessible to any workspace or project.

For more information about UDDI including the specification, see the UDDI OASIS standards at http://uddi.xml.org/.

The following sections describe how to define UDDI registry connections.

Creating UDDI Registry Connections

You can create a new connection to a UDDI registry that is public or private (within your organization). The UDDI registry connection is listed in the Resources window, in the Connections panel.

To create a UDDI registry connection:

  1. In the Applications window, select the project.
  2. Choose File > New > From Gallery to open the New Gallery.
  3. In the Categories tree, expand Business Tier and select Web Services.
  4. In the Items list, select UDDI Registry Connection and click OK to launch the Create UDDI Registry Connection wizard.

    For more information at any time, press F1 or click Help from within the Create UDDI Registry Connection wizard.

Editing the UDDI Registry Connections

You can edit an existing UDDI registry connection. For example, to change the name of the connection or the URL of the inquiry endpoint.

To edit the UDDI registry connection:

  1. In the main menu, choose Window > Resources. By default, the Resources window is displayed to the right of the JDeveloper window.
  2. In the Resources window, under IDE Connections, expand UDDI Registry.
  3. From the context menu of the UDDI registry connection you want to edit, choose Properties.

    The Edit UDDI Registry Connection wizard is launched.

    For more information at any time, press F1 or click Help from within the Edit UDDI Registry Connection wizard.

Changing the View of UDDI Registry Connections

You can change the order that web services are listed in the UDDI registry from Category view to Business view, or from Business View to Category view. For more information, see What You May Need to Know About Choosing the View for your UDDI Registry Connection.

To change the view of UDDI registry connections:

  1. In the main menu, choose Window > Resources. By default, the Resources window is displayed to the right of the JDeveloper window.
  2. In the Resources window, under IDE Connections, expand UDDI Registry.
  3. From the context menu of the UDDI registry connection you want to edit, choose Render Business Perspective or Render Category Perspective.

Refreshing the UDDI Registry Connections

You can refresh a UDDI registry connection to ensure that information stored under the connection is up-to-date.

To refresh the UDDI registry connection:

  1. In the main menu, choose Window > Resources. By default, the Resources window is displayed to the right of the JDeveloper window.
  2. In the Resources window, under IDE Connections, expand UDDI Registry.
  3. From the context menu of the UDDI registry connection you want to refresh, choose Refresh.

Deleting the UDDI Registry Connections

When no longer needed, you can delete a UDDI registry connection from the Resources window.

To delete a UDDI registry connection:

  1. In the main menu, choose Window > Resources. By default, the Resources window is displayed to the right of the JDeveloper window.
  2. In the Resources window, under IDE Connections, expand UDDI Registry.
  3. From the context menu of the UDDI registry connection you want to delete, choose Delete.
  4. A message is displayed asking whether you want to delete the connection. Click Yes.

What You May Need to Know About Choosing the View for your UDDI Registry Connection

When you create the connection, as described in How to Define UDDI Registry Connections, you are prompted whether the web services in the registry are displayed in Business View or Category View. The view you choose will determine how you search for services in the registry.

Choosing the Business View

A UDDI registry contains four data structure types that group information about web services:

  • Business Entities: Defines the top-level data structure that contains information about the business providing the web service. When you find a web service, the business is added to the UDDI browser in the Resources window.

  • Business Services: Contains descriptive information for a family of services, including the name and brief description, and category information.

  • Binding Templates: Contains information about a web service entry point and references to interface specification.

  • tModel: Represents the technical specification of the web service. When the Find Web Services wizard finds a web service, it also displays other web services that are compatible with the same tModel.

If you choose Business View, services are listed under Business Entities and Business Services.

Choosing Category View

If you choose Category View, you can search for web services based on one or more of the following categories:

  • ISO 3166: Search by location using the International Organization for Standardization (ISO) 3166 standard codes.

  • NAICS: Specify the type of industry using the North American Industry Classification System (NAICS).

  • SIC: Specify the type of industry using the Standard Industrial Classification (SIC).

  • UDDI Types: Search by UDDI type.

  • UDDI WSDL Types: Search by UDDI WSDL type.

  • UNSPSC: Search by type of service using the United Nations Standard Products and Services Code (UNSPC).

When you search by name, you can enter all or part of a name and you can use wildcards. The results are tModels where the name of the tModel matches the search criteria. When a number of web services have the same tModel, they are listed in the wizard so that you can choose the one that best fits your requirements.

How to Search for Web Services in a UDDI Registry

You can search a UDDI registry connection in the Resources window for a web service.

Note:

If you are creating a top-down web service, you can use the Find Web Service Wizard to search a UDDI registry connection from within the Create Java Web Service from WSDL wizard.

To search for a web service in a UDDI Registry:

  1. Create a UDDI registry connection, if required. For more information, see Creating UDDI Registry Connections.
  2. In the Resources window, search for the web service. For more information, see Working with the Resources Window.

How to Generate Proxies to Use Web Services Located in a UDDI Registry

You can create a proxy to a web service in a UDDI registry connection in the Resources window.

Note:

You can only generate a proxy to a web service if the service uses a WSDL link. To determine this, open the web service report, and check that the Overview Description in the tModel Instances section of the report is wsdl link.

To generate a proxy to use web services located in a UDDI registry:

  1. Open the Resources window.

    In the main menu, choose Window > Resources. By default, the Resources window is displayed to the right of the JDeveloper window.

  2. Navigate to the web service you want, or search for it.
  3. Navigate to the service endpoint (port).
  4. Right-click the service, and choose Generate Web Service Proxy to launch the Web Service Proxy wizard.

    For more information at any time, press F1 or click Help from within the wizard.

How to Display Reports of Web Services Located in a UDDI Registry

You can display a report of a web service in a UDDI registry.

To display a report of the web service located in a UDDI registry:

  1. Open the Resources window.

    In the main menu, choose Window > Resources. By default, the Resources window is displayed to the right of the JDeveloper window.

  2. Navigate to the web service you want, or search for it.
  3. Right-click the service, and choose View Report.

    A report of the web service is displayed in the source editor.

How to Publish Web Services to a UDDI Registry

You can publish a web service to a UDDI registry through a connection to the registry in the Application Server window. Before you can publish a service to a UDDI registry, you must already have a connection to the registry in the Resource Catalog. For more information, see Creating UDDI Registry Connections.

To publish a web service to a UDDI registry:

  1. Deploy the web service to Oracle WebLogic Server.

    Note:

    If you deploy the web service to the Integrated WebLogic Server, then the UDDI registry to which you are publishing must be local to the Integrated WebLogic Server.

  2. In Application Server window, expand the application server node.
  3. Expand the web services node and locate the node (which represents the WSDL) of the web service you want to publish.
  4. Right-click the WSDL node and choose Publish WSDL to UDDI to launch the Publish WSDL to UDDI Registry dialog.

    For more information at any time, press F1 or click Help in the Publish WSDL to UDDI Registry dialog.

Creating JAX-WS Web Services and Clients

To create JAX-WS web services and clients using JDeveloper, you can:

How to Create JAX-WS Web Services (Bottom-up)

Web services can be created using two development methods: top-down or bottom-up. Bottom-up development refers to the process of developing a web service from the underlying Java implementation using SOAP.

The following sections describe how to generate different types of web services from the bottom up:

For information about:

Creating Java Web Services

You can create web services from:

  • Java classes

  • Remote interface of EJBs

The web service creation wizards create the deployment files for you, so once you have created your web service the final step is to deploy it.

Before you begin:

If you have not already done so, set an appropriate context root for your web service. For more information, see How to Set the Context Root for Web Services.

To create the Java web service:

  1. In the Applications window, select the project containing the Java class or EJB from which you want to create a web service.
  2. Choose File > New > From Gallery to open the New Gallery.
  3. In the Categories list, expand Business Tier and select Web Services.
  4. In the Items list, select Java Web Service and click OK to launch the Create Java Web Service wizard.

    For detailed help about completing the wizard, press F1 or click Help from within the wizard.

Alternatively, you can launch the Create Java Web Service wizard by right-clicking on the Java class from which you want to create a web service and selecting Create Web service.

Note:

The Select Deployment Platform page is only displayed the first time a web service is created in a project. Thereafter, all additional web services in the same project will use the same version. For more information, see How to Choose Your Deployment Platform.

When using the Create Java Web Service wizard, if you enter a class name for a Java class that does not exist, the wizard provides the option to generate a default Java class, with a single String helloWorld(String) method, to be used as the implementation class for the web service. If you decline to generate the default Java class, you will be prompted to select a valid class name.

Using Web Service Annotations

The JSR-181 specification specifies web services metadata, which allows you to use annotations declaratively to make creating and managing web services easier. You use the annotations for methods and classes in order to expose these methods as web service endpoints.

You can add annotations to a class manually, choose to have JDeveloper add them to the class when creating the web service, or add them when editing the web service using the Edit Web Services dialog.

For more information, see the following references:

Note:

If you delete the annotations using the Edit Web Services dialog, any annotations that you entered manually are also deleted.

To use web service annotations:

  1. Open the Java class in the source editor.
  2. On the line where you want to add the annotation, type @ and pause for a couple of seconds.

    Code Insight displays possible values. For more information, see How to Work with Web Services Code Insight.

Using the Properties Window

You can add the @WebService annotation and supporting files to your web service project automatically using the Properties window.

To create a JAX-WS web service in the Properties window:

  1. With the web service class open in the source editor, choose Window > Properties to open the Properties window.

    For more information at any time, press F1 or click Help from within the Properties window.

  2. With the cursor in the public class, navigate to the JAX-WS node in the Properties window.
  3. Select Web Service Bean Class.

    The Select Deployment Plan Platform dialog box is displayed. For information about selecting the deployment platform, see How to Choose Your Deployment Platform.

  4. Select a deployment platform and click OK.

    The javax.jws.WebService annotation is imported and added to the public class of the web service, and the required deployment files (for example, web.xml) are added to your project.

Creating TopLink Database Web Service Providers

The Create TopLink DB Web Service Provider wizard enables you to build a JAX-WS web service provider for a TopLink database to perform one of the following tasks:

  • Access stored procedures and functions

  • Execute an SQL query

  • Perform CRUD operations on a table

Based on the type of service selected, the wizard generates a web service Provider and WSDL document that can be deployed to an application server, such as Oracle WebLogic Server. Deploying TopLink web service Providers is similar to deploying other J2EE Web applications. For more information, see Deploying Web Services.

It should be noted that:

  • The wizard generates a JAX-WS web service Provider.

  • If you edit the TopLink web service provider, ensure that the database connection still exists; otherwise an error message is returned. If you have deleted the database connection, create a new one with the same name as the original connection.

To create the TopLink DB web service Provider from a project:

  1. In the Applications window, select the project.
  2. Choose File > New > From Gallery to open the New Gallery.
  3. In the Categories list, expand Business Tier and select Web Services. In the Items list, double-click TopLink DB Web Service Provider to launch the Create TopLink Web Service Provider wizard.

    For detailed help about completing the wizard, press F1 or click Help from within the wizard.

Regenerating Web Services from Source

There are times that you may need to regenerate your web service. For example, if the source from which the service was originally generated has changed.

Note:

When you regenerate the web service, JDeveloper discards any changes that you have made to the WSDL since it was last generated.

After you regenerate the web service, you may need to regenerate the client to the web service. Otherwise, you may get compilation errors (when the client is in the same project as the web service), or run-time errors (when the client is in a different project to the web service).

If you are not using annotations and change the name of the method in the underlying class, when you regenerate the service you will receive an error message indicating that no methods were selected. Because methods are tracked using namespaces, if you modify the namespace JDeveloper is not able to determine what needs to be regenerated. To correct this error, double-click the web service container to open the Web Services Editor, go to the Methods page, and select the methods on which to base the web service.

To regenerate a web service from source:

  1. In the Applications window, right-click the web service container you want to regenerate.
  2. Choose Regenerate Web Service from Source from the context menu.

    The service is automatically regenerated, and any changes you made to the WSDL since it was last generated are lost.

Using Handlers

JDeveloper allows you to specify the handler classes to edit with the web service message. The handlers can use initialized parameters, SOAP roles, or SOAP headers. For more information about creating SOAP handlers, see “Creating and Using SOAP Message Handlers" in Oracle Fusion Middleware Developing JAX-WS Web Services for Oracle WebLogic Server.

To define handlers:

  1. Create a web service. For more information, see Creating Java Web Services .

    Alternatively, open the web service editor. For more information, see How to Edit JAX-WS Web Services.

  2. In the Handler Details page, enter the values you want to use.

    For more information at any time, press F1 or click Help from within the dialog.

Handling Overloaded Methods

If the Java class on which you base a web service has overloaded methods, JDeveloper handles them automatically.

For JAX-WS web services, you can use the @WebMethod annotation to change the name of an overloaded method. For example:

public class SimpleImpl {
   @WebMethod(operationName="sayHelloOperation")
   public String sayHello(String message) {
      System.out.println("sayHello:" + message);
      return "Here is the message: '" + message + "'";
   }
...
}

In the example, the sayHello() method of the SimpleImpl JWS file is exposed as a public operation of the web service. The operationName attribute specifies, however, that the public name of the operation in the WSDL file is sayHelloOperation.

For more information about @WebMethod, see “Specifying That a JWS Method Be Exposed as a Public Operation (@WebMethod and @OneWay Annotations)" in Oracle Fusion Middleware Developing JAX-WS Web Services for Oracle WebLogic Server.

How to Create JAX-WS Web Services from WSDL (Top-down)

JDeveloper allows you to develop top-down web services, that is, starting with the WSDL. JDeveloper will generate a service implementation and its deployment descriptors. You can browse to a WSDL in the file system, or locate a web service in a UDDI registry connection in the Resources window.

To create a JAX-WS web service from WSDL (top-down):

  1. In the Applications window, select the project in which you want to create the web service.
  2. Choose File > New > From Gallery to open the New Gallery.
  3. In the Categories list, expand Business Tier and select Web Services. In the Items list, double-click Java Web Service From WSDL to launch the Create Java Web Service from WSDL wizard.

    For detailed help about completing the wizard, press F1 or click Help from within the wizard.

    The JAX-WS web service is created and the Java implementation class is opened automatically in the editor.

    Note:

    You can also create a web service from a WSDL by right-clicking an existing WSDL and selecting Create Web Service from the context menu. You will also have the option to create a new web service project from that WSDL

How to Create JAX-WS Web Service Clients

JDeveloper makes it easy to use a web service in your application by allowing you to create JAX-WS client and proxy classes to access the service using the Create Web Service Client and Proxy wizard. You can launch the wizard when you locate or create a web service. Alternatively, you can launch the wizard directly and enter the URL for the web service or use the Find Web Service wizard to locate a web service in a UDDI registry.

JDeveloper automatically generates the correct type of proxy for an RPC or document style web service.

Note:

JAX-WS web services do not support RPC style.

For more information about:

The following sections describe how to create and use JAX-WS web service clients:

See also the following sections describing how to view and manage the WSDL used to create the web service client:

Creating the Client and Proxy Classes

Use JDeveloper to automatically create a client and proxy classes to access a web service and call its methods in your application. Using the wizard, you can also generate asynchronous methods, attach policies, and define SOAP handlers, as required.

You can create a client and proxy classes to access a web service using the Create Web Service Client and Proxy wizard. The wizard generates a new service class (JAX-WS) and service interface for each exposed port and lists them in the Applications window. It opens the generated client file port-nameClient.java in the source editor. Once generated, you can call the methods in your application.

Note:

In some cases, you may encounter errors when you run a web service client that you have created for a web service accessed on the Internet or using a UDDI registry. Because web services standards are still evolving, it is possible that the web services that you locate may not conform to the latest standards, or the standards to which they conform may not be compatible with those supported by the server on which the client is running. If a web service client that you have created in JDeveloper returns an error, examine the error message and consider creating a client to another web service that provides a similar service, but that is compatible with the server and will run without problems.

You can access the Create Web Service Client and Proxy wizard using one of the following methods. For help in completing the wizard, press F1 or click Help from within the wizard.

Creating Client and Proxy Classes to Access a Web Service

You can generate client and proxy classes for a web service that is defined outside of JDeveloper by launching the Create Web Service Client Proxy wizard and specifying the WSDL for the web service.

To create client and proxy classes to access a web service:

  1. In the Applications window, select the project you want to use.
  2. Choose File > New > From Gallery to open the New Gallery.
  3. In the Categories list, select Web Services.
  4. In the Items list, double-click Web Service Client and Proxy to launch the Create Web Service Client and Proxy wizard.

    For more information at any time, press F1 or click Help from within the Create Web Service Client and Proxy wizard.

Creating Client and Proxy Classes to Access a Web Service Defined in JDeveloper

You can generate client and proxy classes for a web service that is currently defined in JDeveloper from the Applications window.

To create a client and proxy classes to access a web service defined in JDeveloper:

Right-click the web service container in the Applications window, and choose Create Client for Web Service Annotations.

The Create Web Service Client and Proxy wizard opens and is pre-populated with the selected web service project.

Note:

When you create the client and proxy classes for an EJB web service that uses JavaBean parameters, the JavaBean must implement the java.io.Serializable interface.

Developing a JAX-WS Web Service Client Application

JDeveloper generates a number of files that define a proxy to the web service. Using the generated files, you can develop the following types of web service client applications:

  • Standalone client application

  • Java Standard Edition (SE) client application

  • Java EE component deployed to Oracle WebLogic Server

Note:

In addition to the procedures described below, you can use web service injection (using the @WebServiceRef method) to define a reference to a web service and identify an injection target in your web service client. For more information see Referencing Web Services Using the @WebServiceRef Annotation

Developing a Standalone Client Application

A standalone client application, in its simplest form, is a Java program that has the Main public class that you invoke with the java command. It runs completely separate from .

To develop a standalone client application:

  1. Open the client proxy class, called port_nameClient.java, in the source editor.

    This file opens automatically when you create the web service client proxy initially. To re-open the class, right-click on the client proxy container and select Go to Client Class or simply double-click on the file in the Applications window.

  2. Locate the comment // Add your code to call the desired methods, and add the appropriate code to invoke the web service.

  3. Run the client.

Developing a Java Standard Edition (SE) Client Application

Include the generated proxy classes as part of a Java Standard Edition (SE) application and reference them to access the remote web service.

To develop a Java SE client application:

  1. Copy the generated client proxy classes to your Java SE application source directory.

  2. Using the main client proxy class, called port_nameClient.java, as your guide, add appropriate methods to access the web service from your application.

  3. Run the application.

Developing a Java EE Component Client Application Deployed to

This type of web service runs inside a Java Platform, Enterprise Edition (Java EE) Version 6 component deployed to , such as an EJB, servlet, or another web service. A JEE web service client application, therefore, runs inside a container.

To develop a Java EE component client application deployed to WebLogic Server:

  1. Open the main client proxy class, called port_nameClient.java, in the source editor.

    This file opens automatically when you create the web service client proxy initially. To re-open the class, right-click on the client proxy container and select Go to Client Class or simply double-click on the file in the Applications window.

  2. Replace the main method with your own method(s) to access the web service and perform required operations. You can use the code generated in the main method as a guide.

  3. Deploy the full set of client module classes that JDeveloper has generated.

  4. Reference the client proxy class in your Java EE application.

Referencing Web Services Using the @WebServiceRef Annotation

When you use the javax.xml.ws.WebServiceRef annotation, you can inject a reference to a web service into any container-managed Java class.

To add a @WebServiceRef annotation to your Java class quickly and easily, right-click within the Java class editor at the location you want to inject the web service reference, and select one of the following options:

  • Select Create Proxy and Insert Reference from the context menu.

    This command invokes the Create Web Service Client and Proxy wizard, enabling you to generate a web service client and proxy classes. Then, the javax.xml.ws.WebServiceRef and web service proxy classes are imported automatically and a reference to the selected web service is injected at the specified location.

  • Select Insert Proxy Reference from the context menu, then select an existing web service proxy from the drop-down list.

    The javax.xml.ws.WebServiceRef and web service proxy classes are imported automatically and a reference to the selected web service is injected at the specified location. If no web service proxy classes are currently available, then this option is greyed out.

The following excerpt provides an example of the code that is automatically added to the Java class:

import java.xml.ws.WebServiceRef;
import ratingservice.CreditRatingService;
...
/**
 ** Injectable field for service WebServiceClient
**/
@WebServiceRef
CreditRatingService creditRatingService1;
...

For more information, see “Defining a Web Service Reference Using the @WebServiceRef Annotation" in Oracle Fusion Middleware Developing JAX-WS Web Services for Oracle WebLogic Server.

Enabling Web Service Atomic Transactions in a Web Service Client

For more information about web service atomic transactions, see How to Use Web Service Atomic Transactions.

You can enable web service atomic transactions in a web service client's injectable target.

To enable web service atomic transactions in a web service client's injectable target:

  1. Open the web service client in the source editor.
  2. Right-click on the @WebServiceRef annotation or injectable target and select Add Transactional from the menu.

    The @Transactional annotation is added to the web service client.

  3. You can specify the version and flow type values as follows: 
    @Transactional(version=Transactional.Version.[WSAT10|WSAT11|WSAT12|DEFAULT],
           value=Transactional.TransactionFowType.[MANDATORY|SUPPORTS|NEVER])

    For more information about the configuration options, see Table 21-5.

Regenerating Web Service Client and Proxy Classes

There are times that you may need to regenerate the web service client and proxy classes. For example, if the web service has been updated since they were last generated.

Note:

When you regenerate the web service client and proxy classes, JDeveloper discards any changes that you have made to the class, WSDL, or supporting files since the client was last generated.

To regenerate the web service client and proxy classes:

You can regenerate the web service client and proxy classes quickly and easily using the set of properties last defined in the Web Service Client and Proxy Editor wizard and the current locally stored WSDL, as follows:

  • In the Applications window, right-click the web service client node that you want to regenerate and choose Regenerate Web Service Proxy from the context menu.

    The web service client class, WSDL, and supporting proxy files are regenerated.

Editing the Web Service Clients

You can edit a web service client using the Web Service Client and Proxy editor.

To edit a web service client:

  • Double-click on the web service client container within the Applications window.

  • Right-click on the client within the Applications window, and select Properties....

For help in completing the wizard, press F1 or click Help from within the wizard.

Deleting the Web Service Clients

Once no longer needed, you can delete web service clients.

To delete a web service client:

  1. In the Applications window, right-click on the web service client container, and select Delete.

    The Delete Proxy? dialog displays.

  2. Ensure that the appropriate files are selected in the dialog box. Click Select All or Deselect All to select or deselect all proxy files.
  3. Choose OK.

    The files are permanently erased.

How to Use Web Service Atomic Transactions

WebLogic web services enable interoperability with other external transaction processing systems, such as Websphere, JBoss, Microsoft .NET, and so on, through the support of the following specifications:

These specifications define an extensible framework for coordinating distributed activities among a set of participants. The coordinator is the central component, managing the transactional state (coordination context) and enabling web services and clients to register as participants. For more information about web service atomic transactions, see “Using Web Services Atomic Transactions" in Oracle Fusion Middleware Developing JAX-WS Web Services for Oracle WebLogic Server.

To enable atomic transactions for a web service implementation at the class level or synchronous method level (for two-way methods only) use one of the following methods:

To enable atomic transactions for web service clients use one of the following methods:

  • Right click on the @WebServiceRef annotation or web service injectable target, and select Add Transactional from the menu to add the @Transactional annotation.

  • Pass the weblogic.wsee.wstx.wsat.TransactionalFeature as a parameter when creating the web service proxy or dispatch. For more information, see “Using Web Services Atomic Transactions" in Oracle Fusion Middleware Developing JAX-WS Web Services for Oracle WebLogic Server.

When enabling web service atomic transactions, configure the following information:

  • Version: Version of the web service atomic transaction coordination context that is used for web services and clients. For clients, it specifies the version used for outbound messages only. The value specified must be consistent across the entire transaction. Valid values include WSAT10, WSAT11, and WSAT12, and DEFAULT. The DEFAULT value for web services is all three versions (driven by the inbound request); the DEFAULT value for web services clients is WSAT10.

  • Flow type: Flag that specifies whether the coordination context is passed with the transaction flow. The following table summarizes the valid values and their meaning on the web service and client. The table also summarizes the valid value combinations when configuring web service atomic transactions for an EJB-style web service that uses the @TransactionAttribute annotation.

Table 21-5 Transaction Configurations

Value Web Service Client Web Service Valid EJB @TransactionAttribute Values

NEVER

JTA transaction: Do not export transaction coordination context.

No JTA transaction: Do not export transaction coordination context.

Transaction flow exists: Do not import transaction coordination context. If the CoordinationContext header contains mustunderstand="true", a SOAP fault is thrown.

No transaction flow: Do not import transaction coordination context.

NEVER, NOT_SUPPORTED, REQUIRED, REQUIRES_NEW, SUPPORTS

SUPPORTS (Default)

JTA transaction: Export transaction coordination context.

No JTA transaction: Do not export transaction coordination context.

Transaction flow exists: Import transaction context.

No transaction flow: Do not import transaction coordination context.

SUPPORTS, REQUIRED

MANDATORY

JTA transaction: Export transaction coordination context.

No JTA transaction: An exception is thrown.

Transaction flow exists: Import transaction context.

No transaction flow: Service-side exception is thrown.

MANDATORY, REQUIRED, SUPPORTS

You can enable web service atomic transactions from a Java class, the Properties window, or a web service client's injectable target, as described in the following sections.

Enabling Web Service Atomic Transactions in a Java Class

You can enable web service atomic transactions in a Java class.

To enable web service atomic transactions in the Java class:

  1. Open the web service class in the source editor.
  2. Start typing the annotation, for example, @Transactional. When you pause, or click Ctrl+Shift+Space, a popup appears from which you can choose the correct entry to complete the statement.
  3. You can specify the version and flow type values as follows: 
    @Transactional(version=Transactional.Version.[WSAT10|WSAT11|WSAT12|DEFAULT],
        value=Transactional.TransactionFowType.[MANDATORY|SUPPORTS|NEVER])

Enabling Web Service Atomic Transactions in the Properties Window

You can enable web service atomic transactions in the Properties window.

To enable web service atomic transactions in the Properties window:

  1. With the web service class open in the source editor, choose Window > Properties to open the Properties window.

    For more information at any time, press F1 or click Help from within the Properties window.

  2. With the cursor in the public class, @WebService, or two-way method line of the class, navigate to the JAX-WS Extensions node in the Properties window.
  3. Select Add Transactional.

    The Properties window is refreshed to display options to enable or disable the feature, and to set the flow type and version. For more information about the configuration options, see Table 21-5.

  4. Select a flow type from the Flow Type drop-down list. Valid values include: Supports, Never, and Mandatory. This field defaults to Supports.
  5. Select a version from the Version drop-down list. Valid values include: WS-AT 1.0, WS-AT 1.1, WS-AT 1.2, and Default. The Default value for web services is all three versions (driven by the inbound request); the Default value for web services clients is WS-AT 1.0.

The @Transactional annotation is imported and added to the public class.

Enabling Web Service Atomic Transactions in a Web Service Client's Injectable Target

You can enable web service atomic transactions in a web service client's injectable target.

To enable web service atomic transactions in a web service client's injectable target:

  1. Open the web service client in the source editor.
  2. Right-click on the @WebServiceRef annotation or injectable target and select Add Transactional from the menu.

    The @Transactional annotation is added to the web service client.

  3. You can specify the version and flow type values as follows: 
    @Transactional(version=Transactional.Version.[WSAT10|WSAT11|WSAT12|DEFAULT],
           value=Transactional.TransactionFowType.[MANDATORY|SUPPORTS|NEVER])

    For more information about the configuration options, see Table 21-5.

How to Use SOAP Over JMS Transport

Typically, web services and clients communicate using SOAP over HTTP/S as the connection protocol. You can, however, configure a WebLogic web service so that client applications use JMS as the transport.

Using SOAP over JMS transport, web services and clients communicate using JMS destinations instead of HTTP connections, offering the following benefits:

  • Reliability

  • Scalability

  • Quality of service

As with web service reliable messaging, if WebLogic Server goes down while the method invocation is still in the queue, it will be handled as soon as WebLogic Server is restarted. When a client invokes a web service, the client does not wait for a response, and the execution of the client can continue. Using SOAP over JMS transport does require slightly more overhead and programming complexity than HTTP/S.

For each transport that you specify, WebLogic Server generates an additional port in the WSDL. For this reason, if you want to give client applications a choice of transports they can use when they invoke the web service (JMS, HTTP, or HTTPS), you should explicitly configure each transport.

Note:

SOAP over JMS transport is not compatible with the following web service features: reliable messaging and HTTP transport-specific security.

You can enable SOAP over JMS transport from a Java class, the Properties window, or a web service client, as described in the following sections.

For more information about SOAP over JMS transport, see “Using SOAP Over JMS Transport" in Oracle Fusion Middleware Developing JAX-WS Web Services for Oracle WebLogic Server.

Developing Web Services Using JMS Transport

To develop web services using JMS transport, use one of the following methods:

Enabling JMS Transport in the Properties Window

To simplify configuration, you can enable JMS transport in the Properties window.

To enable JMS transport in the Properties window:

  1. With the web service class open in the source editor, choose Window > Properties to open the Properties window.

    For more information at any time, press F1 or click Help from within the Properties window.

  2. With the cursor in the public class, @WebService, or two-way method line of the class, navigate to the JMS node in the Properties window.

  3. Select JMS.

    The Properties window is refreshed to display options to configure SOAP over JMS transport. For more information about the configuration options, see Table 21-6.

  4. Configure the JMS transport properties, as required.

When enabling JMS transport, you can configure the properties defined in the following table.

Table 21-6 Configuration Properties for SOAP Over JMS Transport

Name Description

Activation Properties

Activation configuration properties passed to the JMS provider. To edit the activation properties, click ... to open the Edit Property: Activation Properties dialog and specify values in the Value column for the activation properties.

For a list of activation properties that are supported, see “Configuring JMS Transport Properties" in Oracle Fusion Middleware Developing JAX-WS Web Services for Oracle WebLogic Server.

Binding Version

Version of the SOAP JMS binding. This value must be set to SOAP JMS 1.0 for this release, which equates to com.oracle.webservices.api.jms.JMSConstants.SOAP11_JMS_BINDING.

This value maps to the SOAPJMS_bindingVersion JMS message property.

Delivery Mode

Delivery mode indicating whether the request message is persistent. Valid values are Persistent and Non-Persistent. This value defaults to Persistent.

Destination Name

JNDI name of the destination queue or topic. This value defaults to com.oracle.webservices.jms.RequestQueue.

Destination Type

Destination type. Valid values include: Queue or Topic. This value defaults to Queue.

This value overrides the destinationType value specified as an entry in the Activation Properties field, if applicable.

Topics are supported only for one-way communication.

Enable WSDL Access

Boolean flag that specifies whether to publish the WSDL through HTTP. This flag defaults to true.

Header Property

JMS header properties. Each property is specified using name-value pairs, separated by semicolons (;). For example: name1=value1;...;nameN=valueN.

Message Property

JMS message properties. Each property is specified using name-value pairs, separated by semicolons (;). For example: name1=value1;...;nameN=valueN.

Connection Factory

JNDI name of the connection factory that is used to establish a JMS connection. This value defaults to com.oracle.webservices.jms.ConnectionFactory.

Context Parameters

JNDI properties. Each property is specified using name-value pairs, separated by semicolons (;). For example: name1=value1;...;nameN=valueN.

The properties are added to the java.util.Hashtable sent to the InitialContext constructor for the JNDI provider.

Context Factory

Name of the initial context factory class for the JNDI lookup. This value maps to the java.naming.factory.initial property. This value defaults to weblogic.jndi.WLInitialContextFactory.

URL

JNDI provider URL. This value defaults to t3://localhost:7001.

This value maps to the java.naming.provider.url property.

MDB per Destination

Boolean flag that specifies whether to create one listening message-driven bean (MDB) for each requested destination. This value defaults to true.

If set to false, one listening MDB is created for each web service port, and that MDB cannot be shared by other ports.

Message Type

Message type to use with the request message. Valid values are Bytes and Text. This value defaults to Bytes.

For more information about configuring the message type, see “Configuring the JMS Message Type" in Oracle Fusion Middleware Developing JAX-WS Web Services for Oracle WebLogic Server.

Priority

JMS priority associated with the request and response message. Specify this value as a positive Integer from 0, the lowest priority, to 9, the highest priority. The default value is 0.

Reply to Name

JNDI name of the JMS destination to which the response message is sent.

For a two-way operation, a temporary response queue is generated by default. Using the default temporary response queue minimizes the configuration that is required. However, in the event of a server failure, the response message may be lost.

This attribute enables the client to use a previously defined, “permanent" queue or topic rather than use the default temporary queue or topic, for receiving replies. For more information about configuring the JMS response queue, see “Configuring the JMS Response Queue" in Oracle Fusion Middleware Developing JAX-WS Web Services for Oracle WebLogic Server.

The value maps to the JMSReplyTo JMS header in the request message.

Run as Principle Name

Principal used to run the listening MDB.

Run as Role

Role used to run the listening MDB.

Target Service

Port component name of the web service. This value is used by the service implementation to dispatch the service request. If not specified, the service name from the WSDL or javax.jws.WebService annotation is used.

This value maps to the SOAPJMS_targetService JMS message property.

Time to Live

Lifetime, in milliseconds, of the request message. A value of 0 indicates an infinite lifetime. If not specified, the JMS-defined default value (0) is used.

On the service side, this value also specifies the expiration time for each MDB transaction.

Developing Web Service Clients Using JMS Transport

To develop web service clients using JMS transport, use one of the following methods:

For more information about these methods, see “Invoking a WebLogic Web Service Using JMS Transport" in Oracle Fusion Middleware Developing JAX-WS Web Services for Oracle WebLogic Server.

How to Use Fast Infoset for Optimizing XML Transmission

Fast Infoset is a compressed binary encoding format that provides a more efficient serialization than the text-based XML format. Fast Infoset optimizes both document size and processing performance.

When enabled, Fast Infoset converts the XML Information Set in the SOAP envelope into a compressed binary format before transmitting the data. Fast Infoset optimizes encrypted and signed messages, MTOM-enabled messages, and SOAP attachments, and supports both HTTP and JMS transports.

The Fast Infoset specification, ITU-T Rec. X.891 and ISO/IEC 24824-1 (Fast Infoset) is defined by both the ITU-T and ISO standards bodies. The specification can be downloaded from the ITU Web site: http://www.itu.int/rec/T-REC-X.891-200505-I/en

The Fast Infoset capability is enabled on all web services, by default. For web service clients, Fast Infoset is enabled if it is enabled on the web service and advertised in the WSDL.

The following sections describe how to enable and disable Fast Infoset explicitly on web services and clients:

Configuring Fast Infoset on Web Services

The Fast Infoset capability is enabled on all web services, by default.

You can explicitly enable (for example, to ensure the feature is not disabled by a global policy attachment), disable. and configure Fast Infoset for a web service using the following methods:

Configuring Fast Infoset in a Java Class

You can enable Fast Infoset in a Java class.

To configure Fast Infoset in the Java class:

  1. Open the web service class in the source editor.

  2. Start typing the annotation, for example, @FastInfosetService. When you pause, or click Ctrl+Shift+Space, a popup appears from which you can choose the correct entry to complete the statement.

  3. You can specify explicitly whether the feature is enabled or disabled using the enabled attribute, as shown in the following example.

    package examples.webservices.hello_world;
import javax.jws.WebService;
import com.oracle.webservices.api.FastInfosetService;
 
@WebService(name="HelloWorldPortType", serviceName="HelloWorldService")
@FastInfosetService(enabled=true)
 
public class HelloWorldImpl {
  public String sayHelloWorld(String message) {
  try {
    System.out.println("sayHelloWorld:" + message);
  } catch (Exception ex) { ex.printStackTrace(); }
    return "Message from FI Enabled Service: '" + message + "'"; 
  }
}
Configuring Fast Infoset in the Web Service Wizard

You can enable Fast Infoset in the web service wizard when creating a new web service or in the web service editor when updating a web service that already exists.

For more information about creating web services using the Create Java Web Service Wizard, see Creating Java Web Services .

To configure Fast Infoset in the web service wizard:

In the Create Java Web Service wizard or web service editor, navigate to the Message Format page and select the Enable Fast Infoset checkbox. For more information at any time, press F1 or click Help from within the dialog.

Configure Fast Infoset in the Properties Window

You can enable Fast Infoset in the Properties window.

To configure Fast Infoset in the Properties window:

  1. With the web service class open in the source editor, choose Window > Properties to open the Properties window.

    For more information at any time, press F1 or click Help from within the Properties window.

  2. With the cursor in the public class or @WebService line of the class, navigate to the JAX-WS Extensions node in the Properties window.

  3. Select Enable Fast Infoset.

The @FastInfosetService annotation is imported and added to the public class.

Configuring Fast Infoset on Web Service Clients

For web service clients, Fast Infoset is enabled if it is enabled on the web service and advertised in the WSDL.

You can explicitly enable, disable. and configure Fast Infoset for a web service client by passing the com.oracle.webservices.api.FastInfosetClientFeature as a parameter when creating the web service proxy or dispatch.For more information about configuring the content negotiation strategy, see "Configuring the Content Negotiation Strategy" in Oracle Fusion Middleware Developing JAX-WS Web Services for Oracle WebLogic Server.

The following code excerpt provides an example of using the com.oracle.webservices.api.FastInfosetClientFeature feature class to enable and configure Fast Infoset on a web service at design time.

package examples.webservices.hello_world.client;
 
import javax.xml.namespace.QName;
import java.net.MalformedURLException;
import java.net.URL;
import com.oracle.webservices.api.FastInfosetClientFeature;
import com.oracle.webservices.api.FastInfosetContentNegotiationType;
 
public class Main {

public static void main(String[] args) {
    HelloWorldService service;
    FastInfosetContentNegotiationType clientNeg  = 
        FastInfosetContentNegotiationType.PESSIMISTIC;
    FastInfosetClientFeature feature =
FastInfosetClientFeature.builder().fastInfosetContentNegotiation(clientNeg).enabled(true).build();
          try {
      service = new HelloWorldService(new URL(args[0] + "?WSDL"), new QName("http://hello_world.webservices.examples/", "HelloWorldService") );
    } catch (MalformedURLException murl) { throw new RuntimeException(murl); }
      HelloWorldPortType port = service.getHelloWorldPortTypePort(feature);
 
      String result = null;
      result = port.sayHelloWorld("Hi there!");
      System.out.println( "Got result: " + result );
  }
}

To disable Fast Infoset on the client, set the enabled flag to false or set the content negotiation strategy to NONE on the Feature class.

Disabling Fast Infoset on Web Services and Clients

At design time, to disable Fast Infoset explicitly:

The following code excerpt provides an example of using the com.oracle.webservices.api.FastInfosetService annotation to disable Fast Infoset on a web service at design time.

package examples.webservices.hello_world;
import javax.jws.WebService;
import com.oracle.webservices.api.FastInfosetService;
 
@WebService(name="HelloWorldPortType", serviceName="HelloWorldService")
@FastInfosetService(enabled=false)
 
public class HelloWorldImpl {
  public String sayHelloWorld(String message) {
  try {
    System.out.println("sayHelloWorld:" + message);
  } catch (Exception ex) { ex.printStackTrace(); }
    return "Message from FI Enabled Service: '" + message + "'"; 
  }
}

How to Use MTOM for Optimizing Binary Transmission

SOAP Message Transmission Optimization Mechanism/XML-binary Optimized Packaging (MTOM/XOP) defines a method for optimizing the transmission of XML data of type xs:base64Binary or xs:hexBinary in SOAP messages. When the transport protocol is HTTP, Multipurpose Internet Mail Extension (MIME) attachments are used to carry that data while at the same time allowing both the sender and the receiver direct access to the XML data in the SOAP message without having to be aware that any MIME artifacts were used to marshal the base64Binary or hexBinary data.

The binary data optimization process involves the following steps:

  1. Encode the binary data.

  2. Remove the binary data from the SOAP envelope.

  3. Compress the binary data.

  4. Attach the binary data to the MIME package.

  5. Add references to the MIME package in the SOAP envelope.

MTOM/XOP support is standard in JAX-WS via the use of JWS annotations. The MTOM specification does not require that, when MTOM is enabled, the Web service runtime use XOP binary optimization when transmitting base64binary or hexBinary data. Rather, the specification allows the runtime to choose to do so. This is because in certain cases the runtime may decide that it is more efficient to send the binary data directly in the SOAP Message; an example of such a case is when transporting small amounts of data in which the overhead of conversion and transport consumes more resources than just inlining the data as is.

The following Java types are mapped to the base64Binary XML data type, by default: javax.activation.DataHandler, java.awt.Image, and javax.xml.transform.Source. The elements of type base64Binary or hexBinary are mapped to byte[], by default.

The following sections describe how to enable MTOM on web services and clients:

Enabling MTOM on Web Services

You can enable MTOM for a web service using the following

Enabling MTOM in a Java Class

You can enable MTOM in a Java class.

To enable MTOM in the Java class:

  1. Open the web service class in the source editor.

  2. Start typing the annotation, for example, @MTOM. When you pause, or click Ctrl+Shift+Space, a popup appears from which you can choose the correct entry to complete the statement.

The following provides an example of enabling MTOM on a web service:

package examples.webservices.mtom;

import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.xml.ws.soap.MTOM; 

@MTOM
@WebService(name="MtomPortType",
            serviceName="MtomService",
            targetNamespace="http://example.org")
public class MTOMImpl { 
  @WebMethod
  public String echoBinaryAsString(byte[] bytes) {
    return new String(bytes);

  }
}
Enabling MTOM by Attaching a WebLogic Web Service Policy

You can enable MTOM by attaching a WebLogic web service policy, as described in "Enabling MTOM on the Web Services by Attaching a WS-Policy File" in Oracle Fusion Middleware Developing JAX-WS Web Services for Oracle WebLogic Server.

Enabling MTOM in the Web Service Wizard

You can enable MTOM in the web service wizard when creating a new web service or in the web service editor when updating a web service that already exists.

For more information about creating web services using the Create Java Web Service Wizard, see Creating Java Web Services .

To enable MTOM in the web service wizard, in the Create Java Web Service wizard or web service editor, navigate to the Message Format page and select the Enable MTOM checkbox. For more information at any time, press F1 or click Help from within the dialog.

Enabling MTOM in the Properties Window

You can enable MTOM in the Properties window.

To enable MTOM in the Properties window:

  1. With the web service class open in the source editor, choose Window > Properties to open the Properties window.

    For more information at any time, press F1 or click Help from within the Properties window.

  2. With the cursor in the public class or @WebService line of the class, navigate to the JAX-WS node in the Properties window.

  3. Select Enable MTOM.

The @FastInfosetService annotation is imported and added to the public class.

Enabling MTOM on Web Service Clients

To enable MTOM on the client of the Web service, pass an instance of the javax.xml.ws.soap.MTOMFeature as a parameter when creating the Web service proxy or dispatch, as illustrated in the following example. Relevant code is shown in bold.

package examples.webservices.mtom.client;

import javax.xml.ws.soap.MTOMFeature;

public class Main {
  public static void main(String[] args) {
    String FOO = "FOO";
    MtomService service = new MtomService()
    MtomPortType port = service.getMtomPortTypePort(new MTOMFeature()); 
    String result = null;
    result = port.echoBinaryAsString(FOO.getBytes());
    System.out.println( "Got result: " + result );
  }
}

Configuring MTOM on Web Services and Clients

At design time, you can configure the following

  • Set an attachment threshold to specify when the xs:binary64 data is sent inline or as an attachment. By default, the attachment threshold is 0 bytes. For more information, see "Setting an Attachment Threshold" in Oracle Fusion Middleware Developing JAX-WS Web Services for Oracle WebLogic Server.

  • Enable HTTP chunking on the transport layer to minimize excessive buffering on the client side when processing MTOM attachments. For more information, see "Enabling HTTP Chunking" in Oracle Fusion Middleware Developing JAX-WS Web Services for Oracle WebLogic Server

How to Manage WSDL Files

JDeveloper provides a number of ways that you can manage WSDL files for a web service, as described in the following sections:

Creating WSDL Documents

You can create a WSDL document, for example, to create a top-down web service.

To create a WSDL document:

  1. In the Applications window, select the project containing the Java class or EJB from which you want to create a web service.
  2. Choose File > New > From Gallery to open the New Gallery.
  3. In the Categories list, expand Business Tier and select Web Services. In the Items list, double-click WSDL Document to open the Create WSDL Document dialog.

    For detailed help about completing the wizard, press F1 or click Help from within the dialog.

Displaying the WSDL for a Web Service

You can display the WSDL for a web service. The WSDL file is generated based on the annotations defined in the web service to a temporary directory and displayed.

Update “Managing WSDL Files" to indicate that when a user views a locally saved WADL file, the original WSDL location is saved as a read-only field in the editor.

To display the WSDL to a web service project

In the Applications window, right-click the web service for which you want to display the WSDL and select Show WSDL for Web Service Annotations from the context menu.

The WSDL is generated to a temporary directory and displayed.

Adding a WSDL to a Web Service Project

You can generate a WSDL file for a web service and add it to the project using the procedures described below. The WSDL file is generated automatically and added to the WEB-INF/wsdl directory for Web applications and to the META-INF/wsdl directory for EJB applications within the project. In addition, the @WebService annotation is updated with the wsdlLocation attribute to reference the location of the local WSDL. For example:

@WebService(wsdlLocation="WEB-INF/wsdl/CreditRatingService.wsdl")

To add a WSDL to a web service project

In the Applications window, right-click the web service for which you want to add a WSDL and select Generate WSDL and Add to Project from the context menu. The WSDL is automatically generated and added to the project in the WEB-INF/wsdl directory.

Note:

If a WSDL file already exists in the WEB-INF/wsdl or META-INF/wsdl directory, you are prompted whether or not to overwrite the existing WSDL file.

Saving a WSDL to Your Local Directory

When viewing a remote WSDL for a web service, you can save the WSDL to your local directory.

Note:

If you want to use the WSDL within a web service project, you need to copy it to a location that is accessible by the project directory (for example, WEB-INF/wsdl for Web applications and META-INF/wsdl for EJB applications) and update the @WebService annotation to reference the WSDL location.

To save a WSDL to your local directory:

  1. Display the WSDL file for the web service.
  2. Choose Tools > Copy WSDL Locally.
  3. In the Select Destination for WSDL dialog, navigate to the location that you want to save the WSDL, or enter the location in the Directory name text box, and click Select.

    The WSDL is saved to the location specified.

Viewing the WSDL Used to Create the Web Service Client

You can view the WSDL that was used to generate the web service client. Please note:

  • If available, the local copy of the WSDL file is displayed. When generating the web service client, you have the option to copy the WSDL of the source web service to your local directory. See Creating the Client and Proxy Classes.

    Note:

    In most cases, the local copy of the WSDL will match the WSDL of the remote web service. If the remote web service is modified, the local WSDL may become out-of-sync with the remote WSDL. To ensure the web service client will be able to access the remote web service, you can regenerate the local WSDL using the remote WSDL, as needed. See Regenerating Web Service Client and Proxy Classes.

  • If the local version is not available, the remote WSDL is displayed.

To view the WSDL used to create the web service client:

  1. Right-click on the web service client container within the Applications window.
  2. Select Go To WSDL from the pop-up menu.

    The WSDL is displayed.

Refreshing the Local Copy of the WSDL and Regenerating the Web Service Client Proxy and Classes

You can refresh the local copy of the WSDL from the original WSDL location. The web service client and proxy classes are regenerated once the WSDL is refreshed.

To refresh the local copy of the WSDL:

  1. In the Applications window, right-click the web service client node that you want to regenerate and choose Properties from the context menu.

    The Web Service Client and Proxy Editor wizard is displayed.

  2. Select Web Service Description. (It should be selected by default.)
  3. Select Refresh Copied WSDL from Original WSDL Location if you wish to refresh the local WSDL using the WSDL at the original location.
  4. Click OK.

    The local copy of the WSDL is refreshed and the web service client and proxy classes are regenerated.

Updating the Web Service WSDL Used by the Client at Run Time

In some cases, you may need to update your application to reference imported XML resources, such as WSDLs and XSDs, from a source that is different from that which is part of the description of the web service. Redirecting the XML resources in this way may be required to improve performance or to ensure your application runs properly in your local environment.

For example, a WSDL may be accessible during client generation, but may no longer be accessible when the client is run. You may need to reference a resource that is local to or bundled with your application rather than a resource that is available over the network.

You can modify the location of the WSDL that will be used by the web service at runtime using one of the following methods:

  • XML Catalog File

  • Web Service Injection (@WebServiceRef) and a Deployment Plan

Using an XML Catalog File

When you create or regenerate a web service client, a jax-ws-catalog.xml file is created automatically in the META-INF directory. The file complies with the OASIS XML schema, as described in the Oasis XML Catalogs specification at http://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html.

You can update the web service WSDL by modifying the uri attribute of the <system> element in the jax-ws-catalog.xml file. The specified value will be used at run time.

The following provides a sample XML catalog (jax-ws-catalog.xml) file for a remote WSDL:

<catalog xmln="urn:oasis:names:tc:entity:xmlns:xml:catalog"
   prefer="system">
   <system systemId="http://foo.org/hello?wsdl"
      uri="http://foo.org/hello?wsdl" />
</catalog>

The following provides a sample XML catalog (jax-ws-catalog.xml) file for a local WSDL:

<catalog xmln="urn:oasis:names:tc:entity:xmlns:xml:catalog" 
   prefer="system">
   <system systemId="http://foo.org/hello?wsdl" 
      uri="../org/foo/HelloService.wsdl" />
</catalog>

In the preceding examples:

  • The <catalog> root element defines the XML catalog namespace and sets the prefer attribute to system to specify that system matches are preferred.

  • The <system> element associates a URI reference with a system identifier.

    Note:

    When creating the client and proxy classes for multiple web services on a local system that share the same endpoint, to ensure that URL is unique for each web service in the jaxws-catalog.xml file, the service QName is appended as anchor text. For example:

    http://foo.org/helloworld?wsdl

    Might become:

    http://foo.org/helloworld#%7Bhttp%3A%2F%2Fexample.com%2F%7DHelloService?wsdl

Using Web Service Injection (@WebServiceRef) and a Deployment Plan

This method involves the following steps:

  1. Using the @WebServiceRef annotation to define a reference to a web service and identify an injection target.

  2. Updating the deployment plan and modifying the value of the web service WSDL that is referenced at run time.

Step 1: How to Use the @WebServiceRef Annotation

The @WebServiceRef annotation injects an endpoint for the web service interface that is defined in the web.xml file. The following example demonstrates how to use the @WebServiceRef annotation to define a reference to a web service and identify an injection target.

...
@WebService
public class LoansApprover { 
   /** 
    ** Credit rating service injected from web.xml
    **/
   @WebServiceRef(name = "CreditRatingService")
   CreditRating creditRating;

   /** 
    ** @return Loan application with approval code if approved.
    **/
   public LoanApprovalReponse approveLoan(LoanApplication la) {
      ...
   }
}

The web service class for the CreditRatingService is hard-coded in the web.xml file, as shown in the following example:

<?xml version = '1.0' encoding = 'windows-1252'?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
      xsi:schemaLocation="http://java.sun.com/xml/ns/javaee 
      http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" 
      version="2.5"
      xmlns="http://java.sun.com/xml/ns/javaee">
   ... 
   <service-ref>
      <service-ref-name>CreditRatingService</service-ref-name>
      <service-interface>
        com.somecreditrating.xmlns.rating.CreditRating_Service
      </service-interface>
   </service-ref>
</web-app>

Step 2: How to Update the Deployment Plan

To modify the value of the WSDL that is used at run time, you can generate and update a deployment plan.

A deployment plan is an optional XML document that you use to configure an application for deployment to a specific environment. A deployment plan defines or overrides deployment property values that would normally be defined in an application's deployment descriptors. To update the configuration for your application, you add or update variables in the deployment plan, defining both the location of the descriptor properties and the value to assign to the properties. For more information, see the Oracle Fusion Middleware Deploying Applications to Oracle WebLogic Server.

The following example illustrates a deployment plan that overrides the value of the CreditRatingService web service WSDL, where:

  • The variable-definition element defines the CreditRatingService variable and the value to assign to it.

  • As part of the module-override element for the LoanApplication-LoanApprover-context-root.war, a variable-assignment element defines the CreditRatingService variable and the exact location within the descriptor where the property is overridden.

<?xml version='1.0' encoding='UTF-8'?>
<deployment-plan xmlns="http://www.bea.com/ns/weblogic/deployment-plan"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   xsi:schemaLocation="http://www.bea.com/ns/weblogic/deployment-plan
   http://www.bea.com/ns/weblogic/deployment-plan/1.0/deployment-plan.xsd"
   global-variables="false">
   <application-name>production</application-name>
   <variable-definition>
      <variable>
         <name>CreditRatingService</name>
         <value>http://www.somecreditrating.com/xmlns/rating?WSDL</value> 
      </variable>
   </variable-definition>
   <module-override>
      <module-name>production.ear</module-name>
      <module-type>ear</module-type>
      <module-descriptor external="false">
         <root-element>weblogic-application</root-element>
         <uri>META-INF/weblogic-application.xml</uri>
      </module-descriptor>
      <module-descriptor external="false">
         <root-element>application</root-element>
         <uri>META-INF/application.xml</uri>
      </module-descriptor>
      <module-descriptor external="true">
         <root-element>wldf-resource</root-element>
         <uri>META-INF/weblogic-diagnostics.xml</uri>
      </module-descriptor>
   </module-override>
   <module-override>
      <module-name>
        LoanApplication-LoanApprover-context-root.war
      </module-name> 
      <module-type>war</module-type>
      <module-descriptor external="false">
         <root-element>weblogic-web-app</root-element>
         <uri>WEB-INF/weblogic.xml</uri>
      </module-descriptor>
      <module-descriptor external="false">
         <root-element>web-app</root-element>
         <uri>WEB-INF/web.xml</uri>
         <variable-assignment>
            <name>CreditRatingService</name>
            <xpath>
       /web-app/service-ref/[service-ref-name="CreditRatingService"]/wsdl-file
            </xpath> 
            <operation>add</operation>
         </variable-assignment>
      </module-descriptor> 
      <module-descriptor external="true"> 
         <root-element>weblogic-webservices</root-element> 
         <uri>WEB-INF/weblogic-webservices.xml</uri> 
      </module-descriptor> 
      <module-descriptor external="false"> 
         <root-element>webservices</root-element>
         <uri>WEB-INF/webservices.xml</uri>
      </module-descriptor> 
      <module-descriptor external="true"> 
         <root-element>webservice-policy-ref</root-element>
         <uri>WEB-INF/weblogic-webservices-policy.xml</uri> 
      </module-descriptor>
   </module-override>
   <config-root>
      D:\prom-demo\jdeveloper\mywork\LoanApplication\deploy\production\.\plan
   </config-root> 
</deployment-plan>

How to Edit JAX-WS Web Services

You can edit a JAX-WS web service that you have created in JDeveloper, for example to change the exposed method or a file location.

When you edit a JAX-WS web service, the previously generated WSDL file is overwritten, and any changes you have made to it will be lost. If you have already deployed the web service and you edit it, you must redeploy it.

To edit a JAX-WS web service:

  1. In the Applications window, right-click the web service and choose Web Service Properties. The reentrant web service wizard is displayed.
  2. Make your changes to the web service. Click OK. The web service files are regenerated.

    For detailed help about completing the wizard, press F1 or click Help from within the wizard.

After editing the web service files, you must redeploy the web service. For more information, see Deploying Web Services.

How to Delete JAX-WS Web Services

You can delete a JAX-WS web service if it is no longer needed.

When you delete a web service from JDeveloper, the web service container and the files it contains (a WSDL file and possibly some interfaces) are deleted. The entries for the web service in web.xml are removed, although the file is not deleted. The WebServices.deploy file is unchanged as it may be used for other web services.

To delete a web service

In the Applications window, right-click the web service and choose Delete. The Confirm Delete dialog displays listing the file usages. Click OK.

Creating RESTful Web Services and Clients

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.

JAX-RS is a Java programming language API that uses annotations to simplify the development of RESTful web services. JAX-RS annotations are runtime annotations. When you deploy the Java EE application archive containing JAX-RS resource classes to WebLogic Server, the runtime configures the resources, generates the helper classes and artifacts, and exposes the resource to clients.

WebLogic Server supports the following JAX-RS Reference Implementations (RIs):

  • Jersey 1.18 (JAX-RS 1.1 RI)—This is the default implementation and provides a production quality implementation of the JSR-311 JAX-RS 1.1 specification, defined at: http://jcp.org/en/jsr/summary?id=311.

    Note:

    Although support for the Jersey 1.18 (JAX-RS 1.1RI) client APIs of WebLogic Server is deprecated, support is maintained for backward compatibility. For more information about compatibility with earlier Jersey/JAX-RS releases, see Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server.

  • Jersey 2.5.1 (JAX-RS 2.0 RI)—This implementation is offered as a shared library and provides a production quality implementation of the JSR-339 JAX-RS 2.0 specification, defined at: http://jcp.org/en/jsr/detail?id=339.

The Jersey 2.5.1 (JAX-RS 2.0 RI) shared library is auto-deployed to the Integrated WebLogic Server.

Note: You can attach OWSM policies to RESTful web services and clients that are built using Jersey 1. x JAX-RS RI. RESTful web services and clients that are built using Jersey 2.5.1 (JAX-RS 2.0 RI) are also secured using OWSM policies. For more information about securing RESTful web services and clients built using Jersey 2.5.1 (JAX-RS 2.0 RI), see "Securing RESTful Web Services and Clients" in Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server.

For complete details about developing RESTful web services and clients using JAX-RS, see:

The following sections describe how to create RESTful web service and clients quickly and easily using JDeveloper:

How to Create RESTful Web Services

You can develop RESTful web services quickly and easily using JDeveloper. All of the standard Java source editor features will work with RESTful web service calls, such as code insight, import assistance, and so on.

The following sections describe how to develop RESTful web services:

For more information about:

Example of a Simple RESTful Web Service

The following is an example of a simple RESTful web service. In this example:

Additional examples are listed in “Learn More About RESTful Web Services" in Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server.

package samples.helloworld;
 
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
 
// Specifies the path to the RESTful web service
@Path("/helloworld")
public class helloWorld {
 
   // Specifies that the method processes HTTP GET requests 
   @GET
   @Path("hello")
   @Produces("text/plain")
   public String sayHello() {
      return "Hello World!";
   }
}

Creating a RESTful Web Service

You can create a new RESTful web service class or generate a RESTful web service from an existing Java class using the Create RESTful Service wizard.

The wizard creates the deployment files for you, so once you create your web service the final step is to deploy it. You can test them using the HTTP Analyzer. For more information, see How to Examine Web Services using the HTTP Analyzer .

As described in How to Choose Your Deployment Platform, when creating a RESTful web service using the Create RESTful Service wizard, you are prompted to select the deployment platform and you can choose the Jersey 1.0 or 2.0 style.

The JAX-RS Jersey library is automatically added to your project. If required by your application, you can add to your project the JAX-RS Jersey Jackson or JAX-RS Jersey Jettison libraries, which are bundled with the product. (The JAX-RS Jersey Rome library is not bundled with the product.) For information about adding a library to your project, see "How to Manage Libraries".

Note:

As support for the server-side Jersey 1.x APIs is unavailable, use the corresponding JAX-RS 2.0 standard. If required, use Jersey 2.x APIs. Support for the Jersey 1.18 (JAX-RS 1.1RI) client APIs of WebLogic Server is deprecated. However, support is maintained for backward compatibility. For more information about compatibility with earlier Jersey/JAX-RS releases see, Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server.

The Jersey 2.5.1 (JAX-RS 2.0 RI) shared library is auto-deployed to the Integrated WebLogic Server.

Note:

You can attach OWSM policies to RESTful web services and clients that are built using Jersey 1.18 (JAX-RS 1.1 RI). RESTful web services and clients that are built using Jersey 2.5.1 (JAX-RS 2.0 RI) are secured using OWSM policies. For more information about securing RESTful web services and clients built using Jersey 2.5.1 (JAX-RS 2.0 RI), see "Securing RESTful Web Services and Clients" in Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server.

To create the RESTful web service:

  1. In the Applications window, select the project within which you want to create a new RESTful web service or that contains the Java class from which you want to create a RESTful web service or within which you want to create a new RESTful web service.

  2. Choose File > New > From Gallery to open the New Gallery.

  3. In the Categories list, expand Business Tier and select Web Services.

  4. In the Items list, select RESTful Service and click OK to launch the Create RESTful Service wizard.

    For detailed help about completing the wizard, press F1 or click Help from within the wizard.

Alternatively, you can launch the Create RESTful Service wizard by right-clicking on the Java class from which you want to create a RESTful web service and selecting Create RESTful Service.

Defining the Relative URI of the Root Resource and Subresources

Add the javax.ws.rs.Path annotation at the class level of the resource to define the relative URI of the RESTful web service. Such classes are referred to a root resource classes. For more information about the root resource class, see the following sections in Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server:

You can add @Path on methods of the root resource class as well, to define subresources to group specific functionality. For more information, see “How to Define the Relative URI of Subresources (@Path)" in Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server.

You can define the URI as a constant or variable value (referred to as a “URI path template"):

  • To define the URI as a constant value, pass a constant value to the @Path annotation. Preceding and ending slashes (/) are optional.

  • To define the URI as a URI path template, pass one or more variable values enclosed in braces in the @Path annotation. Then, you can use the javax.ws.rs.PathParam annotation to extract variable information from the request URI, defined by the @Path annotation, and initialize the value of the method parameter, as described in Extracting Information from the Request Message.

For more information, see “How to Define the Relative URI of the Resource Class (@Path)" in Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server.

Using JDeveloper, you can specify the @Path annotation using one of the following methods:

Defining the @Path Annotation in the RESTful Service Wizard

You can define the relative URI of the root resource and subresources when creating your RESTful service using the Create RESTful Service wizard. For more information about invoking the wizard, see Creating a RESTful Web Service.

To define the @Path annotation in the RESTful service wizard:

In the Create RESTful Service wizard, navigate to one of the following pages, depending on whether you are creating a new RESTful service class or generating one from an existing Java class:

  • Create New RESTful Service

  • Create RESTful Service From Java Class

Define the relative URIs, as follows:

  • To define the relative URI for the root resource class, enter a value in the Root Path field.

  • To define the relative URI for the subresource, enter a value in the Path field of the HTTP Methods table.

For more information at any time, press F1 or click Help from within the dialog.

Defining the @Path Annotation in the Java Class

You can define the relative URI of the root resource and subresources when creating your RESTful service by adding the @Path annotation directly in the Java class; the Code Insight feature can help you. For more information, see How to Work with Web Services Code Insight.

To define the @Path annotation in the Java class:

  1. Open the RESTful service class in the source editor.

  2. Perform one or more of the following tasks:

    • Add the @Path annotation at the class level of the resource to define the relative URI of the RESTful service.

    • Add the @Path annotation to the method of a resource to define a subresource.

    You can use the Code Insight to help you. Start typing the annotation, for example, @Path. When you pause, or click Ctrl+Shift+Space, a popup appears from which you can choose the correct entry to complete the statement.

Note:

Ensure that you select javax.ws.rs.Path from the popup. For example, do not select java.nio.file.Path inadvertently.

For more information about defining the @Path annotation, see “Defining the Relative URI of the Root Resource and Subresources" in Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server.

Defining the @Path Annotation in the Properties Window

You can define the relative URI of the root resource and subresources using the Properties window.

To define the @Path annotation in the Properties window:

  1. With the RESTful service class open in the source editor, choose Window > Properties to open the Properties window.

    For more information at any time, press F1 or click Help from within the Properties window.

  2. To define the relative URI of the resource class:

    1. Position your cursor at the class level of the resource.

    2. In the Properties window, expand JAX-RS and click RESTful Resource Class.

      The service is updated to add the @Path annotation above the resource class and import javax.ws.rs.Path.

    3. Enter a value in the Path field to define the URI. The URI can be defined as a constant value or URI path template.

    For more information, see “How to Define the Relative URI of the Resource Class (@Path)" in Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server.

  3. To define the relative URI of a subresource:

    1. Position your cursor at the method of the resource.

    2. If you have not already mapped the resource method to an HTTP method, in the Properties window, expand JAX-RS and select an HTTP method from the Method Type drop-down menu. Valid HTTP methods include: GET, POST, PUT, or DELETE.

      The service is updated to include the method annotation above the resource method and the appropriate API is imported. For more information, see Mapping Incoming HTTP Requests to Java Methods.

    3. Enter a value in the Method Path field to define the relative URI of the subresource. The URI can be defined as a constant value or URI path template.

    For more information, see “How to Define the Relative URI of Subresources (@Path)" in Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server.

What Happens at Runtime: How the Base URI is Constructed

The base URI of the RESTful web service is constructed as follows:

http://myHostName/contextPath/servletURI/resourceURI

For a complete description of the base URI path structure, see “What Happens at Runtime: How the Base URI is Constructed" in Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server.

For the contextPath, or context root, at the project level you can set the value that will be assigned to the deployed Java EE web application on Integrated WebLogic Server. For more information, see How to Set the Context Root for Web Services. In this scenario, the contextPath defaults to:

applicationname-projectname-context-root

Mapping Incoming HTTP Requests to Java Methods

JAX-RS uses Java annotations to map an incoming HTTP request to a Java method. Table 21-7 lists the annotations available, which map to the similarly named HTTP methods.

Table 21-7 javax.ws.rs Annotations for Mapping HTTP Requests to Java Methods

Annotation Description Idempotent

@GET

Transmits a representation of the resource identified by the URI to the client. The format might be HTML, plain text, JPEG, and so on. For more information, see “How to Transmit a Representation of the Resource (@GET)" in Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server.

Yes

@PUT

Creates or updates the representation of the specified resource identified by the URI. For more information, see “How to Create or Update the Representation of the Resource (@PUT)" in Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server.

Yes

@DELETE

Deletes the representation of the resource identified by the URI. For more information, see “How to Delete a Representation of the Resource (@DELETE)" in Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server.

Yes

@POST

Creates, updates, or performs an action on the representation of the specified resource identified by the URI. For more information, see “How to Create, Update, or Perform an Action on a Representation of the Resource (@POST)" in Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server.

No

@HEAD

Returns the response headers only, and not the actual resource (that is, no message body). This is useful to save bandwidth to check characteristics of a resource without actually downloading it. For more information, see http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/HEAD.html.

The HEAD method is implemented automatically if not implemented explicitly. In this case, the runtime invokes the implemented GET method, if present, and ignores the response entity, if set.

Yes

@OPTIONS

Returns the communication options that are available on the request/response chain for the specified resource identified by the URI. The Allow response header will be set to the set of HTTP methods supported by the resource and the WADL file is returned. For more information, see http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/OPTIONS.html.

The OPTIONS method is implemented automatically if not implemented explicitly. In this case, the Allow response header is set to the set of HTTP methods supported by the resource and the WADL describing the resource is returned.

Yes

@HttpMethod

Indicates that the annotated method should be used to handle HTTP requests. For more information, see http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/HttpMethod.html.

N/A

Using JDeveloper, you can map HTTP requests to Java methods using one of the following methods:

Mapping HTTP Requests to Java Methods in the RESTful Service Wizard

You can map HTTP requests to Java methods when creating your RESTful web service using the Create RESTful Service wizard. For more information about invoking the wizard, see Creating a RESTful Web Service.

To map HTTP requests to Java methods in the RESTful service wizard:

In the Create RESTful Service wizard, navigate to one of the following pages, depending on whether you are creating a new RESTful service class or generating one from an existing Java class:

  • Create New RESTful Service

  • Create RESTful Service From Java Class

Perform one of the following tasks:

  • If creating a new RESTful service class, select the HTTP method(s) for which you want to create Java methods. In each case, enter a value in the Nos column to indicate the desired number of Java methods that you want to be mapped to HTTP methods.

  • If generating a RESTful service from an existing class, map HTTP requests to Java methods in the Configure HTTP Methods table by selecting an HTTP method from the Type drop-down list. Valid HTTP methods include: GET, POST, PUT, or DELETE.

For more information at any time, press F1 or click Help from within the dialog.

Mapping HTTP Requests to Java Methods in the Java Class

You can map HTTP requests to Java methods when creating your RESTful service by adding one of the HTTP request annotations defined in Table 21-7 directly in the Java class; the Code Insight feature can help you. For more information, see How to Work with Web Services Code Insight.

To map HTTP requests to Java methods in the Java class:

  1. Open the RESTful service class in the source editor.

  2. Add an HTTP request annotation from Table 21-7 to one or more methods in the Java class.

    You can use the Code Insight to help you. Start typing the annotation, for example, @GET. When you pause, or click Ctrl+Shift+Space, a popup appears from which you can choose the correct entry to complete the statement.

For more information about defining the HTTP request annotation, see “Mapping Incoming HTTP Requests to Java Methods" in Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server.

Mapping HTTP Requests to Java Methods in the Properties Window

You can map HTTP requests to Java methods in the Properties window.

To map HTTP requests to Java methods in the Properties window:

  1. With the RESTful service class open in the source editor, choose Window > Properties to open the Properties window.

    For more information at any time, press F1 or click Help from within the Properties window.

  2. Position your cursor at the method of the resource.

  3. In the Properties window, expand JAX-RS and select an HTTP method from the Method Type drop-down menu. Valid HTTP methods include: GET, POST, PUT, or DELETE.

    The service is updated to include the method annotation above the resource method and the appropriate API is imported.

For more information about defining the HTTP request annotation, see “Mapping Incoming HTTP Requests to Java Methods" in Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server.

Customizing Media Types for the Request and Response Messages

Add the javax.ws.rs.Consumes or javax.ws.rs.Produces annotation at the class or method level of the resource to customize the media type of the request and response messages, respectively. More than one media type can be declared in each case.

Using JDeveloper, you can customize messages types for the request and response messages using one of the following methods:

Customizing Media Types in the RESTful Service Wizard

You can customize media types when creating your RESTful web service using the Create RESTful Service wizard. For more information about invoking the wizard, see Creating a RESTful Web Service.

To customize media types in the RESTful service wizard:

In the Create RESTful Service wizard, navigate to one of the following pages, depending on whether you are creating a new RESTful service class or generating one from an existing Java class:

  • Create New RESTful Service

  • Create RESTful Service From Java Class

Customize the media types, as follows:

  • To customize media types for the root resource class, click ... next to the Consumes or Produces field, select one or more media types from the Select Media Types dialog box, and click OK. The number of media types configured is reflected in the field.

  • To customize media types for the methods:

    • If creating a new RESTful service class, in the Select HTTP Methods table click in the Consumes or Produces column corresponding to the method for which you want to configure media types, select the media types from the Select Media Types dialog box, and click OK. The number of media types configured is reflected in the table entry.

    • If generating a RESTful service from an existing class, in the Configure HTTP Methods table click in the Consumes or Produces column corresponding to the method for which you want to configure media types, select the media types from the Select Media Types dialog box, and click OK. The number of media types configured is reflected in the table entry.

For more information at any time, press F1 or click Help from within the dialog.

Customizing Media Types in the Java Class

You can customize media types when creating your RESTful service by adding the @Produces or @Consumes annotation at the class or method level of the resource to customize the media types of the request and response messages, respectively, directly in the Java class; the Code Insight feature can help you. For more information, see How to Work with Web Services Code Insight.

To customize media types in the Java class:

  1. Open the RESTful service class in the source editor.

  2. Add the @Produces or @Consumes annotation at the class or method level.

    You can use the Code Insight to help you. Start typing the annotation, for example, @Produces. When you pause, or click Ctrl+Shift+Space, a popup appears from which you can choose the correct entry to complete the statement.

For more information about customizing media types, see “Customizing Media Types for the Request and Response Messages" in Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server.

Customizing Media Types in the Properties Window

You can customize media types in the Properties window.

To customize media types in the Properties window:

  1. With the RESTful service class open in the source editor, choose Window > Properties to open the Properties window.

    For more information at any time, press F1 or click Help from within the Properties window.

  2. Position your cursor at the class or method level of the resource.

  3. In the Properties window, expand JAX-RS, click ... next to the Consumes Type or Produces Type field, select one or more media types from the Edit Property dialog box, and click OK. The number of media types configured is reflected in the field.

    The service is updated to include the method annotation and the appropriate API is imported.

For more information about customizing media types, see “Customizing Media Types for the Request and Response Messages" in Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server.

Extracting Information from the Request Message

The javax.ws.rs package defines a set of annotations, shown in Table 21-8, that enable you extract information from the request message to inject into parameters of your Java method.

Table 21-8 javax.ws.rs Annotations for Extracting Information From the Request Message

Annotation Description

@CookieParam

Extract information from the HTTP cookie-related headers to initialize the value of a method parameter. For more information, see http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/CookieParam.html.

@DefaultValue

Define the default value of the request metadata that is bound using one of the following annotations: @CookieParam, @FormParam, @HeaderParam, @MatrixParam, @PathParam, or @QueryParam. For more information, see “How to Define the DefaultValue (@DefaultValue)" in Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server.

@FormParam

Extract information from an HTML form of the type application/x-www-form-urlencoded. For more information, see http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/FormParam.html.

@HeaderParam

Extract information from the HTTP headers to initialize the value of a method parameter. For more information, see http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/HeaderParam.html.

@MatrixParam

Extract information from the URI path segments to initialize the value of a method parameter. For more information, see http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/MatrixParam.html.

@PathParam

Define the relative URI as a variable value (referred to as “URI path template"). For more information, see “How to Extract Variable Information from the Request URI (@PathParam)" in Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server.

@QueryParam

Extract information from the query portion of the request URI to initialize the value of a method parameter. For more information, see “How to Extract Request Parameters (@QueryParam)" in Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server.

Using JDeveloper, you can extract information from the request message using one of the following methods:

In the Properties window, you can enable encoding of a parameter value that is bound using one of the following annotations: @FormParam, @MatrixParam, @PathParam, or @QueryParam. For more information, see Enabling the Encoding Parameter Values in the Properties Window.

Extracting Information from the Request Message in the RESTful Service Wizard

You can extract information from the request when creating your RESTful web service using the Create RESTful Service wizard. For more information about invoking the wizard, see Creating a RESTful Web Service.

To extract information from the request message in the RESTful service wizard:

When using the RESTful service wizard, you can extract information from the request message when generating a RESTful service from an existing Java class only.

  1. In the Create RESTful Service wizard, navigate to the Create RESTful Service From Java Class page.

  2. Select a method in the Configure HTTP Methods table. Ensure that you have selected an HTTP method from the Type column for the method.

    A list of the method parameters is shown in the Configure Parameters table.

  3. In the Configure Parameters table:

    • In the Annotation drop-down list, select the annotation to use to extract information from the request message. A list of valid annotations is defined in Table 21-8.

    • In the Parameter field, enter the name of the parameter that will be used to store the extracted value.

    • In the Default field, enter the default value for the parameter, if no value is passed with the request message.

    • Click Encode to enable encoding of the parameter value. This field is enabled for the following annotations only: @FormParam, @MatrixParam, @PathParam, or @QueryParam.

  4. Click Next to advanced to the next screen or Finish to generate the RESTful service.

For more information at any time, press F1 or click Help from within the dialog.

Extracting Information from the Request Message in the Java Class

You can extract information from the request message when creating your RESTful service by adding one or more of the annotations defined in Table 21-8 to the class or method level of the resource directly in the Java class; the Code Insight feature can help you. For more information, see How to Work with Web Services Code Insight.

To extract information from the request message in the Java class:

  1. Open the RESTful service class in the source editor.

  2. Add one of the annotations from Table 21-8 at the class or method level.

    You can use the Code Insight to help you. Start typing the annotation, for example, @PathParam. When you pause, or click Ctrl+Shift+Space, a popup appears from which you can choose the correct entry to complete the statement.

  3. Add the javax.ws.rs.Encode annotation at the class or method level to enable encoding of a parameter value that is bound using one of the following annotations: @FormParam, @MatrixParam, @PathParam, or @QueryParam. If specified at the class level, parameters for all methods in the class will be encoded. For more information, see “Enabling the Encoding Parameter Values (@Encode)" in Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server.

For more information about extracting information from the request message, see “Extracting Information From the Request Message" in Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server.

Enabling the Encoding Parameter Values in the Properties Window

In the Properties window, you can enable the encoding of parameter values that are bound using one of the following annotations: @FormParam, @MatrixParam, @PathParam, or @QueryParam. For more information about the @Encode annotation, see “Encoding Parameter Values (@Encode)" in Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server.

To enable the encoding of parameter values in the Properties window:

  1. With the RESTful service class open in the source editor, choose Window > Properties to open the Properties window.

    For more information at any time, press F1 or click Help from within the Properties window.

  2. Position your cursor at the class or method level of the resource.

  3. In the Properties window, expand JAX-RS and click Encode Values.

    The service is updated to include the @Encode annotation and import the javax.ws.rs.Encoded API.

    Note: If you enable encoding at the class level, encoding is enabled on all associated methods, and the Encode Values checkbox is not available at the method level.

Mapping HTTP Request and Response Entity Bodies Using Entity Providers

A subset of Java types are supported automatically by HTTP request and response entity bodies. For return types that are not supported automatically, you must define an entity provider to map HTTP request and response entity bodies to method parameters and return types. For a list of supported Java types and more information about creating an entity provider, see “Mapping HTTP Request and Response Entity Bodies Using Entity Providers" in Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server.

When creating a RESTful web service from an existing Java class using the Create RESTful Service wizard (by right-clicking on the Java class and selecting Create RESTful Service), if the class contains methods that utilize types that are not supported automatically, the following warning message is displayed:

The return types for the following methods are not supported automatically for 
HTTP response entities and require entity providers to map between 
representations and Java types. Check and correct the code after the service is 
generated. 
methodName

The following code excerpt provides an example of a class that contains a method (getClass) that returns a custom type, and that requires you to write an entity provider.

public class Class1
{
  public String hello() { return "Hello"; }
  public Class2 getClass(String name) { return new Class2(); };
}
 
public class Class2
{
  public Class2() { }
}

Note:

Jersey JSON provides a set of JAX-RS MessageBodyReader and MessageBodyWriter providers distributed with the jersey-json module. For more information, see “JSON Support" in the Jersey User Guide at: http://jersey.java.net/documentation/1.18/json.html

If required by your application, you can add to your project the JAX-RS Jersey Jackson, which is bundled with the product. For information about adding a library to your project, see How to Manage Libraries.

Accessing the RESTful Web Service WADL

The Web Application Description Language (WADL) is an XML-based file format that describes your RESTful web services application. By default, a basic WADL is generated at runtime and can be accessed from JDeveloper.

To access the RESTful web service WADL:

  1. Right-click the service 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 IntegratedWebLogicServer node in the Application Servers window.

    • Displays a Log window for the integrated application server (if the log window is not already open).

  2. Click the Target Application WADL provided in the integrated application server log window. For example:
    This image is described in the surrounding text

Note:

You can view the WADL from the HTTP Analyzer window by clicking the WADL URI in the HTTP Analyzer window.

A read-only version of the WADL file opens in the source editor, as shown in Figure 21-1.

Figure 21-1 Example of WADL File

This image is described in the surrounding text.

The figure shows the WADL file structure, including the resources, subresources, and methods in the RESTful web service. You can press Test to invoke the HTTP Analyzer.

You can toggle between the following views:

  • Preview—Enables you to:

    • View a summary of resources and subresources in the RESTful web service.

    • View the methods mapped for each resource, and the request and response representations and status.

    • Test each method by clicking the Test button to invoke the HTTP Analyzer.

  • Source—View the source of the WADL.

How to Create RESTful Web Service Clients

JDeveloper makes it easy to use a RESTful web service in your application by allowing you to create client and proxy classes to access the service using the Create RESTful Proxy Client wizard. You can launch the wizard when you locate or create a RESTful web service. Alternatively, you can launch the wizard directly and enter the URL for the RESTful web service or use the Find Web Service wizard to locate a RESTful web service in a UDDI registry.

As described in How to Choose Your Deployment Platform, when creating a RESTful web service client using the Create RESTful Proxy Client wizard, you are prompted to select the deployment platform, and you can choose the Jersey 1.18 (JAX-RS 1.1) or Jersey 2.5 (JAX-RS 2.0 RI).

The Jersey JAX-RS library is automatically added to your project. If required by your application, you can add to your project the Jersey JAX-RS Jackson or Jersey JAX-RS Jettison libraries, which are bundled with the product. (The Jersey JAX-RS Rome library is not bundled with the product.) For information about adding a library to your project, see How to Manage Libraries.

The Jersey 2.5.1 (JAX-RS 2.0 RI) shared library is auto-deployed to the Integrated WebLogic Server.

Please note:

  • For Jersey 1.18 (JAX-RS 1.1 RI), the RESTful web service client API is provided by the Jersey JAX-RS RI specifically; they are not part of the JAX-RS standard. Although support for the Jersey 1.18 (JAX-RS 1.1RI) client APIs of WebLogic Server is deprecated, support is maintained for backward compatibility. For more information about compatibility with earlier Jersey/JAX-RS releases, see Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server.

    For Jersey 2.5.1 (JAX-RS 2.0 RI), a standard client API is supported.

  • You can attach OWSM policies to RESTful web services and clients that are built using Jersey 1.18 (JAX-RS 1.1 RI) . RESTful web services and clients that are built using Jersey 2.5.1 (JAX-RS 2.0 RI) are also secured using OWSM policies. For more information about securing RESTful web services and clients built using Jersey 2.5.1 (JAX-RS 2.0 RI), see "Securing RESTful Web Services and Clients" in Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server.

The following sections describe how to develop RESTful web services:

For more information about:

Example of a Simple RESTful Client

This example provides a simple RESTful client that calls the RESTful service defined in the Simple RESTful Service Client above. It uses classes that are provided by the Jersey 1.18 (JAX-RS 1.1 RI) specifically; they are not part of the JAX-RS standard.

Note:

Alternatively, you can create an instance of the com.sun.jersey.api.client.Client class. However, you will not be able to take advantage of the Oracle extensions, such as securing the RESTful client using Oracle Web Services Manager (OWSM) policies, as described in Attaching Policies to RESTful Web Service Clients.

For the Jersey 2.5.1 (JAX-RS 2.0 RI), a standard client API is supported.

package samples.helloworld.client;

import weblogic.jaxrs.api.client.Client;
import com.sun.jersey.api.client.WebResource;

public class helloWorldClient {
   public helloWorldClient() {
      super();
   }

   public static void main(String[] args) {
      Client c = Client.create();
      WebResource resource = c.resource(
            "http://localhost:7101/RESTfulService/jersey/helloWorld");
      String response = resource.get(String.class);
   }
}

Creating RESTful Web Service Clients

You can create a new RESTful web service client from an existing remote or local WADL using the Create RESTful Proxy Client wizard.

To create a RESTful web service client:

  1. In the Applications window, select the project containing the Java class from which you want to create a RESTful web service.
  2. Choose File > New > From Gallery to open the New Gallery.
  3. In the Categories list, expand Business Tier and select Web Services.
  4. In the Items list, select RESTful Client and Proxy and click OK to launch the Create RESTful Proxy Client wizard.

    For detailed help about completing the wizard, press F1 or click Help from within the wizard.

Creating WebSockets

WebLogic Server supports the WebSocket protocol (RFC 6455), which provides full-duplex communications between two peers over the TCP protocol.

The WebLogic Server implementation of the WebSocket protocol and its accompanying API enable you to develop and deploy applications that communicate bidirectionally with clients. To initiate the WebSocket connection, the client sends a handshake request to the server. The connection is established if the handshake request passes validation, and the server accepts the request. When a WebSocket connection is created, a browser client can send data to a WebLogic Server instance while simultaneously receiving data from that server instance.

Although you can use the WebSocket protocol for any type of client-server communication, the implementation is most commonly used to communicate with browsers running Web pages that use the World Wide Web Consortium (W3C) JavaScript WebSocket API. As part of the HTML5 specification (http://www.w3.org/TR/html5/), the WebSocket protocol is supported by most browsers. The WebLogic Server implementation of the WebSocket protocol also supports Java clients.

The JSR 356 Java API for WebSocket reference implementation RI, supported by WebLogic Server, enables you to create, configure, and deploy WebSocket endpoints in web applications. The API includes the following packages:

For more information about the WebSocket protocol and its support on WebLogic Server, see:

The following sections provide more information about configuring WebSockets using JDeveloper:

How to Configure WebSockets in the Properties Window

You can configure WebSockets in the Properties window.

To configure WebSockets in the Properties window:

  1. Create a WebSocket project.

    For more information about creating a project with preconfigured features, see How to Create a Project.

  2. Create a Java class.

    For more information, see How to Create a New Java Class or Interface.

  3. With the Java class open in the source editor, choose Window > Properties to open the Properties window.

    For more information at any time, press F1 or click Help from within the Properties window.

  4. With the cursor in the public class, navigate to the Web Socket node in the Properties window.
  5. Select:

    • Web Socket Client to configure a WebSocket client. In this case, the service is updated to include the @ClientEndpoint annotation and import the javax.websocket.ClientEndpoint API.

      Web Socket Service to configure a WebSocket service. In this case, the service is updated to include the @ServiceEndpoint annotation and import the javax.websocket.server.ServerEndpoint API. By default, the URI template endpoint name is set to service.

  6. Optionally, configure the WebSocket endpoint properties defined in the following table. When you configure a property, the attribute is added to the @ClientEndpoint or @ServiceEndpoint annotation for WebSocket clients and services, respectively.

    Table 21-9 WebSocket Server Endpoint Properties

    Property Annotation Attribute Description

    URI Template

    value

    Relative URI path at which the server endpoint will be deployed.

    Note: This property is available for WebSocket services only.

    Custom Configurator

    configurator

    Custom implementation of ServerEndpointConfiguration.Configurator.

    Decoders

    decoders

    List of message decoder class names.

    Encoders

    encoders

    List of message encoder class names.

    Supported Sub Protocols

    subprotocols

    List of supported subprotocols.

How to Configure WebSockets Using Annotations

The Java API for WebSocket (JSR-356) enables you to create, configure, and deploy WebSocket endpoints in web applications. The WebSocket client API specified in JSR-356 also enables you to access remote WebSocket endpoints from any Java application.

The process for creating and deploying a WebSocket endpoint is as follows, as described in "Using the WebSocket Protocol in WebLogic Server" in Oracle Fusion Middleware Developing Applications for Oracle WebLogic Server:

  1. Create an endpoint class.

    The Java API for WebSocket enables you to create the following kinds of endpoints:

    • Annotated endpoints

    • Programmatic endpoints

    For more information, see "Creating an Endpoint" in Oracle Fusion Middleware Developing Applications for Oracle WebLogic Server.

  2. Implement the lifecycle methods of the endpoint.

    Add a method to your endpoint class to handle an event and annotation that method to designate it as a handler. For more information, see "Handling Life Cycle Events for a WebSocket Connection" in Oracle Fusion Middleware Developing Applications for Oracle WebLogic Server.

  3. Add your business logic to the endpoint.
  4. Deploy the endpoint inside a web application.

    For more information, see "Deploying a WebSocket Application" in Oracle Fusion Middleware Developing Applications for Oracle WebLogic Server.

  5. Create a WebSocket client application.

    For more information, see "Writing a WebSocket Client" in Oracle Fusion Middleware Developing Applications for Oracle WebLogic Server.

For more information about and examples of creating and configuring WebSocket service and client applications using the WebSocket API, see "Using the WebSocket Protocol in WebLogic Server" in Oracle Fusion Middleware Developing Applications for Oracle WebLogic Server.

How to Test the WebSocket Connection

When you run the WebSocket application, you can test the connection by clicking the Target URL provided in the integrated application server log window. If the WebSocket connection is accessible, the following message is displayed:

Connected successfully

Attaching Policies

The following sections describe how to attach policies to web services and clients, and configure the policy repository to use custom web service policies.

What You May Need to Know About OWSM Policies

OWSM policies can be attached to JAX-WS web services at the port level and RESTful web services at the servlet level.

Note:

You can attach OWSM policies to RESTful web services and clients that are built using Jersey 1.x JAX-RS RI. RESTful web services and clients that are built using Jersey 2.5.1 (JAX-RS 2.0 RI) are secured using OWSM policies. For more information about securing RESTful web services and clients built using Jersey 2.5.1 (JAX-RS 2.0 RI), see "Securing RESTful Web Services and Clients" in Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server.

JDeveloper is preconfigured to use the OWSM policy store set at the default location in the WS Policy page of the Preferences dialog, which you can access in one of the following ways:

  • Tools > Preferences > WS Policy Store

  • Application > Application Properties > WS Policy Store

You can specify another policy store location to use your organization's custom OWSM policies. For more information How to Use a Different OWSM Policy Store.

For more information about OWSM policies, see the Oracle Fusion Middleware Securing Web Services and Managing Policies with Oracle Web Services Manager.

Note:

A web service Provider must be deployed with a WSDL file in order to ensure any attached OWSM policies are enforced. You can the WSDL to the web service provider using the wsdlLocation element to the @WebServiceProvider annotation.

What You May Need to Know About Oracle WebLogic Web Service Policies

Oracle WebLogic web service policies can be attached to JAX-WS web services at the port or operation level. With Oracle WebLogic web service policies it is possible to specify the usage direction of the policies, for example, to be applied on the inbound (request) message or outbound (response) message, or both.

You can configure JDeveloper to use the custom Oracle WebLogic web service policies of your organization. For more information, see How to Use Custom Web Service Policies.

Jersey 2. x (JAX-RS 2.0 RI) web services are secured using Oracle Web Services Manager (OWSM) security policies.

For more information, see Oracle Fusion Middleware Securing WebLogic Web Services for Oracle WebLogic Server.

How to Attach Policies to JAX-WS Web Service and Clients

This section describes how to attach policies to JAX-WS web services and clients created in JDeveloper. You can use the following types of policies:

  • Oracle Web Service Manager (OWSM) policies—You can attach security policies only.

  • Oracle WebLogic web service policies

You cannot mix the two types of policies in the same web service, so you should decide which to use at the planning stage. Once you have added policies of one type to your web service, you cannot switch to the other type without deleting the policies that are currently attached. For example, if you have configured OWSM policies and later decide that you want to use Oracle WebLogic web service policies, you must delete the OWSM policies before you can attach the Oracle WebLogic web service policies.

The following sections describe how to use policies with web services:

Before you begin:

A detailed examination of all the tasks to be performed to use policies is outside the scope of this guide, but in general the steps you need to perform are:

  1. Decide on the policies you intend to use. For more information, see “Determining Which Predefined Policies to Use" in the Oracle Fusion Middleware Securing Web Services and Managing Policies with Oracle Web Services Manager.
  2. Attach the policies to a class or service. For more information, see Attaching Policies to JAX-WS Web Services.
  3. Configure a server with the correct key stores or other information that the policies need to work, and deploy the web service to the server. For more information, see “Securing Web Services" in the Oracle Fusion Middleware Securing Web Services and Managing Policies with Oracle Web Services Manager.
  4. Test the web service to ensure that the policies work as expected. For more information, see How to Test Web Services in a Browser.

Attaching Policies to JAX-WS Web Services

JDeveloper allows you to attach Oracle Web Service Manager (OWSM) policies or Oracle WebLogic web service policies to web services.

After you attach a policy to a web service, you need to configure the policies. For more information, see “Securing Web Services" in the Oracle Fusion Middleware Securing Web Services and Managing Policies with Oracle Web Services Manager.

You can attach policies to web services as described in the following sections:

Attaching Policies in the Web Service Wizard

You can attach policies to web services by setting the policies to attach in the web service wizard when creating a new web service or in the web service editor when updating a web service that already exists.

For more information about creating web services using the Create Java Web Service Wizard, see Creating Java Web Services .

To attach policies in the web service wizard:

In the Create Java Web Service wizard or web service editor, navigate to the Configure Policies page. For more information at any time, press F1 or click Help from within the dialog.

When attaching OWSM policies, you can view more information about the policy and its assertions as follows:

  • Click the Show Descriptions checkbox to display a description of each of the policies.

  • Click View to review the policy assertions in the policy file.

  • Click the Show Selected Policies checkbox to display only those policies that are currently selected.

Attaching Policies Using Annotations

You can attach policies to web services by adding policy annotations directly in the Java class. The Code Insight feature can help you, as described inHow to Work with Web Services Code Insight.

To attach policy annotations in the Java class:

  1. Open the web service class in the source editor.

  2. You can use the Code Insight to help you.

    Start typing the annotation, for example, @SecurityPolicy. When you pause, or click Alt+Enter, a popup appears from which you can choose the correct entry to complete the statement.

Annotations for Attaching OWSM Policies

You can attach a single policy using the weblogic.wsee.jws.jaxws.owsm.SecurityPolicy annotation in the Java class, for example:

@SecurityPolicy(uri = "oracle/wss11_message_protection_service_policy")

You can attach multiple policies as a composite using the weblogic.wsee.jws.jaxws.owsm.SecurityPolicies annotation containing a number of @SecurityPolicy elements, for example:

@SecurityPolicies( { 
   @SecurityPolicy(uri = "oracle/wss_http_token_service_policy"), 
   @SecurityPolicy(uri = "oracle/wss_oam_token_service_policy")
} )

Note:

To display a list of valid policies, enter uri="", place your cursor within the empty quotes, and click Ctrl+Alt+Spacebar.

For more information about using the policy annotations, see “Attaching Policies to Java EE Web Services and Clients Using Annotations" in Oracle Fusion Middleware Securing Web Services and Managing Policies with Oracle Web Services Manager.

Annotations for Attaching WebLogic Web Service Policies

You can attach a single policy using the weblogic.jws.Policy annotation in the Java class, for example:

@Policy(uri = "policy:Wssp1.2-2007-Https-UsernameToken-Plain.xml")

You can attach multiple policies as a composite using the weblogic.jws.Policies annotation containing a number of @Policy elements, for example:

@Policies( { 
   @Policy(uri = "policy:Wssp1.2-2007-Https-BasicAuth.xml"), 
   @Policy(uri = "policy:Wssp1.2-2007-Https-UsernameToken-Plain.xml")
} )

Note:

To display a list of valid policies, enter the uri="" argument, place your cursor within the empty quotes, and click Ctrl+Alt+Spacebar.

For more information about the policy annotations, see “Updating the JWS File with @Policy and @Policies Annotations" in Oracle Fusion Middleware Securing WebLogic Web Services for Oracle WebLogic Server.

Attaching Policies in the Properties Window

You can attach policies to web services using the Properties window.

To attach policies in the Properties window:

  1. With the web service class open in the source editor, choose Window > Properties to open the Properties window.

    For more information at any time, press F1 or click Help from within the Properties window.

  2. With the cursor in the public class or @WebService line of the class, navigate to the Policies node where you can choose to use OWSM Policies or Oracle WebLogic web service policies.

  3. Select Secure with OWSM Policies or Secure with WLS Policies.

    The Properties window is refreshed to display options to select single or multiple policies for the policy type selected (OWSM or WLS).

    Note:

    You cannot use both types of policy in the same web service. If you choose the wrong type, delete the lines containing the policy statements from the JAX-WS class so that you can choose again.

  4. Select a single policy from the Single Policy list, or click ... to attach multiple policies from the Edit Property: Multiple Policies dialog.

    When using the Edit Property: Multiple Policies dialog box to attach multiple OWSM policy files, click View to review the policy assertions in the policy file.

Attaching OWSM Policies to JAX-WS Web Service Clients

JDeveloper allows you to attach OWSM policies to JAX-WS web service clients.

After you attach an OWSM policy to a web service client, you need to configure the policies. For more information, see “Securing Web Services" in the Oracle Fusion Middleware Securing Web Services and Managing Policies with Oracle Web Services Manager.

Note:

For information about updating client applications to invoke web services that use WebLogic web service policies, see “Updating a Client Application to Invoke a Message-Secured Web Service" in Oracle Fusion Middleware Securing WebLogic Web Services for Oracle WebLogic Server.

You can attach OWSM policies to web service clients by:

Attaching OWSM Policies in the Web Service Client and Proxy Wizard

You can attach policies to web service clients by setting the policies to attach in the web service client and proxy wizard when creating a new web service client or in the web service client editor when updating a web service client that already exists.

For more information about creating web services using the Create Web Service Client an Proxy wizard, see Creating the Client and Proxy Classes.

To attach OWSM policies in the web service client:

In the Create Web Service Client an Proxy wizard or client editor, navigate to the Client Policy Configuration page. For more information at any time, press F1 or click Help from within the dialog.

When attaching OWSM policies, you can view more information about the policy and its assertions as follows:

  • Click the Show Descriptions checkbox to display a description of each of the policies.

  • Click View to review the policy assertions in the policy file.

  • Click the Show Selected Policies checkbox to display only those policies that are currently selected.

  • Click the Show only the compatible client policies for selection checkbox to view the policies that are compatible with the associated web service.

Attaching OWSM Policies Using Annotations

You can attach policies to web service clients by adding policy annotations directly to the injection target (@WebServiceRef), using one of the following annotations:

  • @weblogic.wsee.jws.jaxws.owsm.SecurityPolicy annotation to attach a single policy

  • @weblogic.wsee.jws.jaxws.owsm.SecurityPolicies annotation to attach multiple policies

The following shows an example of attaching OWSM security policies to web service clients using annotations.

package wsrm_jaxws.example;
import java.xml.ws.WebService;
import java.xml.ws.WebServiceRef;
import weblogic.wsee.jws.jaxws.owsm.SecurityPolicy;
import weblogic.wsee.jws.jaxws.owsm.SecurityPolicies;
import oracle.wsm.security.util.SecurityConstants.ClientConstants;
...
@WebServiceRef(name="MyServiceRef")
@SecurityPolicies({
   @SecurityPolicy(uri="policy:oracle/wss10_message_protection_client_policy"),
   @SecurityPolicy(uri="policy:oracle/authorization_policy")
})
Service service;
...

For more information, see “Attaching Policies to Java EE Web Services and Clients Using Annotations" in Oracle Fusion Middleware Securing Web Services and Managing Policies with Oracle Web Services Manager.

Note:

Attaching OWSM policies using Feature classes, as described in Overriding OWSM Policy Configuration Properties Using RequestContext, takes precedence over annotations.

To attach OWSM policies using annotations:

  1. Open the web service client in the source editor.

  2. Position your cursor in the injection target line, right-click the mouse, and select Add JEE Client Policy Annotations from the context menu.

    The Client Policy Configuration window is displayed that contains a list of OWSM security policies.

  3. Select the security policies that you wish to attach to the client.

    When attaching OWSM policies, you can view more information about the policy and its assertions as follows:

    • Click the Show Descriptions checkbox to display a description of each of the policies.

    • Click View to review the policy assertions in the policy file.

    • Click the Show Selected Policies checkbox to display only those policies that are currently selected.

    • Click the Show only the compatible client policies for selection checkbox to view the policies that are compatible with the associated web service.

  4. Click OK.

    The client code is updated with the appropriate annotations.

Attaching OWSM Policies Using Feature Classes

You can attach policies to web services by manually adding one of the following feature classes to the web service client:

  • weblogic.wsee.jws.jaxws.owsm.SecurityPolicyFeature class to attach a single policy

  • weblogic.wsee.jws.jaxws.owsm.SecurityPoliciesFeature to attach multiple policies

The following example shows how to use the SecurityPolicyFeature class to attach an OWSM policy to a web service client.

...
JAXWSService jaxWsService = new JAXWSService ();
weblogic.wsee.jws.jaxws.owsm.SecurityPolicyFeature securityFeature = new
weblogic.wsee.jws.jaxws.owsm.SecurityPolicyFeature {
new weblogic.wsee.jws.jaxws.owsm.SecurityPolicyFeature("policy:oracle/wss_username_token__over_ssl_client_policy") };
 
JAXWSServicePort  port =  jaxWsService.getJaxWsServicePort(securityFeature);
...

The following example shows how to use the SecurityPoliciesFeature class to attach multiple OWSM policy to a web service client.

...
weblogic.wsee.jws.jaxws.owsm.SecurityPoliciesFeature 
securityFeature = new weblogic.wsee.jws.jaxws.owsm.SecurityPoliciesFeature 
(new String[] { "policy:oracle/wss_username_token_over_ssl_client_policy", 
"policy:oracle/authorization_policy"});

For more information, see “Attaching Policies to Java EE Web Service Clients Using Feature Classes" in Oracle Fusion Middleware Securing Web Services and Managing Policies with Oracle Web Services Manager.

Note:

Attaching OWSM policies using Feature classes takes precedence over annotations (described in Overriding OWSM Policy Configuration Properties Using Annotations).

Overriding OWSM Policy Configuration Properties for the JAX-WS Web Service Clients

JDeveloper allows you to override configuration properties for policies attached to JAX-WS web service clients.

You can attach OWSM policies to web service clients by:

Overriding OWSM Policy Configuration Properties in the Web Service Client and Proxy Wizard

When attaching policies to web service clients using the web service client and proxy wizard, on the Client Policy Configuration page, select Override Properties... to display the Set Override Properties dialog. The configuration properties for the selected policies are displayed. Set the values as desired, and click OK.

In the Create Web Service Client an Proxy wizard or client editor, navigate to the Client Policy Configuration page, select Override Properties.... The Set Override Properties dialog displays enabling you to edit the configuration properties for the selected policies. For more information at any time, press F1 or click Help from within the dialog.

For more information about creating web services using the Create Web Service Client an Proxy wizard, see Creating the Client and Proxy Classes.

Overriding OWSM Policy Configuration Properties Using Annotations

You can override the default configuration properties of an OWSM security policy programmatically at design time using the @Property annotation when attaching an OWSM security policy using the @SecurityPolicy annotation. For more information, see “Attaching Policies to Java EE Web Services and Clients Using Annotations" in Oracle Fusion Middleware Securing Web Services and Managing Policies with Oracle Web Services Manager.

The following example shows how to attach a policy to a web service client using annotations. In this example, the @Property annotation is used to override the keystore recipient alias configuration property when attaching the client policy.

package wsrm_jaxws.example;
import java.xml.ws.WebService;
import java.xml.ws.WebServiceRef;
import weblogic.wsee.jws.jaxws.owsm.SecurityPolicy;
import weblogic.wsee.jws.jaxws.owsm.SecurityPolicies;
import oracle.wsm.security.util.SecurityConstants.ClientConstants;
...
@WebServiceRef(name="MyServiceRef")
@SecurityPolicies({
   @SecurityPolicy(uri="policy:oracle/wss10_message_protection_client_policy",
          properties = { 
             @Property(name="ClientConstants.WSS_KEYSTORE_LOCATION", 
                value="c:/mykeystore.jks")
          }
   ),
   @SecurityPolicy(uri="policy:oracle/authorization_policy")
})
Service service;
...
Overriding OWSM Policy Configuration Properties Using RequestContext

You can attach policies to web services by manually adding one of the following feature classes to the web service client:

  • weblogic.wsee.jws.jaxws.owsm.SecurityPolicyFeature class to attach a single policy

  • weblogic.wsee.jws.jaxws.owsm.SecurityPoliciesFeature to attach multiple policies

For more information, see “Overriding Client Policy Configuration Properties at Design Time" in Oracle Fusion Middleware Securing Web Services and Managing Policies with Oracle Web Services Manager.

Invoking JAX-WS Web Services Secured Using WebLogic Web Service Policies

When creating or editing a web service client from a WSDL that advertises a WebLogic web service policy, you can configure credentials to invoke the web service.

To invoke web services secured using WebLogic web service policies:

  1. Perform one of the following tasks:
  2. Navigate to the Select Credential page of the wizard.
  3. Select an existing set of credentials from the dropdown list or click New to define a new set of credentials.

    For help in completing the wizard, press F1 or click Help from within the wizard.

  4. Complete the wizard.

The client class is updated to include methods for setting the client credentials. Once added, you can modify the credential values, as required.

The following provides an example of the code that is generated and included in the client class:

@Generated("Oracle JDeveloper")
public static void setPortCredentialProviderList(
      Map<String, Object> requestContext) throws Exception 
{
   // Values used from credential preference: TestCredential
   String username = "weblogic";
   String password = "weblogic1";
   String clientKeyStore = "/C:/temp/ClientIdentity.jks";
   String clientKeyStorePassword = "ClientKey";
   String clientKeyAlias = "identity";
   String clientKeyPassword = "ClientKey";
   String serverKeyStore = "/C:/temp/ServerIdentity.jks";
   String serverKeyStorePassword = "ServerKey";
   String serverKeyAlias = "identity";
   List<CredentialProvider> credList = new ArrayList<CredentialProvider>();
  
   // Add the necessary credential providers to the list
   credList.add(getUNTCredentialProvider(username, password));
   credList.add(getBSTCredentialProvider(clientKeyStore, clientKeyStorePassword,
      clientKeyAlias, clientKeyPassword, serverKeyStore, 
      serverKeyStorePassword, serverKeyAlias, requestContext));
   credList.add(getSAMLTrustCredentialProvider());
   requestContext.put(WSSecurityContext.CREDENTIAL_PROVIDER_LIST, credList);
}

For information about how to program your web service client to invoke a web service that is secured using WebLogic web service policies, see “Updating a Client Application to Invoke a Message-secured Web Service" in the Oracle Fusion Middleware Securing WebLogic Web Services for Oracle WebLogic Server.

Editing or Removing Policies from JAX-WS Web Services

You can edit policies and remove them entirely from web services with either of the following:

Editing or Removing Policies Using the Web Service Editor

You can edit or remove policies using the web service editor.

To edit or remove policies using the web service editor:

  1. Right-click the web service in the Applications window, and choose Web Service Properties.

    For more information at any time, press F1 or click Help from within the dialog.

  2. Navigate to the Configure Policies page, where you can change the policies for the type of policies selected, change to using a different type of policies (for example, from OWSM policies to Oracle WebLogic web service policies), or choose No Policies. The web services is changed when you navigate away from this page of the editor.

Editing or Removing Policies Using Annotations in the Java Class

You can edit or remove policies using annotations in the Java class in the source editor.

To edit or remove policies using annotations in the Java class, pen the web service class in the source editor, where the Code Insight feature is available to help you. For more information, see How to Work with Web Services Code Insight. Edit or remove the annotations, as required.

Editing or Removing Policies Using the Properties Window

You can edit or remove policies using the Properties window.

To edit or remove policies using the Properties window:

  1. With the JAX-WS web service class open in the source editor, choose Window > Properties to open the Properties window.

    For more information at any time, press F1 or click Help from within the Properties window.

  2. With the cursor in the public class or @WebService line of the class, navigate to the Policies node:

    • To edit multiple policies, click ... to open the Edit Property: Multiple Policies dialog.

    • To edit a single policy, delete the name from the Single Policy list and choose another.

    • To change from one type of policy to another, delete all the policies so that you can start again.

How to Attach Policies to RESTful Web Services and Clients

This section describes how to attach policies to RESTful web services and clients created in JDeveloper.

Attaching Policies to RESTful Web Services

To secure RESTful web services, you can attach one of the OWSM predefined security policies described in “Which OWSM Policies Are Supported for RESTful Web Services?" in Oracle Fusion Middleware Securing Web Services and Managing Policies with Oracle Web Services Manager.

For more information about:

To attach policies to RESTful web services:

  1. In the Applications window, right-click the web.xml file located in the Web Content > WEB-INF folder.
  2. Select Secure RESTful Application.

    The Select Policy From List dialog opens.

  3. Select the security policy from the list.

    You can attach only one authentication policy and one authorization policy.

  4. Click OK.

    The security policy configuration is saved to the wsm-assembly.xml deployment descriptor file. If the wsm-assembly.xml file does not exist, it will be created.

Attaching Policies to RESTful Web Service Clients

To secure RESTful web services, you can attach one of the OWSM predefined security policies described in “Which OWSM Policies Are Supported for RESTful Web Services?" in Oracle Fusion Middleware Securing Web Services and Managing Policies with Oracle Web Services Manager.

You can attach OWSM policies to the RESTful client using one of the methods described in the following sections:

For more information about:

Attaching OWSM Policies in the RESTful Client and Proxy Wizard

You can attach policies to web service clients by setting the policies to attach in the RESTful client and proxy wizard when creating a new RESTful client.

For more information about creating web services using the Create RESTful Proxy Client wizard, see Creating RESTful Web Service Clients.

To attach OWSM policies to the RESTful client in the RESTful Client and Proxy Wizard:

In the Create RESTful Proxy Client wizard, navigate to the Client Policy Configuration page. For more information at any time, press F1 or click Help from within the dialog.

When attaching OWSM policies, you can view more information about the policy and its assertions as follows:

  • Click the Show Descriptions checkbox to display a description of each of the policies.

  • Click View to review the policy assertions in the policy file.

  • Click the Show Selected Policies checkbox to display only those policies that are currently selected.

  • Click the Show only the compatible client policies for selection checkbox to view the policies that are compatible with the associated web service.

Attaching OWSM Policies in the Client Policy Configuration Dialog

You can attach policies to web service clients by setting the policies to attach in the Client Policy Configuration dialog.

To attach OWSM policies to the RESTful client in the Client Policy Configuration dialog:

  1. In the Applications window, right-click the RESTful web service client file located in the Application Sources folder.

  2. Select Secure RESTful Client.

    The Client Policy Configuration dialog opens.

  3. Select the security policy from the list.

    You can attach only one authentication policy and one authorization policy.

  4. Click OK.

    The customizeClientConfiguration method is updated in the client to include the policy attachment.

For more information at any time, press F1 or click Help from within the dialog.

When attaching OWSM policies, you can view more information about the policy and its assertions as follows:

  • Click the Show Descriptions checkbox to display a description of each of the policies.

  • Click View to review the policy assertions in the policy file.

  • Click the Show Selected Policies checkbox to display only those policies that are currently selected.

  • Click the Show only the compatible client policies for selection checkbox to view the policies that are compatible with the associated web service.

Attaching OWSM Policies to RESTful Clients Programmatically

OWSM security policies can only be attached programmatically to RESTful web service clients, as described in “Attaching Policies to RESTful Web Service Clients Using Feature Classes" in Oracle Fusion Middleware Securing Web Services and Managing Policies with Oracle Web Services Manager.

Using the com.sun.jersey.api.client.config.ClientConfig, you can attach OWSM policies and override configuration properties, as shown in the following example. The following code attaches the oracle/wss_http_token_client_policy policy to the client, and overrides the CO_CSF_KEY configuration property with the value weblogic-csf-key.

package samples.helloworld.client;
 
import weblogic.jaxrs.api.client.Client;
import com.sun.jersey.api.client.WebResource;
import com.sun.jersey.api.client.config.ClientConfig;
import com.sun.jersey.api.client.config.DefaultClientConfig;
import oracle.wsm.metadata.feature.PolicyReferenceFeature;
import oracle.wsm.metadata.feature.AbstractPolicyFeature;
import oracle.wsm.metadata.feature.PolicySetFeature;
import oracle.wsm.metadata.feature.PropertyFeature;
...
    public static void main(String[] args) {
        ClientConfig cc = new DefaultClientConfig();
        cc.getProperties().put(AbstractPolicyFeature.ABSTRACT_POLICY_FEATURE,
             new PolicySetFeature(
                new PolicyReferenceFeature((
                  "oracle/wss_http_token_client_policy"), new 
                  PropertyFeature(SecurityConstants.ConfigOverride.CO_CSF_KEY,
                      "weblogic-csf-key"))));
        Client c = Client.create(cc);
...

Overriding OWSM Policy Configuration Properties for the RESTful Web Service Clients

JDeveloper allows you to override configuration properties for policies attached to RESTful web service clients.

You can override OWSM policy configuration properties for RESTful web service clients by:

Overriding OWSM Policy Configuration Properties in the Web Service Client and Proxy Wizard

When attaching policies to RESTful web service clients using the RESTful client and proxy wizard or client editor, navigate to the Client Policy Configuration page, select one or more policies to attach, and click Override Properties.... The Set Override Properties dialog displays enabling you to edit the configuration properties for the selected policies. For more information at any time, press F1 or click Help from within the dialog. Set the values as desired, and click OK.

For more information about creating RESTful web service clients using the Create RESTful Proxy Client wizard, see Creating RESTful Web Service Clients.

Overriding OWSM Policy Configuration Properties for RESTful Clients Using Feature Classes

When creating a RESTful web service client, when attaching an OWSM security policy programmatically, you can override the default configuration properties of an OWSM security policy using the oracle.wsm.metadata.feature.PropertyFeature class. For more information, see “Attaching Policies to RESTful Web Service Clients Using Feature Classes" in Oracle Fusion Middleware Securing Web Services and Managing Policies with Oracle Web Services Manager.

Editing or Removing Policies from RESTful Web Services and Clients

You can edit policies and remove them entirely from your RESTful web services and clients, as described in the following sections:

Editing or Removing Policies from RESTful Web Services

To edit or remove policies from RESTful web services:

  1. In the Applications window, right-click the web.xml file located in the Web Content > WEB-INF folder.

  2. Select Secure RESTful Application.

    The Select Policy From List dialog opens.

  3. Select the security policy from the list.

    You can attach only one authentication policy and one authorization policy.

  4. Click OK.

    The security policy configuration is saved to the wsm-assembly.xml deployment descriptor file. If the wsm-assembly.xml file does not exist, it will be created.

Editing or Removing Policies from RESTful Web Service Clients

Use any of the methods described in Attaching Policies to RESTful Web Service Clients to edit or remove policies from the RESTful web service client.

How to Use a Different OWSM Policy Store

The OWSM policy store is installed as part of JDeveloper. You can configure a different policy store, for example, to use a shared policy store. You can use a policy store that is available on the local file store or on a remote application server.

To use a different OWSM policy store:

  1. Choose Tools > Preferences to open the Preferences dialog, and navigate to the WS Policy Store page.

    For more information at any time, press F1 or click Help from within the Preferences dialog.

  2. To specify a policy store that is in the local file store, click File Store and enter the location of the policy store in the Override Location text box, or click Browse to browse to its location.
  3. To configure a policy store on a remote application server, click App Server Connection and select a remote application server connection from the Connections drop-down list.

    To add a new remote application server connection, click New.

Note:

The remote application server that you select must be configured with the OWSM Policy Manager. To verify that the OWSM Policy Manager has been properly configured, use the following URL: http://<host>:<port>/wsm-pm/validator. Enter the username and password for the server when prompted. If the OWSM Policy Manager is operational, then a list of the predefined policies is displayed with descriptions. For more information about troubleshooting the OWSM Policy Manager, see “Diagnosing Problems with Oracle OWSM" in the Oracle Fusion Middleware Administering Web Services.

How to Use Custom Web Service Policies

You can use custom policies from within JDeveloper. The process is different based on whether you are using custom OWSM policies or Oracle WebLogic web service policies, as described in the following sections:

Using Custom OWSM Policies

To use custom OWSM policies, perform one of the following steps:

  • Add a custom policy in the default policy store location at:

    JDEV_USER_HOME\system12.1.2.0.x.x.x\DefaultDomain\store\gmds\owsm

    If not set, JDEV_USER_HOME defaults to C:\Users\user-dir\AppData\Roaming\JDeveloper.

    Within this directory, policies must be included using one of the following directory structures:

    • Predefined OWSM policies: policies/oracle/policyname

    • Custom user policies: policies/policyname

    Note:

    When exporting policy files from the OWSM repository for use in JDeveloper, this directory structure is not maintained. You must ensure that when adding the exported policy to the JDeveloper environment that you extract the policies from the zip archive into the JDeveloper policy store using the required directory structure noted above. Otherwise, the policies will not be available in the JDeveloper environment. For more information about exporting policies from the OWSM repository, see “Understanding the Different Mechanisms for Importing and Exporting Policies" in the Oracle Fusion Middleware Securing Web Services and Managing Policies with Oracle Web Services Manager.

  • Specify a different policy store. For more information, see Using Custom Oracle WebLogic Web Service Policies.

    If you elect to use a policy store on a remote application server, you can import custom OWSM policies to the MDS repository on the remote application server using Fusion Middleware Control or WLST. For more information about importing policies to the OWSM MDS on the remote application server, see “Understanding the Different Mechanisms for Importing and Exporting Policies" in the Oracle Fusion Middleware Securing Web Services and Managing Policies with Oracle Web Services Manager.

For more information about creating custom policies, see “Creating Custom Assertions" in Oracle Fusion Middleware Developing Extensible Applications for Oracle Web Services Manager.

Using Custom Oracle WebLogic Web Service Policies

To use custom Oracle WebLogic web service policies, perform one of the following steps:

  • Place the custom policy JAR in the classpath and enable the WebLogic Server property weblogic.wsee.policy.LoadFromClassPathEnabled to true.

  • Place the custom policy JAR in WEB-INF/policies (Web application) or META-INF/policies (EJB).

  • Place the custom policy XML file in WEB-INF (Web application) or META-INF (EJB).

To access the policies:

  • When using the @Policy annotation, ensure that you add the policy prefix; for example, policy:mypolicy.xml.

  • Click the Add Custom Policies button on the Configure Policies page of the Java Web Service Editor and select the custom policy files using the Select Custom Policy Files dialog box.

Deploying Web Services

JDeveloper provides tools that help you create and deploy web services to Oracle WebLogic Server, where they run within a Java EE container. You can:

How to Deploy Web Services to Integrated WebLogic Server

You can deploy a web service generated in JDeveloper to Integrated WebLogic Server. For more information, see Running Java EE Applications in the Integrated Application Server.

To deploy a web service to Integrated WebLogic Server:

  1. If not already started, start the Integrated WebLogic Server.

    Note:

    The first time you start the Integrated WebLogic Server, a dialog is displayed prompting you to enter a password for the administrator ID for the default domain. When you click OK, the default domain is created and the Integrated WebLogic Server is started. You only need to do this once.

  2. In the Applications window, right-click the project containing the web service, and choose Deploy > Web Services.
  3. In the Deploy Web Services dialog, on the Deployment Action page, select Deploy to Application Server and click Next.
  4. On the Select Server page, select IntegratedWebLogicServer and click Next.
  5. On the WebLogic Options page, configure the WebLogic Server deployment options, specifying:

    • Whether to deploy the application to all or select instances in the domain. By default the application is deployed to all instances.

    • Whether the application is registered as a shared library. By default, it is registered as a standalone application.

  6. Click Next to view the Summary page or Finish to deploy the web services.

How to Deploy Web Services to a Standalone Application Server

You can deploy a web service generated in JDeveloper to one of the following standalone application servers:

  • Oracle WebLogic Server

  • JBoss 5.x

  • Tomcat 6.x

  • WebSphere Server 7.x

To deploy a web service to a standalone application:

  1. Ensure that the standalone application server is running.
  2. In the Applications window, right-click the project containing the web service and choose Deploy to > connection. From the list of available connections choose the application server connection that you specified when you created the web service.

How to Undeploy Web Services

If you have deployed the web service to Integrated WebLogic Server you do not need to undeploy it as the integrated server resets itself to the new application and project whenever it is started.

If you have deployed the web service to a server using an application server connection, you can undeploy it from the Resources window.

To undeploy a web service:

  1. In the Application Server window, select the application server connection you have been using and expand Web Services.
  2. Right-click application-name_project-name_ws and choose Undeploy.

Testing and Debugging Web Services

Developer provides a number of ways that you can test and debug web services:

In addition to the methods described in this section, you can use the HTTP Analyzer to examine the content of web services over HTTP, similar to examining other packet information. For more information, see Monitoring and Analyzing Web Services.

How to Test Web Services in a Browser

Once you have created and deployed a web service, you can test it to ensure that it returns what you expect by running it in the browser using the Web Services Test Client. For more information about using the Web Services Test Client to test web services, see “Testing Web Services" in Oracle Fusion Middleware Administering Web Services.

How to Debug Web Services

The debugging tools allow you to debug web services created using the web service wizards. This is similar to debugging Java programs; you can debug a web service locally or remotely by running a client against the service in debug mode. You set breakpoints in the client, which is the proxy to the web service, to investigate the functionality of the service.

JDeveloper lets you debug a web service that is running in the Integrated WebLogic Server locally, or a web service that is deployed remotely.

As you debug your web service, JDeveloper also provides a number of special-purpose debugging windows to help you analyze your code and identify problem areas. You can open the debugger windows by choosing Window > Debugger, then choosing a window from the menu. The Data window is particularly useful for debugging web services. For more information, see Using the Data Window for Debugging Web Services.

You can use the HTTP Analyzer to examine and monitor HTTP request and response packets. It 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. For more information, see How to Examine Web Services using the HTTP Analyzer .

Debugging Web Services Locally

Once the web service is running in Integrated WebLogic Server, you can create a proxy client to the web service. This client contains methods to run against each exposed method in the web service, and you can add your own code and set breakpoints to examine how the web service runs.

You can quickly debug a web service created in JDeveloper by debugging it locally using one of the following methods:

  • Insert breakpoints in the web service class, then run a proxy client against it. This allows you to debug the service class itself.

  • Insert breakpoints in the client.

Before locally debugging a web service, you should turn off the proxy settings. Remember to turn the proxy settings back on when you have finished debugging.

To debug a web service locally:

  1. First, turn off the proxy settings, as described in Disabling the Use of a Proxy Server When Accessing the Internet.
  2. Run the web service in debug mode. In the Applications window, right-click the web service, and choose Debug.

    The Integrated WebLogic Server is started (or restarted) in debug mode, and the web service is deployed to it. The results are displayed in the log window.

  3. Create a web service client, as described in How to Create JAX-WS Web Service Clients.

    A proxy container is generated and displayed in the Applications window, with a Java class called webservicePortClient.java displayed in the source editor.

  4. In the source editor, locate the comment // Add your own code to call the desired methods, and enter some code.
  5. If you are debugging the client to the web service, add one or more breakpoints, right-click and choose Debug.

    Alternatively, if you have set breakpoints in the web service class, choose either Debug or Run from the context menu.

    The debugger operates as for any Java class. For more information, see Running and Debugging Java Projects .

Debugging Web Services Remotely

JDeveloper lets you debug a web service that is deployed remotely.

The web service could be running on Oracle WebLogic Server on the local machine, or it could be running on a service located on a remote machine. In either case, you will need a connection to the server, and the server must be running in debug mode.

When you remotely debug a web service, you have to start the server in debug mode and deploy the web service to it. You can then create a client to the service and set breakpoints in it, and run the client in debug mode.

To debug a web service remotely:

  1. Run the remote server in debug mode.
  2. Deploy the web service. For more information, see Deploying Web Services.
  3. Create a web service client, as described in How to Create JAX-WS Web Service Clients.
  4. In the source editor, locate the comment // Add your own code to call the desired methods, and enter some code.
  5. Add one or more breakpoints, right-click and choose Debug.

    The debugger operates as for any Java class. For more information, see Running and Debugging Java Projects .

Using the Data Window for Debugging Web Services

JDeveloper provides a number of special-purpose debugging windows to help you analyze your code and identify problem areas. The Data window is particularly useful for debugging web services.

The Data window displays information about variables in your program for the current context. By default, the Data window displays local variable information while debugging a program. For web services, the Data window also provides additional information derived from the web service. For example, the returned values for the following method calls are displayed when debugging a proxy class (this is not an exhaustive list):

  • com.sun.xml.ws.client.RequestContext.getEndpointAddressString()

  • javax.xml.ws.Binding.getBindingID()

  • javax.xml.ws.BindingProvider.getResponseContext()

To open the Data debugger window choose Window > Debugger > Data. For more information about accessing and using the other debugging windows, see Using the Debugger Windows.

While debugging, you can use filters to reduce the number of fields that are displayed when you expand an object in the Data window through the Object Preferences dialog. Displaying fewer fields narrows your focus when debugging and may make it easier to locate and isolate potential problems in your program. For more information, see How to Show and Hide Fields in the Filtered Classes List.

How to Test Web Services with JUnit

JDeveloper provides support for JUnit regression testing for your web services. JUnit is an open source Java regression testing framework that is available as an optional feature in JDeveloper. You can use JUnit to write and run tests that verify your code. For detailed information about JUnit, visit the JUnit web site, http://www.junit.org.

To use JUnit, you need to install the JUnit extension. After you install the JUnit extension, you can create a JUnit test class for the web services that you want to test.

To run a JUnit test on a web service:

  1. Install the JUnit extension from the JDeveloper Help menu. For more information, see How to Install Extensions with Check for Updates.
  2. Right-click a web service in the Applications window and choose Create JUnit class for Web Service. This will create a JUnit test class.
  3. Edit the generated class.

    The generated test class can run in the JUnit runtime; however, in order to gather meaningful results, you need to instrument the test class (for example, with assertions) to reflect your environment. There is one generated test method in the generated JUnit class per web service method, which can each be run in the JUnit test harness.

By default, when the generated test is run, JUnit sets up the web service endpoint in a web service endpoint publisher. You can, however, remove the web service endpoint publisher from the generated JUnit test class and set the web service endpoint to any application server where the web service is pre-deployed.

How to View Web Service Message Logs for an Application Server

If you have attached a log policy to a web service that is deployed on an application server, the log policy writes the SOAP message to a message log. The web service message log can be accessed using the Application Servers window.

The application server log files are available under the Log Files folder under each application server node for both integrated and remote servers. Under each Log Files folder there is a OWSM Logs folder that contains the web service log files.

To view the message log of a web service deployed to an application server

  1. If necessary, open the Application Servers window by choosing Window > Application Servers.
  2. Expand the application server that the web service is deployed on.
  3. Expand the Log Files folder to access the OWSM Logs folder.
  4. Expand the OWSM Logs folder, then right-click a log file (for example, diagnostic.log) and choose View from the context menu.

    The log contents are displayed in read-only mode in the editor.

Monitoring and Analyzing Web Services

You can analyze web services in a number of ways, for example to check whether they conform to Web Services-Interoperability Organization (WS-I) Basic Profile 1.1 or to investigate the contents of SOAP packets.

The WS-I was formed by Oracle and other industry leaders to promote the interoperability of web services technologies across a variety of platforms, operating systems, and programming languages. JDeveloper provides tools that allow you to test the interoperability of web services by checking that the services conform to the WS-I Basic Profile 1.1. For more information about WS-I, see the web site of The Web Services-Interoperability Organization (WS-I) at http://www.ws-i.org.

You can analyze a web service for conformity to WS-I standards. The service can either be one you have created that is listed in the Applications window, or it can be a web service that you have located using a UDDI registry that is listed in the Resources window. Alternatively, you can create a client and proxy classes to access a deployed web service and use the HTTP Analyzer to create a log file that you then use to analyze whether the web service conforms to WS-I standards.

In order to monitor a web service against the WS-I Basic Profile, or analyze the log file resulting from monitoring a service, you need to download and register a WS-I compliant analyzer. Before you can register a WS-compliant analyzer, you need to install the WS-I Testing Tools extension

The following sections describe how to monitor and analyze web services:

How to Download and Register a WS-I Analyzer

In order to use a WS-I compliant analyzer to analyze a web service, you need to download one to your machine and register it with JDeveloper.

To download and register a WS-I analyzer:

  1. Download and install a WS-I analyzer from http://www.ws-i.org.
  2. Install the WS-I Testing Tools extension from the JDeveloper Help menu. For more information, see How to Install Extensions with Check for Updates.
  3. In JDeveloper choose Tools > Preferences and select WS-I Testing Tools.
  4. Enter details of where your WS-I compliant analyzer is installed.

    For detailed help in using this dialog, press F1 or click Help from within the dialog.

How to Analyze Web Services in the Applications Window

You can produce a report of a web service that is listed in the Applications window, or that you have located using a UDDI registry and that is listed in the Resources window to see whether it conforms with WS-I Basic Profile 1.1 standards. Before you can do this you must have downloaded a WS-I compliant analyzer to your machine and registered it with JDeveloper.

The parts of the WS-I Basic Profile that check the content of messages sent between a web service and a client cannot be used until the client is run against the service. When invoked from the Applications window, the WS-I analyzer can only analyze the description of the service in its WSDL document.

To analyze a web service:

  1. With the web service selected in the navigator, choose WS-I Analyze WSDL... from the context menu.
  2. The WS-I Analyze Web Service wizard is displayed.

    For detailed help in using the wizard, press F1 or lick Help from within the wizard.

  3. Once the wizard has run, a report of the analysis called wsi-report.html is displayed in JDeveloper. The report may take a few moments to appear, depending on whether you are analyzing a local web service or one deployed elsewhere on the Web.

How to Create and Analyze Web Service Logs

You can use the HTTP Analyzer to produce a log from running a web service client. Then you can use a WS-I compliant analyzer that you have downloaded and registered with JDeveloper to check whether the web service complies with WS-I standards.

Because you are running the analyzer against a client to the web service, discovery, description and messages of the service are reported on.

Note:

If you are working within a firewall, make sure that the proxy server exceptions do not include the IP address of the machine on which the web service is running.

To create and analyze a web service:

  1. Create a client to the web service you want to analyze.

    • To an external web service.

    • For a web service that you have created and deployed to Oracle WebLogic Server, create a client stub or proxy.

    • For a web service that you have just created in JDeveloper, ensure that the web service is running on the embedded server by selecting Run from the web service context menu. In the navigator, select Create Client for Web Service Annotations from the web service context menu. You need to make sure that the web service endpoint in the WSDL is exactly the same as the _endPoint variable in the generated proxy.

  2. Start the HTTP Analyzer. Choose Tools > HTTP Analyzer, and in the monitor click Start This image is described in the surrounding text.
  3. Run the client in one of the following ways:

    • Select Run from the context menu of the client in the source editor.

    • Select Run from the context menu of the client in the navigator.

  4. Once you have received the response you expect from the web service, stop the HTTP Analyzer by clicking Stop This image is described in the surrounding text..
  5. Click WS-I Analyzer This image is described in the surrounding text to launch the WS-I Analyze wizard, and follow the instructions in the wizard. The message log records the progress, and the results are displayed in the HTTP Analyzer.

What You May Need to Know About Performing an Analysis of a Web Service

There are a number of reasons why you may find you have problems when performing an analysis of a web service. Some of these are outside the scope of the JDeveloper documentation, but there are two issues you might come across:

When the Message section of the wsi-report.html is missing all inputs

This can happen when the WSDL for an external web service has an endpoint that contains the machine name in upper or mixed case, and the client generated by JDeveloper has the _endPoint variable with the machine name in lower case. This is similar to the case discussed in How to Analyze Web Services Running in the Integrated Server.

The workaround is to import the WSDL into JDeveloper so that it is listed in the navigator, then edit the WSDL so that the machine name is lower case. Then you can generate the client (and associated proxy classes) and run it with the HTTP Analyzer running.

To import the WSDL into the navigator:

  1. Create a new WSDL document, accepting the defaults.

  2. Open the WSDL document in a browser. View the source of the document, and copy the XML source of the WSDL.

  3. Replace the contents of the WSDL document you have just created with the source from the WSDL document of the web service you want to use.

When the Discovery section of the wsi-report.html is missing all inputs

The Discovery section of wsi-report.html reports on the REGDATA artifacts that are used by web services you locate in a UDDI registry. If you have created a report of a web service that you have not located using a UDDI registry, then it all the Inputs in this section of the report will be missing.

How to Analyze Web Services Running in the Integrated Server

The WS-I compliant analyzer correlates messages in the log file against a set of standard assertions, and in particular the soap:address subelement of the service element in the WSDL document must exactly match that specified in the wsi-log.xml messageEntry's senderHostAndPort or receiverHostAndPort, otherwise the messages will not be analyzed for WS-I compatibility.

Changing the Endpoint Address

When the web service is run in the Integrated Server (by choosing Run from the web service context menu), and you create the log by running the HTTP Analyzer while running a generated client against the web service, you may need to change the web service endpoint in the WSDL or the _endPoint variable in the generated client before creating the log file of the client running.

To make sure the web service endpoint is the same as the _endPoint variable in the proxy:

  1. Edit the WSDL document of the web service by double-clicking on the WSDL document in the navigator.
  2. Navigate to the soap:address subelement, and edit the endpoint using one of the following values:

    • IP_address:integrated_port_no (the default integrated port number is 8988)

    • hostname (lower-case)

Changing the Endpoint Address Without Modifying the WSDL

For JAX-WS web services, you can change the endpoint address without modifying the WSDL, as shown in the following example:

import java.net.URI;
import java.net.URL;
import java.util.Map;
import javax.xml.ws.BindingProvider;
import javax.xml.ws.WebServiceRef;
import project2.proxy.Hello;
import project2.proxy.HelloService;

public class HelloPortClient
{
   @WebServiceRef
   private static HelloService helloService;

   public static void main(String [] args) {
      helloService = new HelloService();
      Hello hello = helloService.getHelloPort();
      setEndpointAddress(hello, "http://some.new.addr/endpoint");
      hello.sayHello("Bob");
   }

   public static void setEndpointAddress(Object port, String newAddress) {
      assert port instanceof BindingProvider : 
        "Doesn't appear to be a valid port";
      assert newAddress !=null :"Doesn't appear to be a valid address";

      //
      BindingProvider bp = (BindingProvider)port;
      Map <String, object> context = bp.getRequestContext();
      Object oldAddress = context.get(
         BindingProvider.ENDPOINT_ADDRESS_PROPERTY);
      context.put(
         BindingProvider.ENDPOINT_ADDRESS_PROPERTY, newAddress);
   }
}

How to Examine Web Services using the HTTP Analyzer

You can use the HTTP Analyzer to examine the network traffic of a client connecting to a JAX-WS or RESTful web service. For more information, see Using the HTTP Analyzer with Web Services.

The HTTP Analyzer enables you to:

  • Observe the exact content of the request and response TCP packets of your web service.

  • Edit a request packet, resend the packet, and see the contents of the response packet.

  • Test web services that are secured using policies; encrypted messages will be decrypted.

You can use the results to debug a locally or remotely deployed web service.

Note:

In order to use the HTTP Analyzer, you may need to update the proxy settings. For more information, see How to Use Proxy Settings and .

To examine the packets sent and received by the client to a web service:

  1. Create the web service.
  2. Either run the web service in the Integrated WebLogic Server by right-clicking the web service container in the navigator and choose Run web_service.

    or

    Deploy and run the web service on Oracle WebLogic Server. For more information, see Deploying Web Services.

  3. Start the HTTP Analyzer by selecting Tools > HTTP Analyzer. It opens in its own window in JDeveloper.
  4. Run the HTTP Analyzer by clicking Start HTTP Analyzer This image is described in the surrounding text.
  5. Run the client proxy to the web service. The request/response packet pairs are listed in the 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.

  6. You can examine the contents of the HTTP headers of the request and response packets to see the SOAP structure (for JAX-WS web services), the HTTP content, the WADL structure (for RESTful services), the Hex content or the raw message contents by choosing the appropriate tab at the bottom of the HTTP Analyzer Test window.
  7. You can test web services that are secured using policies by performing one of the following tasks:

    • Select an existing credential from the Credentials list.

      JDeveloper delivers with a set of preconfigured credentials, HTTPS Credential.

    • Click New to create a new credential. In the Credential dialog, define the credentials to use in the HTTP Analyzer Test window. You can define one of the following credentials: HTTPS, username token, X509, or STS. For more information, see Using SSL with the HTTP Analyzer.