11 Assembling Web Services with Annotations

This chapter describes how to use annotations to quickly develop Web services from Java classes. The Web service can use either HTTP or JMS as the transport mechanism. You can use the annotations feature only when you are performing bottom up development of a Web service from Java classes.

This chapter contains the following sections:

• OracleAS Web Services and J2SE 5.0 Web Service Annotations

• Supported Annotations

OracleAS Web Services and J2SE 5.0 Web Service Annotations

The standard Java mechanisms for the design, development, and deployment of Web services require you to supply 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.

See Also:

Chapter 7, "Assembling a Web Service with Java Classes" for more information on generating a Web service with Java classes.

Oracle Application Server 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, available from the following Web site, defines an annotated Java syntax for programming Web services.

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

The following lists describe the advantages and disadvantages of using the J2SE 5.0 Web Services annotations.

J2SE 5.0 Web Services Annotations Advantages

• Based on a community standard.

• Supported by the J2SE 5.0 JDK. The metadata is stored directly in the class file, making them portable.

• Language-level IDE support. IDEs that support the J2SE 5.0 JDK will recognize J2SE 5.0 Web Service annotations and be able to provide things like auto-completion and syntax checking.

J2SE 5.0 Web Services Annotations Disadvantages

• Requires you to use the J2SE 5.0 JDK.

• See the limitations described in "Assembling Web Services with Annotations".

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 J2SE 5.0 JDK feature 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.

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 JDK annotations that are implemented by session beans will be processed. Note that you cannot use the WebServicesAssembler tool to process EJB 3.0 annotations.

Supported Annotations

The following sections describe the annotations that are supported by OracleAS Web Services.

• Supported J2SE 5.0 JDK Annotations

• Oracle Additions to J2SE 5.0 JDK Annotations

Supported J2SE 5.0 JDK Annotations

OracleAS Web Services enables you to use the entire set of annotations described in the Web Services Metadata for the Java Platform specification. Table 11-1 provides a brief description of these annotations. The Web Services Metadata for the Java Platform specification provides more information on these annotations.

Also included in Table 11-1 is a brief description of the @WebServiceRef annotation. The OracleAS Web Services enables you to use the @WebServiceRef annotation to reference a Web service endpoint from within a version 3.0 EJB, a servlet, or a Java class in an application client container. Support for the @WebServiceRef annotation also includes support for the injection of the service-ref target in the ejb-jar.xml deployment descriptor. For more information on this annotation, see the Java API for XML-based Web Services 2.0 (JSR-224) specification:

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

Table 11-1 J2SE 5.0 JDK Annotations Supported by OracleAS Web Services

J2SE 5.0 JDK Annotation	Description
javax.jws.HandlerChain	Associates the Web service with an externally defined handler chain.
javax.jws.Oneway	Indicates that the given Web method has only an input message, but no output.
javax.jws.WebMethod	Indicates that the method will be exposed as a Web service operation.
javax.jws.WebParam	Customizes the mapping of an individual parameter to a Web service message part and XML element.
javax.jws.WebResult	Customizes the mapping of the return value to a WSDL part and XML part.
javax.jws.WebService	Marks a Java class as implementing a Web service, or a Java interface as defining a Web Service Interface.
javax.jws.soap.SOAPBinding	Specifies the mapping of the Web service onto the SOAP message protocol.
javax.jws.soap.SOAPMessageHandlers	Specifies a list of SOAP protocol handlers that run before and after business methods on the Web service.
javax.xml.ws.WebServiceRef	Declares a reference to a Web service endpoint from within a version 3.0 EJB, a Java class, or a servlet in the application client container. The properties for the WebServiceRef annotation can play a role in how WebServicesAssembler generates the name of the JAX-RPC mapping file. See "How the WebServiceRef Annotation Determines the Mapping File Name" for more information.

Using WebServiceRef within OracleAS Web Services

The Java API for XML-based Web Services 2.0 (JSR-224) specification defines the @WebServiceRef annotation for referencing a Web service endpoint from within a version 3.0 EJB, a servlet, or a Java class in an application client container. Table 11-2 describes the properties that can be used with the @WebServiceRef annotation.

Table 11-2 WebServiceRef Annotation Properties

Property	Description
mappedName	A proprietary name for JNDI lookups.
name	The JNDI lookup name of the Web service. This value can be found in the java:comp/env namespace.
type	The resource type as a Java class object. By default, this value is javax.xml.rpc.Service.
value	The service type as a Java class object. By default, this is the class of the injection target.
wsdlLocation	The URL for the WSDL description of this Web service. If this annotation is present, it overrides the WSDL URL specified by the @WebService annotation of the referenced generated service interface.

The following sections provide more information about using the @WebServiceRef annotation in OracleAS Web Services.

• How the WebServiceRef Annotation Determines the Mapping File Name

• Specifying WSDLs with Multiple Ports in the WebServiceRef Annotation

• WebServiceRef Annotation Examples

How the WebServiceRef Annotation Determines the Mapping File Name

For each @WebServiceRef that occurs in a Java class or version 3.0 EJB, a JAX-RPC mapping file must be included in the deployed archive. WebServicesAssembler will generate the mapping file, but you must ensure that it appears in the appropriate location for your Web service. If the mapping file does not appear in these locations, then you must copy it manually.

• If the Web service is based on a version 3.0 EJB, then the generated JAX-RPC mapping file must appear directly under the META-INF directory.

• If the Web service is based on Java classes, then the generated JAX-RPC mapping file must appear directly under the WEB-INF directory.

The following steps describe how WebServicesAssembler determines the name of the mapping file. These steps are followed in order until a name can be successfully assigned. If the last step fails, then the process fails and a name is not assigned.

1. If the injection target class is a service endpoint interface (SEI) and the @WebService annotation and the serviceName property is specified, then the deployment system will try to load the mapping file with the following name:

   [@WebService.serviceName]Service-java-wsdl-mapping.xml

   In this example, [@WebService.serviceName] represents the value of the serviceName property.

2. If the injection target class is a service endpoint interface with the @WebServiceRef annotation and the serviceName property is specified, the deployment system will try to load the mapping file with the following name:

   [@WebServiceRef.name]Service-java-wsdl-mapping.xml

   In this example, [@WebServiceRef.name] represents the value of the name property.

3. If the injection target class is a service endpoint interface with the @WebServiceRef annotation and the wsdlLocation property is specified, then the mapping file will have the same base name as the WSDL file referenced by the wsdlLocation property.

   [base name of WSDL file]Service-java-wsdl-mapping.xml

   For example, if the WSDL file is named MyService.wsdl, then the mapping file for that service must be MyServiceService-java-wsdl-mapping.xml. This is consistent with what WebServicesAssembler generates when you issue a genWSDL or genInterface command. So, copying a mapping file that WebServicesAssembler generates should work naturally.

   Note:

   The wsdlLocation property cannot point to a remote WSDL. The WSDL file must be located in the same archive as the mapping file.

Specifying WSDLs with Multiple Ports in the WebServiceRef Annotation

According to the Java API for XML-based Web Services 2.0 specification, if the WSDL specified for the @WebServiceRef has multiple ports, then the injection target for the annotation must be of type javax.xml.rpc.Service. When the service is injected to this target, a call to getPort(QName portName, Class serviceEndpointInterface) can be made to get the exact port for invocation. In this signature, portname is the name of the specific port you want to work with and serviceEndpointInterface is the name of the service endpoint interface class file.

WebServiceRef Annotation Examples

This section provides examples of using the @WebServiceRef annotation.

In Example 11-1, the reference to the service endpoint interface is being injected into a field and into a setter method. In this case the mapping file would be named SimpleService-java-wsdl-mapping.xml.

Example 11-1 Injecting the Reference into a Field and a Setter Method

@Stateless(name="WSRefBean")
public class StatelessEJBClient implements StatelessEJBClientInterface{
 
    
@WebServiceRef(name="Simple",wsdlLocation="META-INF/SimpleEJBServiceService.wsdl")
    private SimpleEJBService svc;
 
    private SimpleEJBService svc2;
 
    public String echoString(String str) throws RemoteException {
        if(svc == null){
            return "fail1";
        }
        if(svc2 == null){
            return "fail2";
        }
        String test = svc.echoString("Success");
        test = svc2.echoString(test);
        return str + test;
    }
 
    
@WebServiceRef(name="Simple",wsdlLocation="META-INF/SimpleEJBServiceService.wsdl")
    public void setSvc2(SimpleEJBService service){
        svc2 = service;
    }
}

Example 11-2 is similar to the previous example, the only difference is that the injection is into a javax.xml.Service object instead of an actual service endpoint interface. Again, based on the wsdlLocation, the mapping file is expected to be in META-INF (because this is an EJB) and its name should be SimpleService-java-wsdl-mapping.xml.

Example 11-2 Injecting the Reference into javax.xml.Service Object

@Stateless(name="WSRefBean3")
public class StatelessEJBClient3 implements StatelessEJBClientInterface3{
 
    
@WebServiceRef(name="Simple",wsdlLocation="META-INF/SimpleEJBServiceService.wsdl")
    private Service svc;
 
    public String echoString(String test) throws RemoteException {
        if(svc == null){
            return "fail";
        }
        try{
            SimpleEJBService port = 
(SimpleEJBService)svc.getPort(SimpleEJBService.class);
            return port.echoString(test);
        }catch(Exception ex){
            ex.printStackTrace();
            throw new RemoteException(ex.getMessage(),ex);
        }
    }
}

Example 11-3 uses the ejb-jar.xml deployment descriptor for injection. When using this technique, you must specify the version="3.0" on the ejb-jar.xml. This deployment descriptor can work in conjunction with @WebServiceRef.

When you use the ejb-jar.xml deployment descriptor for injection, you can also directly specify the mapping file in the <jaxrpc-mapping-file> element. In this case, the mapping file is CustomSessionBeanService-java-wsdl-mapping.xml.

Example 11-3 Injecting a Reference by Using the ejb-jar.xml Deployment Descriptor

<ejb-jar version="3.0">
    <enterprise-beans>
        <session>           
            <ejb-name>WSRefBean2</ejb-name>
            <ejb-class>oracle.j2ee.tests.ejb.impl.StatelessEJBClient2</ejb-class>
            <session-type>Stateless</session-type>
            <service-ref>
                <service-ref-name>CustomSessionEJB</service-ref-name>
                <service-interface>javax.xml.rpc.Service</service-interface>
                
<service-ref-type>oracle.j2ee.tests.ejb.impl.CustomSession</service-ref-type>
                <wsdl-file>META-INF/CustomSessionBeanService.wsdl</wsdl-file>
                
<jaxrpc-mapping-file>META-INF/CustomSessionBeanService-java-wsdl-mapping.xml</jaxrpc-mapping-file>               
 
                <injection-target>
                    
<injection-target-class>oracle.j2ee.tests.ejb.impl.StatelessEJBClient2</injection-target-class>
                    <injection-target-name>svc</injection-target-name>
                </injection-target>
            </service-ref>
        </session>
    </enterprise-beans>
</ejb-jar>

Oracle Additions to J2SE 5.0 JDK 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

• Schema Annotation

• WSIFEJBBinding Annotation

Deployment Annotation

The @Deployment annotation (oracle.webservices.annotations.Deployment) can be used to supply the deployment attributes to an endpoint implementation or to a service endpoint interface.

Table 11-3 describes the @Deployment annotation's properties. All of the properties are optional.

Note:

The properties in the following table could potentially be overridden by the deployment descriptor or by argument values passed by WebServicesAssembler. For more information, see "How to Override Annotation Values with WebServicesAssembler".

Table 11-3 Deployment Annotation Properties

Properties	Data Type	Description
contextPath	String	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 property 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 property 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. Default: the name of the EAR file.
portName	String	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 property by entering a value for the <port-component[name]> attribute in the oracle-webservices.xml deployment descriptor deployed with the EAR file. Default: For version 3.0 EJBs, this value is taken from the name of the EJB. This name can be specified by the @Stateless.name property on the EJB. If the @Stateless.name property is not set, then the default value for portName is will be the simple name of the EJB. For all other Web services, the default value for portName will be generated with the following pattern: [protocol][binding_and_version] For example, HttpSoap11 or HttpSoap12.
restSupport	Boolean	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: false.
uriPath	String	This value is appended to the value of the contextPath property. Each Web service can have a different uriPath value. You can override the value of this property 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. Default: For version 3.0 EJBs, the default for uriPath is the @Stateless.name property. For other Web services, the default is the simple (unqualified) class name.

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

Schema Annotation

The @Schema annotation (oracle.webservices.annotations.Schema) can be used to configure how schema elements are generated in the WSDL. This is an optional annotation that has only optional properties: elementFormDefault and targetNamespace.

The elementFormDefault property enables you to change the value of the elementFormDefault attribute in the WSDL. The value of this attribute indicates whether locally declared elements must be qualified by the target namespace in an instance document. If the value of this attribute is unqualified, then locally declared elements should not be qualified by the target namespace. If the value of this attribute is qualified, then locally declared elements must be qualified by the target namespace.

The @Schema.elementFormDefault property is an enumeration of two possible values: @Schema.ElementFormDefault.QUALIFIED and @Schema.ElementFormDefault.UNQUALIFIED. By default, OracleAS Web Services tools set the elementFormDefault attribute in all schemas in the WSDL to qualified. By using the @Schema.elementFormDefault property, you can change this behavior.

The targetNamespace property can be used to set the targetNamespace attribute of the generated schema. This namespace will become the default for all types.

Table 11-4 provides a summary of the @Schema annotation's properties.

Note:

The properties in the following table could potentially be overridden by the deployment descriptor or by argument values passed by WebServicesAssembler. For more information, see "How to Override Annotation Values with WebServicesAssembler".

Table 11-4 Schema Annotation Properties

Property	Data Type	Description
elementFormDefault	enum, with values QUALIFIED and UNQUALIFIED	Enables you to change the value of the elementFormDefault attribute in the WSDL. This property can have the following values: QUALIFIED—Changes the value of the elementFormDefault attribute in the WSDL to qualified. Locally declared elements will be qualified by the target namespace. UNQUALIFIED—Changes the value of the elementFormDefault attribute in the WSDL to unqualified. All locally declared elements will not be qualified by the target namespace. Default: QUALIFIED
targetNamespace	String	Sets the targetNamespace attribute of the generated schema. This namespace will become the default for types. Default: An empty string, however, this will result in the same targetNamespace of the WSDL becoming the default.

WSIFEJBBinding Annotation

The @WSIFEJBBinding annotation (oracle.webservices.annotations.@WSIFEJBBinding) generates a Web Services Invocation Framework (WSIF) binding in the WSDL for a version 3.0 EJB. The WSIF bindings are applied only to a single port. The annotation and its associated properties add extensions to the WSDL that allow a WSIF client to access a 3.0 EJB exposed as a Web service.

Note:

In OracleAS Web Services you cannot use a WSDL document which defines only WSIF bindings; it must also define a SOAP binding.

When you assemble a Web Service with the WSIFEJBBinding annotation, always include the SoapBinding annotation, set to the appropriate style and use, to ensure that you get the message encoding you want.

See Also:

The following sections in the Oracle Application Server Advanced Web Services Developer's Guide provide more information on WSIF, EJBs and WSIF clients.

• "WSIF and EJBs" provides information on using WSIF functionality in Web services based on EJBs and WSIF extensions to the WSDL.

• "Writing a WSIF Client" provides information on how to write a client for a service that has WSIF bindings.

Table 11-5 describes the properties that can be specified for the @WSIFEJBBinding annotation. The className and jndiName properties are required.

Note:

The properties in the following table could potentially be overridden by the deployment descriptor or by argument values passed by WebServicesAssembler. For more information, see "How to Override Annotation Values with WebServicesAssembler".

Table 11-5 WSIFEJBBinding Annotation Properties

Property	Data Type	Description
className	String	(required) Specifies the class name of the EJB's home interface. Default: WebServicesAssembler will use the class name of the parent Ant task, if it was specified.
initialContextFactory	String	Specifies the name of the factory that will provide the initial context. Default: The value defaults to com.evermind.server.rmi.RMIInitialContextFactory.
jndiName	String	(required) Specifies the JNDI name for the EJB. Default: The name of the EJB that is found by querying @Stateless.name or the simple name of the EJB class.
jndiProviderURL	String	Specifies the URL for the JNDI Provider. Default: The value defaults to the empty string.
name	String	Specifies the name of the WSIF Port in the Web service. This name will be used to identify the WSIF port in the WSDL's port element. Default: n/a

The following example illustrates the @WSIFEJBBinding annotation being used in an interface file for a version 3.0 EJB.

...
@WebService(name="Hello",
            targetNamespace="http://ejb.oracle.com/targetNamespace",
            serviceName="CustomHelloBeanService")
@WSIFEJBBinding(
   className="oracle.demo.hello.HelloBean",
   jndiName="Hello",
   initialContextFactory="com.evermind.server.rmi.RMIInitialContextFactory",
   jndiProviderUrl="ormi://localhost:23791/ejb30wsif")
public interface CustomHelloBeanIntf extends Remote {
...

When the file is compiled, it generates an EJB WSIF binding in the WSDL, and an EJB port with the following values.

...
<port name="WsifEJBPort" binding="tns:WsifEjbBinding">
    <ejb:address className="oracle.demo.hello.HelloBean"
        jndiName="Hello"
        initialContextFactory="com.evermind.server.rmi.RMIInitialContextFactory"
        jndiProviderURL="ormi://localhost:23791/ejb30wsif"/>
</port>
...

How to Use Annotations

This section contains the following subsections:

• Steps to Use Annotations to Assemble a Web Service from Java Classes

• Steps to Use Annotations to Assemble a Web Service from a Version 3.0 EJB

• How to Override Annotations

• Sample Java File with Annotations

Steps to Use 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 11-4 illustrates a sample annotated Java file.

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

   2. Add the endpointInterface property to the @WebService annotation in the implementation class if you want to reference a service endpoint interface. Note that if the service endpoint interface also has an @WebService annotation, 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

      Note:

      If you enter an @WebService annotation on a service endpoint interface and no @WebMethod annotations, then all of the methods will be exposed regardless of the number of @WebMethod annotations you enter.

      If you enter an @WebService annotation on an implementation bean and no @WebMethod annotations, then you should get a verification exception, because you must have at least one method exposed. See Sections 4.1 and 4.2 of the Web Services Metadata for the Java Platform specification.

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.

Steps to Use 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 annotation 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 annotation to the interface that the bean implements.

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

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

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

      Note:

      If you enter an @WebService annotation on a service endpoint interface and no @WebMethod annotations, then all of the methods will be exposed regardless of the number of @WebMethod annotations you enter.

      If you enter an @WebService annotation on an implementation bean and no @WebMethod annotations, then you should get a verification exception, because you must have at least one method exposed. See Sections 4.1 and 4.2 of the Web Services Metadata for the Java Platform specification.

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

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

   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 properties of the @Deployment annotation.

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

How to Override Annotations

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

• How to Override Annotation Values with WebServicesAssembler

• How to Override Deployment Annotation Values with Deployment Descriptors

How to Override 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.

Table 11-6 WebServicesAssembler Arguments that can Override Annotation Values

This WebServicesAssembler argument	Will override this annotation
context	@Deployment.contextPath
portName	@Deployment.portName
portTypeName	@WebService.name (the @WebService.name annotation is used to derive the portType name in the WSDL. See section 5.11 of the Web Services Metadata for the Java Platform specification.
qualifiedElementForm	@Schema.elementFormDefault
restSupport	@Deployment.restSupport
serviceName	@WebService.serviceName
targetNamespace	@WebService.targetNamespace
typeNamespace	@Schema.targetNamespace
uri	@Deployment.uriPath

How to Override 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 properties 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 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 11-4 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 enables you to provide values for the serviceName and targetNamespace properties. These properties are used to populate the wsdl:service name and wsdl:targetNamespace elements in the generated WSDL file. The targetNamespace property provides the default namespace for the WSDL and the schema types.

  Note:

  The target namespace for schema elements and types will be the same as that specified in @WebService.targetNamespace or the generated namespace of the WSDL. For a document-literal Web service, you can assign operation parameters to different namespaces by using the @WebParam.targetNamespace annotation property. For example:

  @WebParam(name="param", targetNamespace="http://mytns")
  

  Note that in this case, you must set the @WebParam.name property. For document-literal wrapped services, the wrapper element will always be created in the same target namespace as the WSDL.

  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 11-4 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:

• using the Test Page to test Web service deployment, see Chapter 13, "Testing Web Services Deployment".

• building J2SE clients, see Chapter 15, "Assembling a J2SE Web Service Client".

• building J2EE clients, see Chapter 14, "Assembling a J2EE Web Service Client".

• JAX-RPC handlers, see Chapter 16, "Using JAX-RPC Handlers".

• JAR files that are needed to assemble a client, see Appendix A, "Web Service Client APIs and JARs".

• Web services interoperability, see "Ensuring Interoperable Web Services" in the Oracle Application Server Advanced Web Services Developer's Guide.

• using quality of service features in Web service clients, see "Managing Web Services" in the Oracle Application Server Advanced Web Services Developer's Guide.

• adding security to a Web service, see the Oracle Application Server Web Services Security Guide.

• adding reliability to a Web service, see "Ensuring Web Service Reliability" in the Oracle Application Server Advanced Web Services Developer's Guide.

• adding an auditing and logging configuration to a Web service, see "Auditing and Logging Messages" in the Oracle Application Server Advanced Web Services Developer's Guide.

• processing nonstandard data types, see "Custom Serialization of Java Value Types" in the Oracle Application Server Advanced Web Services Developer's Guide.

• the JAX-RPC mapping file, see "JAX-RPC Mapping File Descriptor" in the Oracle Application Server Advanced Web Services Developer's Guide.

• data types supported by OracleAS Web Services, see "Mapping Java Types to XML and WSDL Types" in the Oracle Application Server Advanced Web Services Developer's Guide.

• Oracle JDeveloper tool support for Web service development, see the Oracle JDeveloper on-line help.