16 Developing Applications Using Web Services

This chapter describes how JDeveloper provides powerful tools that help you discover and use existing web services, and develop and deploy new web services.

This chapter includes the following sections:

16.1 About Developing Applications using 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.

You can create web service clients to access existing web services. If you use web services in your application, you can create bottom-up (starting from Java) and top-down (starting from WSDL) web services as follows:

  • 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 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 SOAP web services from the underlying Java implementation (bottom up)

    • Create web services from the WSDL (top down).

    • Create RESTful web services.

  • Secure web services using policies

  • Test and debug web services

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

  • Publish web services to a UDDI registry

Once deployed, your web services can then be accessed and used in other applications.

16.1.1 Discovering and Using Web Services

You can quickly create a client to an existing web service in order to use it in your application. You can view all web services in the application under the Web Services folder in the Application Navigator.

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 Section 16.3, "Working with Web Services in a UDDI Registry".

16.1.2 Developing and Deploying Web Services

You can create web services from Java classes, the remote interface of EJBs, and an ADF Business Components service session bean wrapped as an EJB. 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. For more information, see Section 16.5, "Creating SOAP Web Services (Bottom-Up)".

Alternatively, you can create a web service starting with a WSDL, as a top-down web service. For more information, see Section 16.6, "Creating SOAP Web Services from WSDL (Top Down)".

Finally, you can develop web services that are based on Representational State Transfer (REST). A RESTful web service is a simple interface that transmits data over a standardized interface (such as HTTP) without an additional messaging layer, such as SOAP. For more information, see Section 16.7, "Creating RESTful Web Services"

JDeveloper also supports a set of standard Java-to-XML type mappings. You can also create custom serializers for types of objects that are not automatically supported. For more information, see Section 16.2, "Using JDeveloper to Create and Use Web Services".

16.2 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.

16.2.1 How to Use Proxy Settings and JDeveloper

By default, JDeveloper uses the proxy settings from the default browser on the same machine. If you have problems making connections from JDeveloper, for example, connecting to an application server that is on the same machine as JDeveloper, you may need to change the proxy server settings you use.

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.

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.

To exclude an IP address:

  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. Add the IP address to the Exceptions list.

To turn off use of the browser proxy server:

  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. Deselect Use HTTP Proxy Server.

16.2.2 How to Set the Context Root for Web Services

The context root 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. You set the context root at the project level.

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.

To set the context root:

  1. In the Application Navigator, 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. Expand Project Source Paths and select Web Application.

  3. Either accept the default HTML Root Directory or enter a new value.

    Click Browse to browse the local directory.

16.2.3 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.

16.2.4 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 ones 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://java.sun.com/javase/technologies/desktop/javabeans/api/index.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. These are listed in the table below, which shows the primitive XML Schema types and arrays of primitive XML Schema types that are supported as parameters, and the return values for web services. In addition, a service method can accept and return a single piece of XML element data, passed as an org.w3c.dom.Element.

Table 16-1 XML schema type mapping to Java types

XML Schema type Java type

string

java.lang.String

boolean

java.lang.Boolean

decima

java.lang.Double

float

java.lang.Float

double

java.lang.Double

dateTime

java.util.Date

time

java.util.Date

date

date java.util.GregorianCalendar

base64Binary

java.lang.Byte[]

normalizedString

java.lang.String

integer

java.lang.Integer

long

java.lang.Long

int

java.lang.Integer

short

java.lang.Short

byte

java.lang.Byte


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.

16.2.5 How to Work with PL/SQL Web Services and Types

This section describes the limitations for which PL/SQL web services cannot be created for a particular circumstance:

Overloaded Program Units

A program unit that shares its name with another program unit in the same package is an overloaded program unit. At runtime the WSDL processor cannot determine which program unit to execute when there is more than one program unit with the same name. Therefore, the PL/SQL program units cannot be deployed as web services.

You can avoid the problem of overloaded program units that you can adapt to suit your requirements. Consider the following example of a PL/SQL package containing the following program:

-- promotes an employee to the specified rank
PROCEDURE promote_emp(empno IN NUMBER, rank IN NUMBER);

-- promotes an employee to the rank above their current rank
PROCEDURE promote_emp(empno IN NUMBER);

You can workaround the overloaded types in one of the following ways:

  • If you are able to change the existing package, you can add the two procedures shown below to the package, and publish the web services from the new procedures.

    or

  • You can add the two procedures shown below to a new package, and publish the web services from the new package.

The new procedures are:

-- promotes an employee to the specified rank
PROCEDURE promote_emp_to_rank(empno IN NUMBER, rank IN NUMBER)
IS
BEGIN
promote_emp(empno, rank);
END;

-- promotes an employee to the rank above their current rank
PROCEDURE promote_emp_to_next_rank(empno IN NUMBER) IS
BEGIN
promote_emp(empno);
END;

BFILE Type

The PL/SQL type BFILE can only be used as an OUT argument or as a function return value.

BCLOB Type

The PL/SQL type BCLOB is not supported.

OUT and IN-OUT Parameters

When you publish a program unit with OUT or IN-OUT parameters, these are transferred back to the caller in a return type structure with one attribute for each OUT or IN-OUT parameter. For example, a service with the following signature:

PROCEDURE a_proc(val1 IN VARCHAR2, val2 IN OUT NUMBER, val3 OUT INTEGER) 

Returns the final values of val2 and val3 in a generated result class. You can use accessor methods on the generated class to access these values.

Creating PL/SQL web services from PL/SQL records

JDeveloper does not allow you to create web services directly from PL/SQL packages that use PL/SQL records. If your organization uses PL/SQL packages that have been migrated from earlier versions of the Oracle database, you may find that you want to expose some functionality as web services and be unable to do so because the packages accept and return parameters that are record types, rather than object types.

You can use Oracle JPublisher on the packages that contain record types. For more information, see Section 28.3.1, "How to Use JPublisher".

A SQL file is produced that you run against your database to create equivalent packages that contain object types. You can then use the new packages to create your PL/SQL web services in the usual manner.

Stored procedures of the same name which are accessible in more than one schema

On Oracle9i Database release 2, when a stored procedure or function of the same name and the same package name is accessible in more than one schema, then the SQLJ translator invoked during publication of PL/SQL web services will fail.

In order to resolve this problem, ensure that packages to be published are visible only in one schema, and that no other packages in other schemas share the same name.

Ref Cursors Return Types

You cannot create a web service from a packages that uses ref cursor as a return type, for example:

PACKAGE TEST AS
type EmpCurType is ref cursor;
function EmpData return TEST.EmpCurType;
END;

SYS Schema

In order to prevent an arbitrary user from assuming SYS privilege, a connection cannot be specified from the middle tier as SYS. This means that you cannot create a web service from a package in the SYS schema.

If you need to access a PL/SQL package in the SYS schema from the middle tier, for example, to create a web service in JDeveloper, log on to the database as SYS, and grant package EXECUTE privileges to the user you then use to create the JDeveloper database connection.

Types Declared Within a Package Spec

PL/SQL packages can have types declared within the package spec, however these packages cannot be published as web services. To avoid this, create the types outside the scope of the package.

PL/SQL nested tables

JDeveloper does not allow you to create web services directly from PL/SQL packages that use PL/SQL nested tables.

16.2.6 How to Choose Your Deployment Platform

When you create a web service using the web services wizards, you are offered a choice of deployment platforms, as defined in Table 16-2. 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.

Table 16-2 Deployment Platforms

Deployment Platform Description

J2EE 1.4 JAX-RPC with support for WebLogic Server 10.3

Generates a JAX-RPC web service that is configured for deploying to Oracle WebLogic Server 10.3.

Java EE 1.5 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. 5. This option provides support for deploying to WebLogic Server 10.3 with Java annotations using the JAX-WS annotation specification.

Java EE 1.5 with support for JAX-WS RI

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


16.2.7 How to Work with Web Services Code Insight

The web services Code Insight completes annotations when typing in a Java class, and is available for WSDL documents in the XML editor (that is, 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 menu > Preferences > Code Editor > Code Insight.

Note:

Code Insight does not work with Java classes for JAX-RPC web services, only with Java classes for JAX-WS web services.

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 1.5, 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 1.5, with support for JAX-WS RI. In this case, JDevleoper adds:

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

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

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 either the Java class or WSDL, click the Audit fix icon and select how you would like to reconcile the discrepancy.

16.2.8 How to Migrate JAX-RPC 10.1.3 Web Services

You can migrate web services created as J2EE 1.4 JAX-RPC web services in JDeveloper 10.1.3.n.

Note:

You cannot migrate EJB 2.1 web services because they are deprecated in this version of JDeveloper. You cannot migrate JMS web services because they are Oracle-proprietary and no longer supported.

The following actions are performed during the upgrade:

The WSDL is not changed. After performing the upgrade, you can use the Edit Web Service dialog to make any additional changes.

The limitations of the migrated service are:

  • JAX-RPC web services in this version of JDeveloper only support SOAP 1.1, so support for SOAP 1.2 is removed.

  • Any attached policies are removed. You can attach new policies by editing the web service and applying the appropriate Oracle WebLogic Server policies. For more information, see Section 16.9.3, "How to Attach Policies to Web Services".

    Note:

    JAX-RPC web services can only use Oracle WebLogic Server security policies.
  • Support for the previous version of stateful services is removed. You can configure support for the current version of stateful services in the Edit Web Services dialog. For more information, see Section 16.10, "Editing and Deleting Web Services".

  • Support for REST is removed.

  • Methods with collection return type, which are not supported, are disabled in the implementation.

To migrate a web service:

  1. In the Application Navigator, select Open Application from the dropdown list. Open the application that contains the web service.

    The migration wizard is automatically invoked enabling you to migrate the application and projects. For more information at any time, press F1 or click Help from within the wizard.

  2. On the Webapp 2.5 Migration page of the Migration Wizard, deselect Migrate to Webapp 2.5. JAX-RPC is compatible with version 2.4 of web.xml, not version 2.5.

  3. To upgrade the web service, in the Application Navigator, right-click the web service container and choose Upgrade Web Service to WLS JAX-RPC Configuration.

  4. Read the Confirm Upgrade message and click Yes. The web service is upgraded to use the JAX-RPC 11g Web Services library and regenerated.

  5. If necessary, edit the web service to make any additional changes.

16.3 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 Web Services Description Language (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:

16.3.1 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.

16.3.1.1 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 Resource Palette, in the Connections panel.

To create a new connection:

  1. In the Application Navigator, select the project.

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

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

  4. In the Items list, double-click UDDI Registry Connection 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.

Alternatively, you can create the connection directly in the Resource Palette as described in Section 6.9, "Using WebDAV with JDeveloper".

16.3.1.2 Editing the Name of UDDI Registry Connections

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

To change the inquiry endpoint of a registry:

  1. In the main menu, choose View > Resource Palette. By default, the Resource Palette is displayed to the right of the JDeveloper window.

  2. In the Resource Palette, expand UDDI Registry.

  3. From the context menu of the UDDI registry connection you want to edit, choose Properties.

    The reentrant UDDI Registry Connection wizard is launched.

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

16.3.1.3 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 Section 16.3.2, "How to Configure the View of UDDI Registry Connections".

To change the view of a registry:

  1. In the main menu, choose View > Resource Palette. By default, the Resource Palette is displayed to the right of the JDeveloper window.

  2. In the Resource Palette, expand the UDDI Registry.

  3. From the context menu of the UDDI registry connection you want to edit, choose Render Business Perspective or Render Category Perspective.

16.3.1.4 Refreshing UDDI Registry Connections

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

To refresh a connection:

  1. In the main menu, choose View > Resource Palette. By default, the Resource Palette is displayed to the right of the JDeveloper window.

  2. In the Resource Palette, expand the UDDI Registry.

  3. From the context menu of the UDDI registry connection you want, choose Refresh.

16.3.1.5 Deleting UDDI Registry Connections

When no longer needed, you can delete a UDDI registry connection from the Resource Palette.

To delete a connection:

  1. In the main menu, choose View > Resource Palette. By default, the Resource Palette is displayed to the right of the JDeveloper window.

  2. In the Resource Palette, expand the 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.

16.3.2 How to Configure the View of UDDI Registry Connections

When you create the connection, as described in Section 16.3.1, "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.

16.3.2.1 Choosing Business View

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

  • businessEntity: 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 Resource Palette.

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

  • bindingTemplate: 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.

16.3.2.2 Choosing Category View

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

  • UDDI Types: Search by UDDI type.

  • NAICS: Specify the type of industry.

  • ISO 3166: Search by location.

  • UNSPSC: Search by type of service.

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.

16.3.3 How to Search for Web Services in a UDDI Registry

You can search a UDDI registry connection in the Resource Palette 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 Section 16.3.1, "How to Define UDDI Registry Connections".

  2. In the Resource Palette, search for the web service. For more information, see Section 3.7, "Working with the Resource Palette".

16.3.4 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 Resource Palette.

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:

  1. Open the Resource Palette.

    In the main menu, choose View > Resource Palette. By default, the Resource Palette 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

  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.

16.3.5 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 service:

  1. In the Resource Palette, expand the UDDI registry connection, and navigate to the endpoint for the service.

  2. Right-click the service, and choose View Report.

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

16.3.6 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 navigator. 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 Section 16.3.1.1, "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 navigator, 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.

16.4 Creating Web Service Clients

JDeveloper makes it easy to use a web service in your application by allowing you to create 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 web service clients:

16.4.1 How to Create 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 and attach policies, 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) or stub (JAX-RPC) and service interface for each exposed port and lists them in the Application Navigator. 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.

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

  1. In the Application Navigator, select the project you want to use.

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

  3. In the Categories list, select Web Services.

  4. In the Items list, double-click Web Services to launch t 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.

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

  1. Right-click the web service container in the Application Navigator, and choose:

    • For a JAX-WS web service, Create Client for Web Service Annotations.

    • For a JAX-RPC web service, Generate Web Service Proxy.

  2. The Create Web Service Client and Proxy wizard opens and is prepopulated 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.

16.4.2 How to Use Web Service Client and Proxy Classes

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:

  • Stand-alone 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 Section 16.4.7, "How to Reference Web Services Using the @WebServiceRef Annotation"

16.4.2.1 How to Use a Stand-Alone Client Application

A stand-alone 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 WebLogic Server.

To use the generated client proxy classes in a stand-alone client:

  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 Application Navigator.

  2. Locate the comment // Add your own code here, which is in a try-catch block in the main method, and add the appropriate code to invoke the web service.

  3. Run the client.

16.4.2.2 How to Use the 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 use the generated client proxy classes in a JSE component:

  1. Copy the generated client proxy classes to your JSE 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.

16.4.2.3 How to Use the Java EE Component Client Application Deployed to WebLogic Server

In this case, the web service runs inside a Java Platform, Enterprise Edition (Java EE) Version 5 component deployed to WebLogic Server, such as an EJB, servlet, or another web service. This type of client application, therefore, runs inside a WebLogic Server container.

To use the generated client proxy classes in a Java EE component:

  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 Application Navigator.

  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.

16.4.3 How to View the WSDL Used to Create the Web Service Client

You can view the WSDL that was used to generate the web service client under the following circumstances:

  • 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 Section 16.4.1, "How to Create 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 Section 16.4.5, "How to Regenerate Web Service Client and Proxy Classes".
  • If the local version is not available, the remote WSDL is displayed.

To view the client WSDL:

  1. Right-click on the web service client within the Application Navigator.

  2. Select Go To WSDL from the pop-up menu.

    The WSDL is displayed.

16.4.4 How to Update the Web Service WSDL 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

16.4.4.1 How to Use 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.

16.4.4.2 How to Use 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: Using 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: Updating 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 WebLogic Server environment. A deployment plan defines or overrides deployment property values that would normally be defined in an application's WebLogic Server deployment descriptors. To update the configuration for your application, you add or update variables in the deployment plan, defining both the location of the WebLogic Server 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 CreditRating Service 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>

16.4.5 How to Regenerate Web Service Client and Proxy Classes

There are times that you may need to regenerate the web service client and proxy classes.

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:

  1. In the Application Navigator, 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.

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 Application Navigator, 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.

16.4.6 How to Manage the Web Service Clients

JDeveloper provides the ability to both edit and delete web service clients.

To edit web service clients:

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

  1. Double-click on the client within the Application Navigator.

  2. Right-click on the client within the Application Navigator, and select Properties...

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

To delete web service clients:

  1. In the Application Navigator, expand the node that contain the web service client proxy files, package.proxy, and select the files.

  2. Choose File > Erase from Disk. You can ignore any usages JDeveloper finds.

  3. Expand the node that contains the web service proxy runtime files, package.proxy.runtime, and select the files.

  4. Choose File > Erase from Disk.

    The files are permanently erased.

16.4.7 How to Reference 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 @WebServiceRef Annotation" in GD.

16.5 Creating SOAP 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. For information about using top-down development—starting from the WSDL—see Section 16.6, "Creating SOAP Web Services from WSDL (Top Down)".

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

16.5.1 How to Create Java Web Services

You can create web services from:

  • Java classes

  • Remote interface of EJBs

  • ADF Business Components service session bean wrapped as an EJB

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 Section 16.2.2, "How to Set the Context Root for Web Services".

To create the web service:

  1. In the Application Navigator, select the project containing the Java class or EJB from which you want to create a web service.

  2. Choose File > New 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 to launch the Create Java Web Service wizard.

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

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.

16.5.2 How to Use JSR-181 Annotations

JSR-181 specifies web services meta data, which allows you to use annotations to 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 end-points.

You can add JSR-181 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.

Note:

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

To add annotations:

  1. Open the Java class open in the source editor.

  2. On correct line, type @ and pause for a couple of seconds.

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

For more information, see the following references:

16.5.3 How to Create PL/SQL Web Services

The Create PL/SQL Web Service wizard makes it easy to generate a web service from a PL/SQL package or a Java stored procedure that uses object types. A Java stored procedure is defined by a SQL specification that invokes it, and the PL/SQL Web Service wizard treats these in the same way as packages.

Note:

You can only create JAX-RPC PL/SQL Web Services. For more information, see Section 16.2.6, "How to Choose Your Deployment Platform".

PL/SQL web services can be deployed to Oracle WebLogic Server. The Create PL/SQL Web Service wizard uses the functionality of Oracle JPublisher to wrap the PL/SQL in Java so that the service can be published. For more information see Section 28.3.1, "How to Use JPublisher".

You can either:

  • Create the web service starting from a project in the Application Navigator. In this case, you select the database connection and the PL/SQL package to generate the web service from.

  • Create the web service from the PL/SQL package under the database connection node in the Database Navigator or the Resource Palette. In this case, you have to select the project into which the generated files for the web service are deployed.

It should be noted that:

  • If you edit a PL/SQL web service, make sure that the database connection still exists otherwise you will see an error message. If you have deleted the database connection, create a new one with the same name as the original connection.

  • There are some cases where a web service cannot be created. For more information on the limitations, see Section 16.2.5, "How to Work with PL/SQL Web Services and Types".

  • Deploying PL/SQL web services is similar to deploying other J2EE Web Applications. For more information, see Section 16.12, "Deploying Web Services".

To create the PL/SQL web service from a project:

  1. In the Application Navigator, select the project.

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

  3. In the Categories list, expand Business Tier and select Web Services. In the Items list, double-click PL/SQL Web Service to launch the Create PL/SQL Web Service wizard.

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

To create the web service from a PL/SQL package:

  1. In the Database Navigator or the Resource Palette, expand the database connection node, the schema node, the Packages node, then the node of the package.

  2. Right-click the PL/SQL package body, and choose Publish as Web Service to launch the Create PL/SQL Service wizard.

16.5.4 How to Create 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 Section 16.12, "Deploying Web Services".

It should be noted that:

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

  • If you edit a 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.

  • In some cases, you may not be able to generate a TopLink web service provider. For more information on the limitations, see Section 16.2.5, "How to Work with PL/SQL Web Services and Types".

To create the TopLink web service provider from a project:

  1. In the Application Navigator, select the project.

  2. Choose File > New 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.

16.5.5 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 Service Atomic Transactions" in Oracle Fusion Middleware Programming Advanced Features of 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 Service Atomic Transactions" in Oracle Fusion Middleware Programming Advanced Features of 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 @TransacationAttribute annotation.

Table 16-3 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


To enable web service atomic transactions in the Java class:

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

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

    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])
    

To enable web service atomic transactions in the Property Inspector:

  1. With the web service class open in the source editor, choose View Property Inspector to open the Property Inspector.

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

  2. With the cursor in the public class, @WebService, or two-way method line of the class, navigate to the Web Services Extensions node in the Property Inspector.

  3. Select Add Transactional.

    The Property Inspector is refreshed to display options to set the flow type and version. For more information about the configuration options, see Table 16-3.

  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.

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 16-3.

16.5.6 How to Regenerate 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 Application Navigator, 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.

16.5.7 How to Use Handlers

JDeveloper allows you to specify the handler classes to deal with the web service message. The handlers can use initialized parameters, SOAP roles or SOAP headers.

To define handlers:

  1. Create a web service. For more information, see Section 16.5.1, "How to Create Java Web Services".

    or

    Open the web service editor. For more information, see Section 16.10, "Editing and Deleting 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.

16.5.8 How to Expose Superclass Methods for JAX-RPC

Note:

For JAX-WS web services, superclass methods are always exposed.

To expose superclass methods for JAX-RPC, consider the following two examples:

package mypackage;
public class Shape {
    public void area() {
    }
}

and

package mypackage;
public class Circle extends Shape {
    public Circle() {
    }
    public void callParentMethod() {
        super.area();
    }
}

In class Circle, which extends Shape, there is a public method callParentMethod() which is responsible for calling the parent class method area. To call the superclass method area(), create a J2EE Java web service on the Circle class using the public method callParentMethod().

16.5.9 How to Handle Overloaded Methods

If the Java class on which you base a web service has overloaded methods, JDeveloper handles them automatically. However if you create a J2EE 1.4 web service, and then change the class on which it is based so that an existing method becomes an overloaded method you have to take action to update the mapping file.

The procedure to handle overloaded methods depends on the type of web service that you are developing, JAX-WS or JAX-RPC.

Handling Overloaded Methods for JAX-WS Web Services

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 Getting Started With JAX-WS Web Services for Oracle WebLogic Server.

Handling Overloaded Methods for JAX-RPC Web Services

For JAX-RPC web services, there are two ways that you can handle overloaded methods:

  • Manually modify the mapping file

  • Delete the mapping file and recreate the web service

To manually modify the mapping file

After you create the web service based on the Java class, add the overloaded method to the class.

To delete the mapping file and recreate the web service

  1. In the Application Navigator, expand Web Content and WEB-INF.

  2. Right-click <web_service>-java-wsdl-mapping.xml and choose Delete.

  3. Open the web service editor. For more information, see Section 16.10, "Editing and Deleting Web Services".

  4. Click OK to close it and regenerate the service.

16.5.10 How to Set Mappings between Java Methods and WSDL Operations Using the JAX-RPC Mapping File Editor

JAX-RPC maps Java types to WSDL definitions. However when the types you want to support are not covered by the JSR-109 specification, or when you want to use different mappings to provide the functionality your web service requires, you can use the JAX-RPC Mapping File Editor to amend an existing mapping file, or to create your own.

The JAX-RPC Mapping File Editor is a specialized schema-driven editor which helps you to create a JSR-109 compliant mapping file for a J2EE 1.4 web service. The mapping file standardizes the Java- WSDL mappings, and in general you have to provide a full mapping only when the default mapping rules in JSR-109 are not satisfied.

These features are available while you are using the JAX-RPC Mapping File Editor:

  • While you are typing, you can invoke Code Insight by pausing after typing the < (open bracket), or by pressing Ctrl+Space (if you are using the default key mapping). Code Insight opens a list with valid elements based on the schema.

  • You can choose View > Component Palette to open the Palette and select one of the available pages from the dropdown list.

  • A mapping file's elements are displayed hierarchically in the Structure window, which also displays any XML syntax errors found as you type and edit. You can double-click on an element or error to edit it in the JAX-RPC Mapping File Editor.

  • You can right-click on an XML element in the editor and choose Locate in Structure to expand the Structure window to both show the element and select it. While you are editing, you can right-click in the open file and choose Auto Indent XML to properly indent the elements.

  • In an open JAX-RPC Mapping File Editor window, or in the Structure window with the web service selected in the Application Navigator, right-click a mapping file and choose Validate WSDL. The Validate WSDL command will validate the XML against the registered schemas.

16.6 Creating SOAP 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 use the Find Web Service Wizard to locate a web service in a UDDI registry connection in the Resource Palette.

To create a SOAP web service from WSDL (top down):

  1. In the Application Navigator, select the project in which you want to create the web service.

  2. Choose File > New 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 SOAP web service is created and the Java implementation class is opened automatically in the editor

16.7 Creating RESTful Web Services

Representational State Transfer (REST) describes any simple interface that transmits data over a standardized interface (such as HTTP) without an additional messaging layer, such as SOAP. REST provides a set of design rules for creating stateless services that are viewed as resources, or sources of specific information, and can be identified by their unique URIs. A client accesses the resource using the URI, a standardized fixed set of methods, and a representation of the resource is returned. The client is said to transfer state with each new resource representation.

When using the HTTP protocol to access RESTful resources, the resource identifier is the URL of the resource and the standard operation to be performed on that resource is one of the HTTP methods: GET, PUT, DELETE, POST, or HEAD.

The following sections describe how to create RESTful web service and clients:

16.7.1 How to Add the Jersey JAX-RS Reference Implementation to Your Project

Before you can create RESTful web services in JDeveloper, you need to download and add to your project the Jersey JAX-RS Reference Implementation (RI). The Jersey JAX-RS RI is available at https://jersey.dev.java.net. Click Download for more information about the Jersey RI and to download the ZIP file that contains the relevant library JAR files. Once downloaded, you need to add the Jersey RI to your project.

Note:

The Jersey RI 1.1.5.1 (jersey-archive-1.1.5.1) version or above is compatible with this release of JDeveloper.

To add the Jersey JAX-RS RI to your project:

  1. With the project selected in the Application Navigator, open the Project Properties dialog.

    To display the dialog, double-click the Project folder or select Edit > Properties.

  2. Select the Libraries and Classpath node.

  3. On the Libraries and Classpath page, click Add Library.

  4. In the Add Library dialog, click New.

  5. In the Create Library dialog, enter a name for the new library (for example, JAX-RS) and select its location.

  6. Enable Deployed by Default.

    Note:

    If you do not select this check box, you will experience errors during deployment of your RESTful web services and clients.
  7. Select Class Path and click Add Entry.

  8. In the Select Path Entry dialog, navigate to the lib directory of the Jersey archive. For example, c:\mylibraries\jersey-archive-1.1.5.1\lib.

  9. Select all of the JAR files in the lib directory and click Select.

    Note:

    If you are developing RESTful web services only (that is, you are not developing RESTful clients), you do not have to include the jersey-client-1.1.5.1.jar. Similarly, if you are developing RESTful web service clients only, you do not have to include the jersey-server-1.1.5.1.jar.
  10. If you downloaded the source files, you can set the Source Path to point to the source files (similar to the way that you defined the Class Path in the previous steps).

  11. In the Create Library dialog, click OK.

  12. In the Add Library dialog, click OK.

  13. On the Libraries and Classpath page, if finished click OK.

Once you have added the Jersey JAX-RS RI to your project, you can then create JAX-RS web services and clients.

16.7.2 How to Create JAX-RS Web Services and Clients

After you have added the Jersey JAX-RS RI to your project, you can start creating JAX-RS web services and clients using JDeveloper. All of the standard Java source editor features will work with the JAX-RS calls, such as code insight, import assistance, and so on.

For more information about JAX-RS and samples, you might find it helpful to review the Jersey RI documentation at: http://wikis.sun.com/display/Jersey/Main.

Once you create your RESTful web services, you can test them using the HTTP Analyzer. For more information, see Section 16.13.4, "How to Examine Web Services using the HTTP Analyzer".

Note:

If you experience errors during the deployment of your RESTful web services and clients, ensure that you have selected the Deployed by Default check box when adding the Jersey JAX-RS RI to your project.

A Simple Hello World Example

Example 16-1 provides a very simple example of a RESTful web services:

Example 16-1 RESTful web services

package samples.helloworld;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;

// Specifies the path to the RESTful service
@Path("/helloworld")
public class helloWorld {
 
   // Specifies that the method processes HTTP GET requests 
   @GET
   @Path("sayHello")
   @Produces("text/plain")
   public String sayHello() {
      return "Hello World!";
   }
}

Example 16-2 provides a simple RESTful client that calls the RESTful web service defined previously. This sample uses classes that are provided by the Jersey JAX-RS RI specifically; they are not part of the JAX-RS standard.

Example 16-2 RESTful client

package samples.helloworld.client;

import com.sun.jersey.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-Project1-context-root/
            jersey/helloWorld");
      String response = resource.get(String.class);
   }
}

About the web.xml File

JDeveloper does not automatically add the servlet class to the web.xml file. Instead, you are prompted to confirm whether you want to add it when you call a JAX-RS method from your code. For example, see Figure 16-1.

Figure 16-1 Prompt to confirm update

Prompt to confirm update.

Note:

Why is the web.xml file not updated automatically? In the future, when you deploy to a Java EE 6.0 container, an update to the web.xml will not be required. Therefore, this is set up as an optional activity.

To update the web.xml:

To update the web.xml, select Configure web.xml for Jersey JAX-RS web services as follows:

<?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">
   <servlet>
      <servlet-name>jersey</servlet-name>
      <servlet-class>
          com.sun.jersey.spi.container.servlet.ServletContainer
      </servlet-class>
      <load-on-startup>1</load-on-startup>
   </servlet>
   <servlet-mapping>
      <servlet-name>jersey</servlet-name>
      <url-pattern>/jersey/*</url-pattern>
   </servlet-mapping>
</web-app> 

16.8 Managing WSDLs

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

16.8.1 How to Create WSDL Documents

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

To create a WSDL:

  1. In the Application Navigator, select the project containing the Java class or EJB from which you want to create a web service.

  2. Choose File > New 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.

16.8.2 How to Add 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")

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.

To add a WSDL to a web service project:

In the Application Navigator, 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.

16.8.3 How to Display 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.

To display the WSDL to a web service project:

In the Application Navigator, 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.

16.8.4 How to Save 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.

16.9 Using Policies with Web Services

This section describes how to use policies with web services created in JDeveloper. You can use the following types of policies:

  • Oracle Web Service Manager (Oracle WSM) policies—Attach security policies only to JAX-WS web services.

  • Oracle WebLogic web service policies—Attach to JAX-WS or JAX-RPC web services.

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 Oracle WSM policies and later decide that you want to use Oracle WebLogic web service policies, you must delete the Oracle WSM 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 Security Policies to Use" in the Oracle Application Server Web Services Security Guide.

  2. Attach the policies to a class or service. For more information, see Section 16.9.3, "How to Attach Policies to 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 "Configuring Policies" in the Oracle Application Server Web Services Security Guide.

  4. Test the web service to ensure that the policies work as expected. For more information, see Section 16.11.1, "How to Test Web Services in a Browser".

16.9.1 What You May Need to Know About Oracle WSM Policies

Oracle WSM policies can be attached to JAX-WS web services at the port-level. JDeveloper currently supports Oracle WSM security policies only.

JDeveloper is preconfigured to use the policy store set at the default location in the WS Policy page of the Preferences dialog at:

  • Tools menu > Preferences > WS Policy Store

    or

  • Application menu > Application Properties > WS Policy Store

You can specify another policy store location to use your organization's custom Oracle WSM policies. For more information Section 16.9.8, "How to Use a Different Oracle WSM Policy Store".

For more information about Oracle WSM policies, see the Oracle Application Server Web Services Security Guide.

Policy Annotations

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 @SecurityPolicies 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, click Ctrl+Alt+Enter to invoke the Code Assist feature.

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

Oracle WebLogic web service policies can be attached to JAX-WS and JAX-RPC 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, i.e., to be applied on the inbound (request) message or outbound (response) message, or both.

You can configure JDeveloper to use your organization's custom Oracle WebLogic web service policies. For more information, see Section 16.9.7, "How to Use Custom Web Service Policies".

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

Policy Annotations

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 @Policies 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, click Ctrl+Alt+Enter to invoke the Code Assist feature.

16.9.3 How to Attach Policies to Web Services

JDeveloper allows you to attach Oracle Web Service Manager (Oracle WSM) 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 "Configuring Policies" in the Oracle Application Server Web Services Security Guide.

You can attach policies to web services by:

  • Selecting 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.

  • Adding policy annotations directly in the Java class; the Code Insight feature can help you. For more information, see Section 16.2.7, "How to Work with Web Services Code Insight".

  • Using the Property Inspector.

To attach policies in the web service wizard or editor:

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 Oracle WSM 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.

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, @Policies. 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 using policy annotations, see "Updating the JWS File with @Policy and @Policies Annotations" and "SecurityPolicy and SecurityPolicies Annotations" in Oracle Fusion Middleware Securing WebLogic Web Services for Oracle WebLogic Server.

To attach policies in the Property Inspector:

  1. With the web service class open in the source editor, choose View > Property Inspector to open the Property Inspector.

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

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

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

    The Property Inspector is refreshed to display options to select single or multiple policies for the policy type selected (Oracle WSM or WLS).

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

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

    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.

16.9.4 How to Attach Oracle WSM Policies to Web Service Clients

JDeveloper allows you to attach Oracle Web Service Manager (Oracle WSM) to web service clients.

After you attach an Oracle WSM policy to a web service client, you need to configure the policies. For more information, see "Configuring Policies" in the Oracle Application Server Web Services Security Guide.

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 Oracle WSM policies to web service clients by:

  • Selecting the Oracle WSM policies to attach in the Create Web Service Client and Proxy wizard when creating a new web service client or in the Web Service Client and Proxy editor when updating a web service client that already exists. In the Create Web Service Client and Proxy wizard or editor, navigate to the Policy page.

  • When attaching Oracle WSM 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.

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

  • Manually using weblogic.wsee.jws.jaxws.owsm.SecurityPolicyFeature class to attach a single policy or weblogic.wsee.jws.jaxws.owsm.SecurityPoliciesFeature to attach multiple policies.

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

16.9.5 How to Invoke 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 configure credentials for a web service client that invokes a web service 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.

16.9.6 How to Edit and Remove Policies from Web Services

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

  • Web service editor

  • Source editor

  • Property Inspector

To change or remove policies using the web service editor:

  1. Right-click the web service in the Application Navigator, 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 Oracle WSM 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.

To change or remove policies using annotations in the Java class:

To change or remove policies using the Property Inspector:

  1. With the JAX-WS web service class open in the source editor, choose View > Property Inspector to open the Property Inspector.

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

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

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

    • To change a single policy, delete the name from the 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.

16.9.7 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 Oracle Web Service Manager (Oracle WSM) policies or Oracle WebLogic web service policies, as described in the following sections:

16.9.7.1 Using Custom Oracle WSM Policies

To use custom Oracle Web Service Manager (Oracle WSM) policies, perform one of the following steps:

  • Add a custom policy in the default policy store location at:

    JDEV_USER_HOME\system11.1.1.2.x.x.x\DefaultDomain\oracle\store\gmds. If not set,

    JDEV_USER_HOME defaults to C:\Documents and Settings\user-dir\Application Data\JDeveloper.

    Within this directory, policies must be included using one of the following directory structures:

    • Predefined Oracle WSM policies: owsm/policies/oracle/policy_file

    • Custom user policies: owsm/policies/policy_file

    Note:

    When exporting policy files from the Oracle WSM 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 use 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 Oracle WSM repository, see "Understanding the Different Mechanisms for Importing and Exporting Policies" in the Oracle Application Server Web Services Security Guide.
  • Specify a different policy store. Fro more information, see Section 16.9.7.2, "Using Custom Oracle WebLogic Web Service Policies".

    If you elect to use a policy store on a remote application server, you can import custom Oracle WSM policies to the MDS repository on the remote application server using Fusion Middleware Control or WLST.

    For more information about importing policies to the Oracle WSM MDS on the remote application server, see "Understanding the Different Mechanisms for Importing and Exporting Policies" in the Oracle Application Server Web Services Security Guide.

For more information about creating custom policies, see "Creating Custom Assertions" in Extensibility Guide for Oracle Web Services Manager.

16.9.7.2 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.

For more information about creating custom policies, see "Creating Custom Assertions" in Extensibility Guide for Oracle Web Services Manager.

16.9.8 How to Use a Different Oracle WSM Policy Store

The Oracle Web Service Manager (Oracle WSM) policy store is installed as part of JDeveloper. You can use 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 specify a different policy store location:

  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 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 Oracle WSM Policy Manager. To verify that the Oracle WSM 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 Oracle WSM Policy Manager is operational, then a list of the predefined policies is displayed with descriptions. For more information about troubleshooting the Oracle WSM Policy Manager, see "Diagnosing Problems" in the Oracle Application Server Web Services Security Guide.

16.10 Editing and Deleting Web Services

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

To edit a web service:

  1. In the Application Navigator, right-click the web service container and choose 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 Section 16.12, "Deploying Web Services".

When you edit a 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.

When you edit a PL/SQL web service, ensure that the database connection is present; otherwise, you will receive an error message. If you have deleted the database connection, create a new one with the same name as the original one.

To delete a web service:

  • In the Application Navigator, right-click the web service container and choose Delete Web Service. The Delete Web Service dialog listing the files that will be deleted is displayed. Click OK.

    The files are deleted and any references to the service web.xml are removed.

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.

16.11 Testing and Debugging Web Services

Developer provides a number of ways that you can test web services. You can use the debugger, which enables you to debug web services that you create locally, on the Integrated WebLogic Server, and remotely, on Oracle WebLogic Server. You can also run a web service deployed to Integrated WebLogic Server in a browser to check that it returns what you expect.

In addition to the topics described in this section, you can use HTTP Analyzer to examine the content of web services over HTTP, similar to examining other packet information. For more information, see Section 16.13.4, "How to Examine Web Services using the HTTP Analyzer".

The following sections describe how to test and debug web services:

16.11.1 How to Test Web Services in a Browser

Once you have created and deployed a web service, you can check that it returns what you expect by running it in the browser.

The process that you use to test web services depends on whether you are testing WebLogic web services or Oracle Infrastructure web services, such as ADF business components.

  • Testing WebLogic Java EE web services in a browser

  • Testing Oracle Infrastructure web services in a browser

To test WebLogic Java EE web services in a browser:

  1. Open the following URL in a browser: http://IP_address:port/wls_utc

  2. Enter the URL of the WSDL and click Test.

    For example: http://IP_address:port/Project1-context-root/MyWebService1?WSDL

    The browser shows a simple page which lists the operations available on the service.

  3. Enter values for each of the parameters and click the operation-name button to review the request details.

Testing Oracle Infrastructure Web Services in a Browser

For Oracle Infrastructure web services, such as ADF business components, you can test web services in a browser deployed to:

  • Integrated WebLogic Server

  • Oracle WebLogic Server

To test a service deployed to Integrated WebLogic Server:

  1. When you deploy the Oracle Infrastructure web service to Integrated WebLogic Server, examine the contents of the log window. Find the line containing the following:

    Use the following context root(s) to test your web application(s): http://IP_address:port/Project1-context-root/MyWebService1

  2. Copy the URL and paste it into browser. The browser shows a simple page which lists the operations available on the service.

  3. Enter a parameter, and click Enter. The result from the web service is displayed.

To test a service deployed to Oracle WebLogic Server:

  1. When you deploy the Oracle Infrastructure web service to Oracle WebLogic Server, examine the contents of the log window. Find the line that says:

    The application can be accessed at location: http://IP_address:port/Project1-context-root

    This URL only shows the context root for the web service.

  2. Copy the URL and paste it into browser, and add the name of the web service to the end to give the full location of the service:

    http://IP_address:port/Project1-context-root/MyWebService1

    The browser shows a simple page which lists the operations available on the service.

  3. Enter a parameter, and click Enter. The SOAP message containing the parameter you entered to the web service is displayed.

  4. Click Invoke. The result from the web service is displayed.

16.11.2 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.

Although you can debug a PL/SQL web service, what you are debugging is the Java class generated by JDeveloper to wrap the PL/SQL for deployment as a web service. Therefore, the correct way to ensure that a PL/SQL web service runs as expected is to debug the PL/SQL before you create a web service from it. For more information, see Section 29.3, "Debugging PL/SQL Programs and Java Stored Procedures".

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 Section 16.13.4, "How to Examine Web Services using the HTTP Analyzer".

JDeveloper lets you debug a web service that is running in the Integrated WebLogic Server, locally or a web service that is deployed remotely.

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. There are two ways to do this:

  • By putting breakpoints in the web service class, then running a proxy client against it. This allows you to debug the service class itself.

  • By putting 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. Choose Tools > Preferences, and select Web Browser and Proxy.

  2. Deselect Use Http Proxy Server.

  3. Run the web service in debug mode. In the navigator, right-click the web service container, and choose Debug.

    The Integrated WebLogic Server is started in debug mode, and the web service is deployed to it. The results are displayed in the log window.

  4. Create a web service client, as described in "Creating Web Service Clients".

    A proxy container is generated and displayed in the navigator, with a Java class called web_serviceSoapHttpPortClient.java displayed in the source editor.

  5. In the source editor, navigator to // Add your own code here, and enter some code.

  6. 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 Chapter 19, "Running and Debugging Java Programs".

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, 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 Section 16.12, "Deploying Web Services".

  3. Create a client to the web service.

  4. In the source editor, navigate to // Add your own code here, 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 Chapter 19, "Running and Debugging Java Programs".

16.12 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:

In addition, you can define a different WebLogic Server domain to be the Integrated WebLogic Server on which to run web services. For more information, see Section 9.2, "Running Java EE Applications in the Integrated Application Server".

16.12.1 How to Deploy Web Services to Integrated WebLogic Server

You can deploy web service generated in JDeveloper to Integrated WebLogic Server.

To deploy a web service to Integrated WebLogic Server:

  1. In the Application navigator, right-click the project containing the web service, and choose Deploy > Web Services.

    The first time you start Integrated WebLogic Server by running or debugging an application or web service, a dialog is displayed where you enter a password for the administrator ID on the default domain. When you click OK, the default domain is created. You only need to do this once.

  2. In the Deploy Web Services dialog, on the Deployment Action page, select Deploy to Application Server and click Next.

  3. On the Select Server page, select IntegratedWebLogicServer and click Next to view the Summary page or Finish to deploy the web services.

16.12.2 How to Deploy Web Services to Oracle WebLogic Server

You can deploy a web service generated in JDeveloper to Oracle WebLogic Server.

When you used one of the Create Web Services wizards to generate the files for your Java EE web service, the wizard automatically created all the files that you need, including a deployment profile named WebServices.deploy. The WebServices.deploy file is created at project level. The deployment profile contains a WAR file and an EAR file.

Note:

If you are deploying a PL/SQL web service, you must create an EAR, which is a deployment profile at application level, and deploy the EAR file. The database connection information is contained in the EAR, although password indirection is used so you also have to set a JDBC data source on Oracle WebLogic Server.

To deploy a web service:

  • In the navigator, 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.

To deploy a PL/SQL web service:

  1. Create an application-level EAR deployment profile and add the web service to it.

  2. Deploy the EAR to the application server connection to Oracle WebLogic Server.

  3. Set the database connection details on Oracle WebLogic Server by following the information about deploying EARs to Oracle WebLogic Server.

For more information, see Section 9.4.1, "Deploying to a Java JAR".

To examine the contents of a web services deployment profile:

  1. To examine the contents of a web services deployment profile:

  2. Choose the File Groups > WEB-INF/classes > Filters node to display a listing of the .java and .wsdl files for the web service.

16.12.3 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 Resource Palette.

To undeploy a web service:

  1. In the Application Server Navigator, select the application server connection you have been using and expand Web Services.

  2. Right-click application-name_project-name_ws and choose Undeploy.

16.13 Monitoring and Analyzing Web Services

You can analyze web services in a number of ways, for example to check whether they conform to WS-I Basic Profile 1.1, or to investigate the contents of SOAP packets.

The Web Services-Interoperability Organization (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.

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 have downloaded a WS-I compliant analyzer.

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 Application Navigator, or it can be a web service that you have located using a UDDI registry that is listed in the Resource Palette. 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 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. In JDeveloper choose Tools > Preferences and select WS-I Testing Tools.

  3. 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.

The following sections describe how to monitor and analyze web services:

16.13.1 How to Analyze Web Services in the Navigator

You can produce a report of a web service that is listed in the Application Navigator, or that you have located using a UDDI registry and that is listed in the Resource Palette 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 navigator, 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.

16.13.2 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.

    • Either to an external web service.

      or

    • For a web service that you have created and deployed to Oracle WebLogic Server, create a client stub or proxy.

      or

    • 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 container's context menu. In the navigator, select Generate Web Service Proxy from the web service container's 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 View > HTTP Analyzer, and in the monitor click the Start button.

    Start button icon
  3. Run the client. Either:

    • Select Run from the context menu of the client in the source editor.

      or

    • 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 the Stop button.

    Stop button icon
  5. Click the WS-I Analyzer button 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.

    Analyzer button icon

16.13.2.1 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 Section 16.13.3, "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.

16.13.3 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.

16.13.3.1 Changing the Endpoint Address

When the web service is run in the Integrated Server (by choosing Run from the web service's 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 using one of the following methods:

    • Double-click the web service container in the navigator, go to the Endpoint page of the Edit Web Service dialog, and edit the Web Service Endpoint.

    • Select the web service container in the navigator, and double-click the WSDL document in the Structure window. Navigate to the soap:address subelement, and edit the endpoint.

  2. Change the web service endpoint to one of the following:

    • IP_address:integrated_port_no (the default integrated port number is 8988)

    • hostname (lower-case)

  3. For JAX-RPC web services, open the EmbeddedStub.java file by double-clicking on it and navigate to the _endPoint variable. After ensuring the web service endpoint is the same as the _endPoint variable in the proxy you can create and analyze the web service logs. For more information, see Section 16.13.2, "How to Create and Analyze Web Service Logs".

16.13.3.2 Changing the Endpoint Address Without Modifying the WSDL (JAX-WS Only)

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);
   }
}

16.13.4 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 web service. More information, see Section 8.3, "Monitoring HTTP Using the HTTP Analyzer". It allows 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.

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 amend the proxy settings. For more information, see Section 16.2.1, "How to Use Proxy Settings and JDeveloper".

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 Section 16.12, "Deploying Web Services".

  3. Start the HTTP Analyzer by selecting View > HTTP Analyzer. It opens in its own window in JDeveloper.

  4. Run the HTTP Analyzer by clicking Start HTTP Analyzer. Start icon

  5. Run the client proxy to the web service. The request/response packet pairs are listed in the Http Analyzer.

  6. To examine the content of a request/response pair highlight it in the History tab and then click the Data tab.

  7. You can quickly move from one pair to the previous or the next by clicking the up Next message and Previous message buttons.

    Next button
    Previous button