Skip Headers
Oracle® Application Server Web Services Developer's Guide
10g Release 3 (10.1.3)
B14434-01
  Go To Documentation Library
Home		 Go To Product List
Solution Area		 Go To Table Of Contents
Contents		 Go To Index
Index
Previous
Previous		 Next
Next		  

10 Assembling Web Services with Annotations

This chapter describes how to use annotations to quickly develop Web services from Java classes. You can use the annotations feature only when you are performing bottom up development of a Web service from Java classes.

The standard Java mechanisms for the design, development, and deployment of Web services require you to leverage a substantial amount of information. For example, to deploy a service based on a Java class you must provide the class itself, an associated service endpoint interface, and potentially, additional metadata files. For more information on generating a Web service with Java classes, see Chapter 6, "Assembling a Web Service with Java Classes".

Oracle Application Server Web Services provides support for J2SE 5.0 JDK Web Services Annotations. J2SE 5.0 Web Services annotations is part of an ongoing standard and is supported by other platforms. The following lists describe the advantages and disadvantages of using the J2SE 5.0 Web Services annotations.

J2SE 5.0 Web Services Annotations Advantages

J2SE 5.0 Web Services Annotations Disadvantages

Developing Web Services with J2SE 5.0 Annotations

OracleAS Web Services provides support for J2SE 5.0 Web Service annotations (also known as the Web Services Metadata for the Java Platform (JSR-181) specification). The specification defines an annotated Java syntax for programming Web services. The specification is available from the following Web site.

http://www.jcp.org/en/jsr/detail?id=181

Using the annotated Java syntax requires the J2SE 5.0 JDK. The J2SE 5.0 JDK also provides documentation on the language-level support for annotations, such as how to define them, their syntax, and how to create new annotations. The J2SE 5.0 JDK is available from the following Web site.

http://java.sun.com/j2se/1.5.0/download.jsp

Java Metadata Annotations is a feature in J2SE 5.0 JDK that enables you to add special tags to your Java classes. These tags are then compiled into the class byte code and made accessible to third party annotation processors. The Web Services Metadata for the Java Platform specification further extends this feature with metadata tags for Web services. OracleAS Web Services supports this specification and allows developers to customize the Web services generation process through the use of annotations.

Since metadata annotations are a J2SE 5.0 feature, you must have the JVM from the J2SE 5.0 JDK to use Web service annotations in OracleAS Web Services. The WebServicesAssembler tool can generate Web services from Java classes that have J2SE 5.0 annotations. When the tool is used in a J2SE 5.0 JDK JVM, the assemble and genWsdl commands will process annotations in a given Java class.

The EJB 3.0 specification has extended the Web Services Metadata for the Java Platform specification by adding metadata tags for EJBs. The specification supports the Web Services Metadata for the Java Platform tags, allowing EJBs to be exposed as Web services. EJB 3.0 annotations are processed when an EAR file containing EJBs is deployed to a running Oracle Application Server. Any interfaces with J2SE 5.0 annotations that are implemented by session beans will be processed. Note that you cannot use the WebServicesAssembler tool to process EJB 3.0 annotations.

How to Use J2SE 5.0 Annotations to Assemble a Web Service from Java Classes

To assemble a Web service from a Java class with J2SE 5.0 annotations, follow these steps.

  1. Add Web service metadata annotations to the implementation class.

    Example 10-1 illustrates a sample annotated Java file.

    1. At a minimum, the @WebService metadata tag must be present in the class.

    2. Add the endpointInterface property to the @WebService metadata tag in the implementation class if you want to reference a service endpoint interface. Note that if the service endpoint interface also has an @WebService tag, the annotations will be processed at that starting point instead.

    3. Add the @WebMethod annotation to each method you want to expose in the Web service. Note that if your annotations are in the service endpoint interface, then all of the methods will be exposed, regardless of whether they have the @WebMethod annotation.

  2. Compile the annotated classes.

    The classes must be compiled with a JDK 5.0-compliant compiler.

  3. Generate the Web service artifacts (such as the WSDL, the deployment descriptors, and so on) by using the WebServicesAssembler assemble command

    1. You must specify the implementation class as the value of the assemble command's className argument. This is true even if all of your annotations are in the service endpoint interface. The implementation class must have an @WebService annotation.

    2. If you only want to generate a WSDL from an annotated Java class, use the genWsdl command and supply the implementation class as the value of the className argument.

How to Use J2SE 5.0 Annotations to Assemble a Web Service from a Version 3.0 EJB

Web services can be assembled from EJB 3.0-compliant beans at deployment time. To generate a Web service endpoint from an EJB 3.0 bean, follow these steps.

  1. Add an @Stateless metadata tag to the bean.

    Only stateless EJB session beans are supported.

    The name property of the @Stateless annotation provides the name of the Web service endpoint. If this property is not specified, then the default endpoint name will be the unqualified class name of the EJB bean class.

  2. Add the @WebService tag to the interface that the bean implements.

    1. Enter the tag in the interface. Do not enter it in the actual bean class.

    2. At a minimum, the interface must contain the @WebService tag.

    3. Add the @WebMethod annotation to each method you want to expose in the Web service.

    4. The interface must be implemented by the EJB bean class.

  3. (Optional) Add the @Deployment tag to the interface with values for the uriPath and portName attributes.

    By default, the port name and default URI for an EJB 3.0 bean is the EJB name. This name is found in the @Stateless annotation of the bean. If the name of the bean is not specified in the @Stateless annotation, the short class name of the bean will be used instead. You can override this by providing values for the uriPath and portName attributes of the @Deployment tag.

  4. Compile the EJB classes and package them into an EAR file. Deploy the EAR file to a running instance of OC4J.

Supported J2SE 5.0 Annotation Tags

OracleAS Web Services provides support for the entire set of annotation tags described in the Web Services Metadata for the Java Platform specification. The tags appear in the following list.

  • javax.jws.WebMethod

  • javax.jws.Oneway

  • javax.jws.WebParam

  • javax.jws.WebResult

  • javax.jws.HandlerChain

  • javax.jws.soap.SOAPBinding

  • javax.jws.soap.SOAPMessageHandlers

Oracle Additions to J2SE Annotations

This section describes the Oracle-proprietary annotations that can be read and processed by the Java Metadata Annotations feature in the J2SE 5.0 JDK.

Deployment Annotation

The @Deployment annotation can be used to supply the deployment attributes to an endpoint implementation or to a service endpoint interface. It is an optional annotation that has only optional properties.

The oracle.webservices.annotations.Deployment class defines the @Deployment annotation.

Table 10-1 describes the attributes supported by the @Deployment annotation. All the attributes of this tag are optional.

Table 10-1 Deployment Annotation Attributes

Attribute Description

contextPath

This value specifies the default context for the Web service. If you want to package multiple Web services in a WAR file and each endpoint class has an @Deployment annotation, then the value of the contextPath attribute must be the same for all of the services. This is because contextPath is global to a Web service deployment. If the Web services have differing contextPath values, then their behavior will be unpredictable. If only one contextPath property is set, then that will be the root context for all Web services in the same EAR or WAR file.

You can override the value of this attribute by providing a valid value for the <context-root> element in the oracle-webservices.xml deployment descriptor that is deployed with the EAR file. Setting <context-root> in the deployment descriptor overrides all contextPath properties in all Web services that have the Deployment annotation.

portName

This value specifies the portName element in the generated WSDL. Each Web service can have a different portName value.

You can override the value of the portName attribute by entering a value for the <port-component[name]> attribute in the oracle-webservices.xml deployment descriptor deployed with the EAR file.

restSupport

This Boolean value identifies whether the service is a REST Web service. If true, the port will supports REST-style GET and POST requests and responses. Default is false.

uriPath

This value is appended to the value of the contextPath attribute. Each Web service can have a different uriPath value.

You can override the value of this attribute by providing a URI in the <endpoint-address-uri> element for the corresponding <port-component[name]>. These elements must appear in the same service element in the oracle-webservices.xml deployment descriptor deployed with the EAR file.

Note: if there is a conflict in between the values of <url-pattern> in the web.xml deployment descriptor and the value of uriPath, then the value of <url-pattern> will take precedence.

The following example illustrates an interface that uses the @Deployment annotation. In this example, the Web service will be accessed by the URL http://$HOST:$PORT/ejb30/ejb30-simple after it is deployed.

...
@WebService(name="CustomSession",
            targetNamespace="http://ejb.oracle.com/targetNamespace",
            serviceName="CustomSessionBeanService")
@Deployment(contextPath="ejb30",
            uriPath="ejb30-simple",
            portName="Custom")
public interface CustomSessionIntf extends Remote{
...

Overriding Annotations

This section describes how you can override annotation values in a Java file by using deployment descriptors or WebServicesAssembler.

Overriding Annotation Values with WebServicesAssembler

Command line arguments passed to the WebServicesAssembler assemble and genWsdl commands will override any annotations in the Java class file that perform the same function. For example, if you pass the portName argument to the assemble or genWsdl command, then its value will override the value of the @Deployment.portName annotation.

Overriding Deployment Annotation Values with Deployment Descriptors

If you want to override any of the properties specified by the Oracle-proprietary @Deployment annotation, you can package a deployment descriptor that provides an override in the EAR file in META-INF/oracle-webservices.xml (or WEB-INF/oracle-webservices.xml for Web modules).

When you use an oracle-webservices.xml deployment descriptor to override @Deployment annotation properties, each <webservice-description> element in the descriptor must match a Web service being deployed based on the serviceName of the Web service. The serviceName is specified by @WebService.serviceName annotation.

Note that if you are assembling multiple Web services that use the @Deployment annotation and you specify a deployment descriptor that overrides the properties for only one of the services, then the other services will not be affected. In the deployment descriptor, you should specify only those properties you want to override.

For example, the values in the following XML fragment from an oracle-webservices.xml deployment descriptor override the @Deployment annotation properties. Since this fragment provides values for the <port-component name> attribute and the <endpoint-address-uri> element, the annotation's portName and uriPath attributes will be overridden. The <context-root> element was not specified in this example, so the annotation's contextPath property will not be overridden.

<webservice-description name="CustomSessionBeanService">
    <port-component name="CustomSession">
          <endpoint-address-uri>/custom-session</endpoint-address-uri>
    </port-component>
</webservice>

Of course, instead of annotating the class you could just provide an oracle-webservices.xml deployment descriptor to specify the deployment properties.

Sample Java File with J2SE 5.0 Annotations

To generate Web services from Java classes, you can enter J2SE 5.0 annotations in either of these files.

  • the endpoint class only

  • the endpoint class and the service endpoint interface

If you choose to enter the annotations in both the endpoint class and the service endpoint interface, then you need to enter only minimal annotations in the endpoint class.

Example 10-1 illustrates an example of an implementation class with Web service metadata annotations. Note how the @WebService, @WebMethod, and @WebParam annotations are used in the example.

  • The @WebService annotation specifies the serviceName and targetNamespace. These properties are used to populate the wsdl:service name and wsdl:targetNamespace elements in the generated WSDL file.

    Optionally, you can specify the endpointInterface property with the fully-qualified class name of an service endpoint interface. In this case, provide the following annotations.

    • Enter only the @WebService annotations in the endpoint class, and enter the correct value for endpointInterface. In the case where endpointInterface is used, all Web service-related annotations are ignored, except for the @WebService annotation on the endpoint class.

    • Enter the @WebMethod and @WebParam annotations in the service endpoint interface.

  • The @WebMethod annotations identify the methods that should be present in the Web service. These annotated methods will be assembled into wsdl:operation elements in the generated WSDL. If a value for the operationName property is specified in the @WebMethod annotation, then it will be used as the operation name for the wsdl:operation. If a value is not provided, then the name of the method is used by default.

  • The @WebParam annotations identify message parts or parameters to wsdl:operations. An optional Mode can be specified for each parameter. The INOUT or OUT modes can be specified only for parameters that implement the javax.xml.rpc.holders.Holder interface. By default, a parameter that implements the Holder interface becomes an INOUT parameter, unless Mode.OUT is explicitly specified by an annotation. All other parameters must be IN parameters.

Example 10-1 Sample Java File with J2SE 5.0 Web Service Metadata Annotations

package oracle.webservices.examples.annotations;

import java.rmi.RemoteException;
import javax.jws.*;
import javax.jws.WebParam.Mode;

@WebService (
    serviceName = "annotatedBank",
    targetNamespace = "http://service.annotatedBank"
)
public class BankServiceImpl {
    @WebMethod (operationName="create-account")
    public String createAccount( @WebParam(name="accountName") String acctName, 
                                 float initBalance ) 
        throws RemoteException, AccountException {
        return m_bank.addNewAccount(acctName,initBalance);
    }
    
    @WebMethod
    public void deposit( @WebParam(name="accountID", mode=Mode.IN) String acctID, 
                         float amount ) 
        throws RemoteException, AccountException {
        Account theAccount = m_bank.getAccount(acctID);
        if ( theAccount == null ) {
            throw new AccountException("No account found for " + acctID);
        }
        theAccount.deposit(amount);
    }
    //class truncated…
}

Limitations

See "Assembling Web Services with Annotations".

Additional Information

For more information on:

  Previous
Previous		 Next
Next
  Go To Documentation Library
Home		 Go To Product List
Solution Area		 Go To Table Of Contents
Contents		 Go To Index
Index