Skip navigation.
Downloads | Product Documentation | Support

Programming Web Services for WebLogic Server

# JWS Annotation Reference

The following sections provide reference documentation about standard (JSR-181) and WebLogic-specific JWS annotations:

- Overview of JWS Annotation Tags
- Standard JSR-181 JWS Annotations Reference
- WebLogic-Specific JWS Annotations Reference

# Overview of JWS Annotation Tags

The WebLogic Web Services programming model uses the new JDK 5.0 metadata annotations feature (specified by JSR-175). In this programming model, you create an annotated Java file and then use Ant tasks to compile the file into the Java source code and generate all the associated artifacts.

The Java Web Service (JWS) annotated file is the core of your Web Service. It contains the Java code that determines how your Web Service behaves. A JWS file is an ordinary Java class file that uses annotations to specify the shape and characteristics of the Web Service. The JWS annotations you can use in a JWS file include the standard ones defined by the Web Services Metadata for the Java Platform specification (JSR-181) as well as a set of WebLogic-specific ones. This chapter provides reference information about both of these set of annotations.

You can target a JWS annotation at either the class-, method- or parameter-level in a JWS file. Some annotations can be targeted at more than one level, such as `@SecurityRoles` that can be targeted at both the class- and method-level. The documentation in this section lists the level to which you can target each annotation.

The following example shows a simple JWS file that uses both standard JSR-181 and WebLogic-specific JWS annotations, shown in bold:

>     package examples.webservices.complex;

>     // Import the standard JWS annotation interfaces

>     import javax.jws.WebMethod;
>     import javax.jws.WebParam;
>     import javax.jws.WebResult;
>     import javax.jws.WebService;
>     import javax.jws.soap.SOAPBinding;

>     // Import the WebLogic-specific JWS annotation interface

>     import weblogic.jws.WLHttpTransport;

>     // Import the BasicStruct JavaBean

>     import examples.webservices.complex.BasicStruct;

>     // Standard JWS annotation that specifies that the portType name of the Web
>     // Service is "ComplexPortType", its public service name is "ComplexService",
>     // and the targetNamespace used in the generated WSDL is "http://example.org"

>     @WebService(serviceName="ComplexService", name="ComplexPortType",
>                 targetNamespace="http://example.org")

>     // Standard JWS annotation that specifies this is a document-literal-wrapped
>     // Web Service

>     @SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
>                  use=SOAPBinding.Use.LITERAL,
>                  parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)

>     // WebLogic-specific JWS annotation that specifies the context path and service
>     // URI used to build the URI of the Web Service is "complex/ComplexService"

>     @WLHttpTransport(contextPath="complex", serviceUri="ComplexService",
>                      portName="ComplexServicePort")

>     /**
>      * This JWS file forms the basis of a WebLogic Web Service.  The Web Services
>      * has two public operations:
>      *
>      *  - echoInt(int)
>      *  - echoComplexType(BasicStruct)
>      *
>      * The Web Service is defined as a "document-literal" service, which means
>      * that the SOAP messages have a single part referencing an XML Schema element
>      * that defines the entire body.
>      *
>      * @author Copyright (c) 2005 by BEA Systems. All Rights Reserved.
>      */

>     public class ComplexImpl {

>       // Standard JWS annotation that specifies that the method should be exposed
>       // as a public operation.  Because the annotation does not include the
>       // member-value "operationName", the public name of the operation is the
>       // same as the method name: echoInt.
>       //
>       // The WebResult annotation specifies that the name of the result of the
>       // operation in the generated WSDL is "IntegerOutput", rather than the
>       // default name "return".   The WebParam annotation specifies that the input
>       // parameter name in the WSDL file is "IntegerInput" rather than the Java
>       // name of the parameter, "input".

>       @WebMethod()
>       @WebResult(name="IntegerOutput",
>                  targetNamespace="http://example.org/complex")
>       public int echoInt(
>           @WebParam(name="IntegerInput",
>                     targetNamespace="http://example.org/complex")
>           int input)
>       {
>         System.out.println("echoInt '" + input + "' to you too!");
>         return input;
>       }

>       // Standard JWS annotation to expose method "echoStruct" as a public operation
>       // called "echoComplexType"
>       // The WebResult annotation specifies that the name of the result of the
>       // operation in the generated WSDL is "EchoStructReturnMessage",
>       // rather than the default name "return".

>       @WebMethod(operationName="echoComplexType")
>       @WebResult(name="EchoStructReturnMessage",
>                  targetNamespace="http://example.org/complex")
>       public BasicStruct echoStruct(BasicStruct struct)
>       {
>         System.out.println("echoComplexType called");
>         return struct;
>       }
>     }

# Standard JSR-181 JWS Annotations Reference

The Web Services Metadata for the Java Platform (JSR-181) specification defines the standard annotations you can use in your JWS file to specify the shape and behavior of your Web Service. This section briefly describes each annotation, along with its attributes. See Programming the JWS File, for examples. For more detailed information about the annotations, such as the Java annotation type definition and additional examples, see the specification.

This section documents the following standard JWS annotations:

- javax.jws.WebService
- javax.jws.WebMethod
- javax.jws.Oneway
- javax.jws.WebParam
- javax.jws.WebResult
- javax.jws.HandlerChain
- javax.jws.soap.SOAPBinding
- javax.jws.soap.SOAPMessageHandler
- javax.jws.soap.InitParam
- javax.jws.soap.SOAPMessageHandlers

## javax.jws.WebService

### Description

Target: Class

Specifies that the JWS file implements a Web Service.

### Attributes

Table B-1 Attributes of the javax.jws.WebService JWS Annotation

Name | Description | Data Type | Required?
--- | --- | --- | ---
name | Name of the Web Service. Maps to the `<wsdl:portType>` element in the WSDL file. Default value is the unqualified name of the Java class in the JWS file. | String | No.
targetNamespace | The XML namespace used for the WSDL and XML elements generated from this Web Service. The default value is specified by the JAX-RPC specification. | String. | No.
serviceName | Service name of the Web Service. Maps to the `<wsdl:service>` element in the WSDL file. Default value is the unqualified name of the Java class in the JWS file, appended with the string `Service`. | String | No.
wsdlLocation | Relative or absolute URL of a pre-defined WSDL file. If you specify this attribute, the `jwsc` Ant task does not generate a WSDL file, and returns an error if the JWS file is inconsistent with the port types and bindings in the WSDL file. Note: The `wsdlc` Ant task uses this attribute when it generates the endpoint interface JWS file from a WSDL. Typically, users never use the attribute in their own JWS files. | String. | No.
endpointInterface | Fully qualified name of an existing service endpoint interface file. If you specify this attribute, it is asumed that you have already created the endpoint interface file and it is in your CLASSPATH. | String. | No.

### Example

>     @WebService(name="JMSTransportPortType",
>                 serviceName="JMSTransportService",
>                 targetNamespace="http://example.org")

## javax.jws.WebMethod

### Description

Target: Method

Specifies that the method is exposed as a public operation of the Web Service. You must explicitly use this annotation to expose a method; if you do not specify this annotation, the method by default is not exposed.

### Attributes

Table B-2 Attributes of the javax.jws.WebMethod JWS Annotation

Name | Description | Data Type | Required?
--- | --- | --- | ---
operationName | Name of the operation. Maps to the `<wsdl:operation>` element in the WSDL file. Default value is the name of the method. | String | No.
action | The action for this operation. For SOAP bindings, the value of this attribute determines the value of the `SOAPAction` header in the SOAP messages. | String | No.

### Example

>      @WebMethod(operationName="echoComplexType")

>      public BasicStruct echoStruct(BasicStruct struct)
>      {
>         ...
>      }

## javax.jws.Oneway

### Description

Target: Method

Specifies that the method has only input parameters, but does not return a value. This annotation must be used only in conjunction with the `@WebMethod` annotation.

It is an error to use this annotation on a method that returns anything other than `void`, takes a `Holder` class as an input parameter, or throws checked exceptions.

This annotation does not have any attributes.

### Example

>       @WebMethod()
>       @Oneway()
>       public void helloWorld(String input) {
>         ...

>       }

## javax.jws.WebParam

### Description

Target: Parameter

Customizes the mapping between operation input parameters of the Web Service and elements of the generated WSDL file. Also used to specify the behavior of the parameter.

### Attributes

Table B-3 Attributes of the javax.jws.WebParam JWS Annotation

Name | Description | Data Type | Required?
--- | --- | --- | ---
name | Name of the parameter in the WSDL file. For RPC-style Web Services, the name maps to the `<wsdl:part>` element that represents the parameter. For document-style Web Services, the name is the local name of the XML element that represents the parameter. The default value is the name of the method's parameter. | String | No.
targetNamespace | The XML namespace of the parameter. This value is used only used for document-style Web Services, in which the parameter maps to an XML element. The default value is the targetNamespace of the Web Service. | String | No.
mode | The direction in which the parameter is flowing. Valid values are: `WebParam.Mode.IN` `WebParam.Mode.OUT` `WebParam.Mode.INOUT` Default value is `WebParam.Mode.IN`. If you specify `WebParam.Mode.OUT` or `WebParam.Mode.INOUT`, then the data type of the parameter must be `Holder`, or extend `Holder`. For details, see the JAX-RPC specification. `WebParam.Mode.OUT` and `WebParam.Mode.INOUT` modes are only supported for RPC-style Web Services or for parameters that map to headers. | enum | No.
header | Specifies whether the value of the parameter is found in the SOAP header. By default parameters are in the SOAP body. Valid values are `true` and `false`. Default value is `false`. | boolean | No.

### Example

>      @WebMethod()
>      public int echoInt(
>          @WebParam(name="IntegerInput",
>                    targetNamespace="http://example.org/complex")
>          int input)
>      {
>        ...
>      }

## javax.jws.WebResult

### Description

Target: Method

Customizes the mapping between the Web Service operation return value and the corresponding element of the generated WSDL file.

### Attributes

Table B-4 Attributes of the javax.jws.WebResult JWS Annotation

Name | Description | Data Type | Required?
--- | --- | --- | ---
name | Name of the parameter in the WSDL file. For RPC-style Web Services, the name maps to the `<wsdl:part>` element that represents the return value. For document-style Web Services, the name is the local name of the XML element that represents the return value. The default value is the hard-coded name `result`. | String | No.
targetNamespace | The XML namespace of the return value. This value is used only used for document-style Web Services, in which the return value maps to an XML element. The default value is the targetNamespace of the Web Service. | String | No.

### Example

>       @WebMethod(operationName="echoComplexType")
>       @WebResult(name="EchoStructReturnMessage",
>                  targetNamespace="http://example.org/complex")
>       public BasicStruct echoStruct(BasicStruct struct)
>       {
>        ...
>       }

## javax.jws.HandlerChain

### Description

Target: Class

Associates a Web Service with an external file that contains the configuration of a handler chain. The configuration includes the list of handlers in the chain, the order in which they execute, the initialization parameters, and so on.

Use the `@HandlerChain` annotation, rather than the `@SOAPMessageHandlers` annotation, in your JWS file if:

- You want multiple Web Services to share the same configuration.
- Your handler chain includes handlers for multiple transports.
- You want to be able to change the handler chain configuration for a Web Service without recompiling the JWS file that implements it.

It is an error to combine this annotation with the `@SOAPMessageHandlers` annotation.

For the XML Schema of the external configuration file, additional information about creating it, and additional examples, see the Web Services Metadata for the Java Platform specification.

### Attributes

Table B-5 Attributes of the javax.jws.HandlerChain JWS Annotation

Name | Description | Data Type | Required?
--- | --- | --- | ---
file | URL, either relative or absolute, of the handler chain configuration file. Relative URLs are relative to the location of JWS file. | String | Yes
name | Name of the handler chain (in the configuration file pointed to by the `file` attribute) that you want to associate with the Web Service. | String | Yes.

### Example

>     package examples.webservices.handler;

>     ...

>     @WebService (...)

>     @HandlerChain(file="HandlerConfig.xml", name="SimpleChain")

>     public class HandlerChainImpl {

>     ...

>     }

## javax.jws.soap.SOAPBinding

### Description

Target: Class

Specifies the mapping of the Web Service onto the SOAP message protocol.

### Attributes

Table B-6 Attributes of the javax.jws.soap.SOAPBinding JWS Annotation

Name | Description | Data Type | Required?
--- | --- | --- | ---
style | Specifies the message style of the request and response SOAP messages. Valid values are: `SOAPBinding.Style.RPC` `SOAPBinding.Style.DOCUMENT`. Default value is `SOAPBinding.Style.DOCUMENT`. | enum | No.
use | Specifies the formatting style of the request and response SOAP messages. Valid values are: `SOAPBinding.Use.LITERAL` `SOAPBinding.Use.ENCODED` Default value is `SOAPBinding.Use.LITERAL`. | enum | No.
parameterStyle | Determines whether method parameters represent the entire message body, or whether the parameters are elements wrapped inside a top-level element named after the operation. Valid values are: `SOAPBinding.ParameterStyle.BARE` `SOAPBinding.ParameterStyle.WRAPPED` Default value is `SOAPBinding.ParameterStyle.WRAPPED` Note: This attribute applies only to Web Services of style document-literal. Or in other words, you can specify this attribute only if you have also set the `style` attribute to `SOAPBinding.Style.DOCUMENT` and the `use` attribute to `SOAPBinding.Use.LITERAL`. | enum | No.

### Example

>     package examples.webservices.bindings;

>     ...

>     @WebService (...)

>     @SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
>                  use=SOAPBinding.Use.LITERAL,
>                  parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)

>     public class BindingsImpl {

>     ...

>     }

## javax.jws.soap.SOAPMessageHandler

### Description

Target: None; this annotation can be used only inside of a `@SOAPMessageHandler` array.

Specifies a particular SOAP message handler in a `@SOAPMessageHandler` array. The annotation includes attributes to specify the class name of the handler, the initialization parameters, list of SOAP headers processed by the handler, and so on.

### Attributes

Table B-7 Attributes of the javax.jws.soap.SOAPMessageHandler JWS Annotation

Name | Description | Data Type | Required?
--- | --- | --- | ---
name | Name of the SOAP message handler. The default value is the name of the class that implements the `Handler` interface (or extends the `GenericHandler` abstract class.) | String | No.
className | Name of the handler class. | String | Yes.
initParams | Array of name/value pairs that is passed to the handler class during initialization. | Array of `@InitParam` | No.
roles | List of SOAP roles implemented by the handler. | Array of String | No.
headers | List of SOAP headers processed by the handler. Each element in this array contains a QName which defines the header element processed by the handler. | Array of String | No.

### Example

>     package examples.webservices.handlers;

>     ...

>     @WebService (...)

>     @SOAPMessageHandlers ( {
>       @SOAPMessageHandler (
>        className="examples.webservices.soap_handlers.simple.ServerHandler1"),
>       @SOAPMessageHandler (
>        className="examples.webservices.soap_handlers.simple.ServerHandler2")
>     } )

>     public class HandlersImpl {

>     ...

>     }

## javax.jws.soap.InitParam

### Description

Target: None; this annotation can be used only as a value to the `initParams` attribute of the `@SOAPMessageHandler` annotation.

Use this annotation in the `initParams` attribute of the `@SOAPMessageHandler` annotation to specify the array of parameters (name/value pairs) that are passed to a handler class during initialization.

### Attributes

Table B-8 Attributes of the javax.jws.soap.InitParam JWS Annotation

Name | Description | Data Type | Required?
--- | --- | --- | ---
name | Name of the initialization parameter. | String | Yes.
value | Value of the initialization parameter. | String | Yes.

## javax.jws.soap.SOAPMessageHandlers

### Description

Target: Class

Specifies an array of SOAP message handlers that execute before and after the operations of a Web Service. Use the `@SOAPMessageHandler` annotation to specify a particular handler. Because you specify the list of handlers within the JWS file itself, the configuration of the handler chain is embedded within the Web Service.

Use the `@SOAPMessageHandlers` annotation, rather than `@HandlerChain`, if:

- You prefer to embed the configuration of the handler chain inside the Web Service itself, rather than specify the configuration in an external file.
- Your handler chain includes only SOAP handlers and none for any other transport.
- You prefer to recompile the JWS file each time you change the handler chain configuration.

The `@SOAPMessageHandlers` annotation is an array of `@SOAPMessageHandler` types. The handlers run in the order in which they appear in the annotation, starting with the first handler in the array.

This annotation does not have any attributes.

### Example

>     package examples.webservices.handlers;

>     ...

>     @WebService (...)

>     @SOAPMessageHandlers ( {
>       @SOAPMessageHandler (
>        className="examples.webservices.soap_handlers.simple.ServerHandler1"),
>       @SOAPMessageHandler (
>        className="examples.webservices.soap_handlers.simple.ServerHandler2")
>     } )

>     public class HandlersImpl {

>     ...

>     }

# WebLogic-Specific JWS Annotations Reference

WebLogic Web Services define a set of JWS annotations that you can use to specify behavior and features in addition to the standard JSR-181 JWS annotations. In particular, the WebLogic-specific annotations are:

- weblogic.jws.AsyncFailure
- weblogic.jws.AsyncResponse
- weblogic.jws.BufferQueue
- weblogic.jws.Context
- weblogic.jws.Conversation
- weblogic.jws.Conversational
- weblogic.jws.MessageBuffer
- weblogic.jws.Policies
- weblogic.jws.Policy
- weblogic.jws.ReliabilityBuffer
- weblogic.jws.ServiceClient
- weblogic.jws.Transactional
- weblogic.jws.WLHttpTransport
- weblogic.jws.WLHttpsTransport
- weblogic.jws.WLJmsTransport
- weblogic.jws.WSDL
- weblogic.jws.security.RolesAllowed
- weblogic.jws.security.RolesReferenced
- weblogic.jws.security.RunAs
- weblogic.jws.security.SecurityRole
- weblogic.jws.security.SecurityRoleRef
- weblogic.jws.security.UserDataConstraint
- weblogic.jws.security.WssConfiguration
- weblogic.jws.security.SecurityRoles (deprecated)
- weblogic.jws.security.SecurityIdentity (deprecated)

## weblogic.jws.AsyncFailure

### Description

Target: Method

Specifies the method that handles a potential failure when the main JWS file invokes an operation of another Web Service asynchronously.

When you invoke, from within a JWS file, a Web Service operation asynchronously, the response (or exception, in the case of a failure) does not return immediately after the operation invocation, but rather, at some later point in time. Because the operation invocation did not wait for a response, a separate method in the JWS file must handle the response when it does finally return; similarly, another method must handle a potential failure. Use the `@AsyncFailure` annotation to specify the method in the JWS file that will handle the potential failure of an asynchronous operation invocation.

The `@AsyncFailure` annotation takes two parameters: the name of the JAX-RPC stub for the Web Service you are invoking and the name of the operation that you are invoking asynchronously. The JAX-RPC stub is the one that has been annotation with the `@ServiceClient` annotation.

The method that handles the asynchronous failure must follow these guidelines:

- Return `void`.
- Be named `on` `MethodName` `AsyncFailure`, where `MethodName` is the name of the method you are invoking asynchronously (with initial letter always capitalized.)

In the main JWS file, the call to the asynchronous method will look something like:

>     port.getQuoteAsync (apc, symbol);

where `getQuote` is the non-asynchronous name of the method, `apc` is the asynchronous pre-call context, and `symbol` is the usual parameter to the `getQuote` operation.

- Have two parameters: the asynchronous post-call context (contained in the `weblogic.wsee.async.AsyncPostCallContext` object) and the `Throwable` exception, potentially thrown by the asynchronous operation call.

Within the method itself you can get more information about the method failure from the context, and query the specific type of exception and act accordingly.

Typically, you always use the `@AsyncFailure` annotation to explicitly specify the method that handles asynchronous operation failures. The only time you would not use this annotation is if you want a single method to handle failures for two or more stubs that invoke different Web Services. In this case, although the stubs connect to different Web Services, each Web Service must have a similarly named method, because the Web Services runtime relies on the name of the method (`on` `MethodName` `AsyncFailure`) to determine how to handle the asynchronous failure, rather than the annotation. However, if you always want a one-to-one correspondence between a stub and the method that handles an asynchronous failure from one of the operations, then BEA recommends that you explicitly use `@AsyncFailure`.

See Invoking a Web Service Using Asynchronous Request-Response for detailed information and examples of using this annotation.

### Attributes

Table B-9 Attributes of the weblogic.jws.AsyncFailure JWS Annotation Tag

Name | Description | Data Type | Required?
--- | --- | --- | ---
target | The name of the JAX-RPC stub of the Web Service for which you want to invoke an operation asynchronously. The stub is the one that has been annotated with the `@ServiceClient` field-level annotation. | String | Yes
> operation | The name of the operation that you want to invoke asynchronously. This is the actual name of the operation, as it appears in the WSDL file. When you invoke this operation in the main code of the JWS file, you add `Async` to its name. For example, if set `operation="getQuote"`, then in the JWS file you invoke it asynchronously as follows:
>      port.getQuoteAsync (apc, symbol);
| String | Yes.

### Example

The following sample snippet shows how to use the `@AsyncFailure` annotation in a JWS file that invokes the operation of another Web Service asynchronously; only the relevant Java code is included:

>     package examples.webservices.async_req_res;

>     ...

>     public class StockQuoteClientImpl {

>       @ServiceClient(wsdlLocation="http://localhost:7001/async/StockQuote?WSDL",
>                      serviceName="StockQuoteService", portName="StockQuote")
>       private StockQuotePortType port;

>       @WebMethodpublic void getQuote (String symbol) {

>         AsyncPreCallContext apc = AsyncCallContextFactory.getAsyncPreCallContext();
>         apc.setProperty("symbol", symbol);

>         try {
>           port.getQuoteAsync(apc, symbol );
>           System.out.println("in getQuote method of StockQuoteClient WS");
>         }
>         catch (RemoteException e) {
>           e.printStackTrace();
>         }

>       }

>     ...

>       @AsyncFailure(target="port", operation="getQuote")
>       public void onGetQuoteAsyncFailure(AsyncPostCallContext apc, Throwable e) {
>         System.out.println("-------------------");
>         e.printStackTrace();
>         System.out.println("-------------------");
>       }

>     }

The example shows a JAX-RPC stub called `port`, used to invoke the Web Service located at `http://localhost:7001/async/StockQuote`. The `getQuote` operation is invoked asynchronously, and any exception from this invocation is handled by the `onGetQuoteAsyncFailure` method, as specified by the `@AsyncFailure` annotation.

## weblogic.jws.AsyncResponse

### Description

Target: Method

Specifies the method that handles the response when the main JWS file invokes an operation of another Web Service asynchronously.

When you invoke, from within a JWS file, a Web Service operation asynchronously, the response does not return immediately after the operation invocation, but rather, at some later point in time. Because the operation invocation did not wait for a response, a separate method in the JWS file must handle the response when it does finally return. Use the `@AsyncResponse` annotation to specify the method in the JWS file that will handle the response of an asynchronous operation invocation.

The `@AsyncResponse` annotation takes two parameters: the name of the JAX-RPC stub for the Web Service you are invoking and the name of the operation that you are invoking asynchronously. The JAX-RPC stub is the one that has been annotation with the `@ServiceClient` annotation.

The method that handles the asynchronous response must follow these guidelines:

- Return `void`.
- Be named `on` `MethodName` `AsyncResponse`, where `MethodName` is the name of the method you are invoking asynchronously (with initial letter always capitalized.)

In the main JWS file, the call to the asynchronous method will look something like:

>     port.getQuoteAsync (apc, symbol);

where `getQuote` is the non-asynchronous name of the method, `apc` is the asynchronous pre-call context, and `symbol` is the usual parameter to the `getQuote` operation.

- Have two parameters: the asynchronous post-call context (contained in the `weblogic.wsee.async.AsyncPostCallContext` object) and the usual return value of the operation.

Within the asynchronous-response method itself you add the code to handle the response. You can also get more information about the method invocation from the context.

Typically, you always use the `@AsyncResponse` annotation to explicitly specify the method that handles asynchronous operation responses. The only time you would not use this annotation is if you want a single method to handle the response for two or more stubs that invoke different Web Services. In this case, although the stubs connect to different Web Services, each Web Service must have a similarly named method, because the Web Services runtime relies on the name of the method (`on` `MethodName` `AsyncResponse`) to determine how to handle the asynchronous response, rather than the annotation. However, if you always want a one-to-one correspondence between a stub and the method that handles an asynchronous response from one of the operations, then BEA recommends that you explicitly use `@AsyncResponse`.

See Invoking a Web Service Using Asynchronous Request-Response for detailed information and examples of using this annotation.

### Attributes

Table B-10 Attributes of the weblogic.jws.AsyncResponse JWS Annotation Tag

Name | Description | Data Type | Required?
--- | --- | --- | ---
target | The name of the JAX-RPC stub of the Web Service for which you want to invoke an operation asynchronously. The stub is the one that has been annotated with the `@ServiceClient` field-level annotation. | String | Yes
> operation | The name of the operation that you want to invoke asynchronously. This is the actual name of the operation, as it appears in the WSDL file. When you invoke this operation in the main code of the JWS file, you add `Async` to its name. For example, if set `operation="getQuote"`, then in the JWS file you invoke it asynchronously as follows:
>      port.getQuoteAsync (apc, symbol);
| String | Yes.

### Example

The following sample snippet shows how to use the `@AsyncResponse` annotation in a JWS file that invokes the operation of another Web Service asynchronously; only the relevant Java code is included:

>     package examples.webservices.async_req_res;

>     ...

>     public class StockQuoteClientImpl {

>       @ServiceClient(wsdlLocation="http://localhost:7001/async/StockQuote?WSDL",
>                      serviceName="StockQuoteService", portName="StockQuote")
>       private StockQuotePortType port;

>       @WebMethodpublic void getQuote (String symbol) {

>         AsyncPreCallContext apc = AsyncCallContextFactory.getAsyncPreCallContext();
>         apc.setProperty("symbol", symbol);

>         try {
>           port.getQuoteAsync(apc, symbol );
>           System.out.println("in getQuote method of StockQuoteClient WS");
>         }
>         catch (RemoteException e) {
>           e.printStackTrace();
>         }

>       }

>     ...

>       @AsyncResponse(target="port", operation="getQuote")
>       public void onGetQuoteAsyncResponse(AsyncPostCallContext apc, int quote) {
>         System.out.println("-------------------");
>         System.out.println("Got quote " + quote );
>         System.out.println("-------------------");
>       }

>     }

The example shows a JAX-RPC stub called `port`, used to invoke the Web Service located at `http://localhost:7001/async/StockQuote`. The `getQuote` operation is invoked asynchronously, and the response from this invocation is handled by the `onGetQuoteAsyncResponse` method, as specified by the `@AsyncResponse` annotation.

## weblogic.jws.BufferQueue

### Description

Target: Class

Specifies the JNDI name of the JMS queue to which WebLogic Server:

- stores a buffered Web Service operation invocation.
- stores a reliable Web Service operation invocation.

When used with buffered Web Services, you use this annotation in conjunction with `@MessageBuffer`, which specifies the methods of a JWS that are buffered. When used with reliable Web Services, you use this annotation in conjunction with `@Policy`, which specifies the reliable messaging WS-Policy file associated with the Web Service.

If you have enabled buffering or reliable messaging for a Web Service, but do not specify the `@BuffereQueue` annotation, WebLogic Server uses the default Web Services JMS queue (`weblogic.wsee.DefaultQueue`) to store buffered or reliable operation invocations. This JMS queue is also the default queue for the JMS transport features. It is assumed that you have already created this JMS queue if you intend on using it for any of these features.

See Creating Buffered Web Services and Using Web Service Reliable Messaging for detailed information and examples of creating buffered or reliable Web Services.

### Attributes

Table B-11 Attributes of the weblogic.jws.BufferQueue JWS Annotation Tag

Name | Description | Data Type | Required?
--- | --- | --- | ---
name | The JNDI name of the JMS queue to which the buffered or reliable operation invocation is queued. | String | Yes

### Example

The following example shows a code snippet from a JWS file in which the public operation is buffered and the JMS queue to which WebLogic Server queues the operation invocation is called `my.buffere.queue`; only the relevant Java code is shown:

>     package examples.webservices.buffered;

>     ...

>     @WebService(name="BufferedPortType",
>                 serviceName="BufferedService",
>                 targetNamespace="http://example.org")

>     @BufferQueue(name="my.buffer.queue")

>     public class BufferedImpl {

>     ...

>       @WebMethod()
>       @MessageBuffer(retryCount=10, retryDelay="10 seconds")
>       @Oneway()
>       public void sayHelloNoReturn(String message) {
>         System.out.println("sayHelloNoReturn: " + message);
>       }
>     }

## weblogic.jws.Context

### Description

Target: Field

Specifies that the annotated field provide access to the runtime context of the Web Service.

When a client application invokes a WebLogic Web Service that was implemented with a JWS file, WebLogic Server automatically creates a context that the Web Service can use to access, and sometimes change, runtime information about the service. Much of this information is related to conversations, such as whether the current conversation is finished, the current values of the conversational properties, changing conversational properties at runtime, and so on. Some of the information accessible via the context is more generic, such as the protocol that was used to invoke the Web Service (HTTP/S or JMS), the SOAP headers that were in the SOAP message request, and so on. The data type of the annotation field must be `weblogic.wsee.jws.JwsContext`, which is a WebLogic Web Service API that includes methods to query the context.

For additional information about using this annotation, see Accessing Runtime Information about a Web Service Using the JwsContext.

This annotation does not have any attributes.

### Example

The following snippet of a JWS file shows how to use the `@Context` annotation; only parts of the file are shown, with relevant code in bold:

>     ...

>     import weblogic.jws.Context;

>     import weblogic.wsee.jws.JwsContext;

>     ...

>     public class JwsContextImpl {

>       @Context
>       private JwsContext ctx;

>       @WebMethod()
>       public String getProtocol() {

>     ...

## weblogic.jws.Conversation

### Description

Target: Method

Specifies that a method annotated with the `@Conversation` annotation can be invoked as part of a conversation between two WebLogic Web Services or a stand-alone Java client and a conversational Web Service.

The conversational Web Service typically specifies three methods, each annotated with the `@Conversation` annotation that correspond to the start, continue, and finish phases of a conversation. Use the`@Conversational` annotation to specify, at the class level, that a Web Service is conversational and to configure properties of the conversation, such as the maximum idle time.

If the conversation is between two Web Services, the client service uses the `@ServiceClient` annotation to specify the wsdl, service name, and port of the invoked conversational service. In both the service and stand-alone client cases, the client then invokes the start, continue, and finish methods in the appropriate order to conduct a conversation.The only additional requirement to make a Web Service conversational is that it implement `java.io.Serializable`.

See Creating Conversational Web Services for detailed information and examples of using this annotation.

### Attributes

Table B-12 Attributes of the weblogic.jws.Conversation JWS Annotation Tag

Name | Description | Data Type | Required?
--- | --- | --- | ---
value | Specifies the phase of a conversation that the annotated method implements. Possible values are: `Phase.START` Specifies that the method starts a new conversation. A call to this method creates a new conversation ID and context, and resets its idle and age timer. `Phase.CONTINUE` Specifies that the method is part of a conversation in progress. A call to this method resets the idle timer. This method must always be called after the start method and before the finish method. `Phase.FINISH` Specifies that the method explicitly finishes a conversation in progress. Default value is `Phase.CONTINUE` | enum | No.

### Example

The following sample snippet shows a JWS file that contains three methods, `start`, `middle`, and `finish`) that are annotated with the `@Conversation` annotation to specify the start, continue, and finish phases, respectively, of a conversation.

>     ...

>     public class ConversationalServiceImpl implements Serializable {

>       @WebMethod
>       @Conversation (Conversation.Phase.START)
>       public String start() {
>         // Java code for starting a conversation goes here
>       }

>       @WebMethod
>       @Conversation (Conversation.Phase.CONTINUE)
>       public String middle(String message) {
>         // Java code for continuing a conversation goes here
>       }

>       @WebMethod
>       @Conversation (Conversation.Phase.FINISH)
>       public String finish(String message ) {
>         // Java code for finishing a conversation goes here
>       }

>     }

## weblogic.jws.Conversational

### Description

Target: Class

Specifies that a JWS file implements a conversational Web Service.

You are not required to use this annotation to specify that a Web Service is conversational; by simply annotating a single method with the `@Conversation` annotation, all the methods of the JWS file are automatically tagged as conversational. Use the class-level `@Conversational` annotation only if you want to change some of the conversational behavior or if you want to clearly show at the class level that the JWS if conversational.

If you do use the `@Conversational` annotation in your JWS file, you can specify it without any attributes if their default values suit your needs. However, if you want to change values such as the maximum amount of time that a conversation can remain idle, the maximum age of a conversation, and so on, specify the appropriate attribute.

See Creating Conversational Web Services for detailed information and examples of using this annotation.

### Attributes

Table B-13 Attributes of the weblogic.jws.Conversational JWS Annotation Tag

Name | Description | Data Type | Required?
--- | --- | --- | ---
maxIdleTime | Specifies the amount of time that a conversation can remain idle before it is finished by WebLogic Server. Activity is defined by a client Web Service executing one of the phases of the conversation. Valid values are a number and one of the following terms: `seconds` `minutes` `hours` `days` `years` For example, to specify a maximum idle time of ten minutes, specify the annotation as follows: `@Conversational(maxIdleTime="10 minutes")` If you specify a zero-length value (such as `0 seconds`, or `0 minutes` and so on), then the conversation never times out due to inactivity. Default value is `0 seconds`. | String | No.
maxAge | The amount of time that a conversation can remain active before it is finished by WebLogic Server. Valid values are a number and one of the following terms: `seconds` `minutes` `hours` `days` `years` For example, to specify a maximum age of three days, specify the annotation as follows: `@Conversational(maxAge="3 days")` Default value is `1 day`. | String | No
runAsStartUser | Specifies whether the continue and finish phases of an existing conversation are run as the user who started the conversation. Typically, the same user executes the start, continue, and finish methods of a conversation, so that changing the value of this attribute has no effect. However, if you set the `singlePrincipal` attribute to false, which allows users different from the user who initiated the conversation to execute the continue and finish phases of an existing conversation, then the `runAsStartUser` attribute specifies which user the methods are actually "run as": the user who initiated the conversation or the different user who executes subsequent phases of the conversation. Valid values are `true` and `false`. Default value is `true`, which means that the continue and finish phases are always run as the user who started the conversation. | boolean | No.
singlePrincipal | Specifies whether users other than the one who started a conversation are allowed to execute the continue and finish phases of the conversation. Typically, the same user executes all phases of a conversation. However, if you set this attribute to `false`, then other users can obtain the conversation ID of an existing conversation and use it to execute later phases of the conversation. Valid values are `true` and `false`. Default value is `true`, which means only the user who started the conversation can continue and finish it. | boolean | No

### Example

The following sample snippet shows how to specify that a JWS file implements a conversational Web Service. The maximum amount of time the conversation can be idle is ten minutes, and the maximum age of the conversation, regardless of activity, is one day. The continue and finish phases of the conversation can be executed by a user other than the one that started the conversation; if this happens, then the corresponding methods are run as the new user, not the original user.

>     package examples.webservices.conversation;

>     ...

>     @Conversational(maxIdleTime="10 minutes",
>                     maxAge="1 day",
>                     runAsStartUser=false,
>                     singlePrincipal=false )

>     public class ConversationalServiceImpl implements Serializable {

>     ...

## weblogic.jws.MessageBuffer

### Description

Target: Method

Specifies which public methods of a JWS are buffered.

When a client Web Service invokes a buffered operation of a different WebLogic Web Service, WebLogic Server (hosting the invoked Web Service) puts the invoke message on a JMS queue and the actual invoke is dealt with later on when the WebLogic Server delivers the message from the top of the JMS queue to the Web Service implementation. The client does not need to wait for a response, but rather, continues on with its execution. For this reason, buffered operations (without any additional asynchronous features) can only return `void` and must be marked with the `@Oneway` annotation. If you want to buffer an operation that returns a value, you must use asynchronous request-response from the invoking client Web Service. See Invoking a Web Service Using Asynchronous Request-Response for more information.

Buffering works only between two Web Services in which one invokes the buffered operations of the other.

Use the optional attributes of `@MessageBuffer` to specify the number of times the JMS queue attempts to invoke the buffered Web Service operation until it is invoked successfully, and the amount of time between attempts.

Use the optional class-level `@BufferQueue` annotation to specify the JMS queue to which the invoke messages are queued. If you do not specify this annotation, the messages are queued to the default Web Service queue, `weblogic.wsee.DefaultQueue`.

See Creating Buffered Web Services for detailed information and examples for using this annotation.

### Attributes

Table B-14 Attributes of the weblogic.jws.MessageBuffer JWS Annotation Tag

Name | Description | Data Type | Required?
--- | --- | --- | ---
retryCount | Specifies the number of times that the JMS queue on the invoked WebLogic Server instance attempts to deliver the invoking message to the Web Service implementation until the operation is successfully invoked. Default value is 3. | int | No
> retryDelay | Specifies the amount of time that elapses between message delivery retry attempts. The retry attempts are between the invoke message on the JMS queue and delivery of the message to the Web Service implementation. Valid values are a number and one of the following terms: `seconds` `minutes` `hours` `days` `years` For example, to specify a retry delay of two days, specify:
>     @MessageBuffer(retryDelay="2 days")
Default value is `5 seconds.` | String | No

### Example

The following example shows a code snippet from a JWS file in which the public operation `sayHelloNoReturn` is buffered and the JMS queue to which WebLogic Server queues the operation invocation is called `my.buffere.queue`. The WebLogic Server instance that hosts the invoked Web Service tries a maximum of 10 times to deliver the invoke message from the JMS queue to the Web Service implementation, waiting 10 seconds between each retry. Only the relevant Java code is shown in the following snippet:

>     package examples.webservices.buffered;

>     ...

>     @WebService(name="BufferedPortType",
>                 serviceName="BufferedService",
>                 targetNamespace="http://example.org")

>     @BufferQueue(name="my.buffer.queue")

>     public class BufferedImpl {

>     ...

>       @WebMethod()
>       @MessageBuffer(retryCount=10, retryDelay="10 seconds")
>       @Oneway()
>       public void sayHelloNoReturn(String message) {
>         System.out.println("sayHelloNoReturn: " + message);
>       }
>     }

## weblogic.jws.Policies

### Description

Target: Class, Method

Specifies an array of `@weblogic.jws.Policy` annotations.

Use this annotation if you want to attach more than one WS-Policy files to a class or method of a JWS file. If you want to attach just one policy file, you can use the `@weblogic.jws.Policy` on its own.

See Using Web Service Reliable Messaging and Configuring Message-Level Security (Digital Signatures and Encryption) for detailed information and examples of using this annotation.

This JWS annotation does not have any attributes.

### Example

>     @Policies({
>         @Policy(uri="policy:firstPolicy.xml"),
>         @Policy(uri="policy:secondPolicy.xml")
>       })

## weblogic.jws.Policy

### Description

Target: Class, Method

Specifies that a WS-Policy file, which contains information about digital signatures, encryption, or Web Service reliable messaging, should be applied to the request or response SOAP messages.

This annotation can be used on its own to apply a single WS-Policy file to a class or method. If you want to apply more than one WS-Policy file to a class or method, use the `@weblogic.jws.Policies` annotation to group them together.

If this annotation is specified at the class level, the indicated policy file or files are applied to every public operation of the Web Service. If the annotation is specified at the method level, then only the corresponding operation will have the policy file applied.

By default, WS-Policy files are applied to both the request (inbound) and response (outbound) SOAP messages. You can change this default behavior with the `direction` attribute.

By default, the specified WS-Policy file is attached to the generated and published WSDL file of the Web Service so that consumers can view all the policy requirements of the Web Service. Use the `attachToWsdl` attribute to change this default behavior.

See Using Web Service Reliable Messaging and Configuring Message-Level Security (Digital Signatures and Encryption) for detailed information and examples of using this annotation.

### Attributes

Table B-15 Attributes of the weblogic.jws.Policies JWS Annotation Tag

Name | Description | Data Type | Required?
--- | --- | --- | ---
> uri | Specifies the location from which to retrieve the WS-Policy file. Use the `http:` prefix to specify the URL of a policy file on the Web. Use the `policy`: prefix to specify that the policy file is packaged in the Web Service archive file or in a shareable J2EE library of WebLogic Server, as shown in the following example:
>     @Policy(uri="policy:MyPolicyFile.xml")
If you are going to publish the policy file in the Web Service archive, the policy XML file must be located in either the `META-INF/policies` or `WEB-INF/policies` directory of the EJB JAR file (for EJB implemented Web Services) or WAR file (for Java class implemented Web Services), respectively. For information on publishing the policy file in a library, see Creating Shared J2EE Libraries and Optional Packages. | String | Yes.
direction | Specifies when to apply the policy: on the inbound request SOAP message, the outbound response SOAP message, or both (default). Valid values for this attribute are: `Policy.Direction.both` `Policy.Direction.inbound` `Policy.Direction.outbound` The default value is `Policy.Direction.both`. | enum | No.
attachToWsdl | Specifies whether the WS-Policy file should be attached to the WSDL that describes the Web Service. Valid values are `true` and `false`. Default value is `false`. | boolean | No.

### Example

>       @Policy(uri="policy:myPolicy.xml",
>               attachToWsdl=true,
>               direction=Policy.Direction.outbound)

## weblogic.jws.ReliabilityBuffer

### Description

Target: Method

Use this annotation to configure reliable messaging properties for an operation of a reliable Web Service, such as the number of times WebLogic Server should attempt to deliver the message from the JMS queue to the Web Service implementation, and the amount of time that the server should wait in between retries.

Note: It is assumed when you specify this annotation in a JWS file that you have already enabled reliable messaging for the Web Service by also including a `@Policy` annotation that specifies a WS-Policy file that has Web Service reliable messaging policy assertions.

If you specify the `@ReliabilityBuffer` annotation, but do not enable reliable messaging with an associated WS-Policy file, then WebLogic Server ignores this annotation.

See Using Web Service Reliable Messaging for detailed information about enabling Web Services reliable messaging for your Web Service.

### Attributes

Table B-16 Attributes of the weblogic.jws.ReliabilityBuffer JWS Annotation Tag

Name | Description | Data Type | Required?
--- | --- | --- | ---
retryCount | Specifies the number of times that the JMS queue on the destination WebLogic Server instance attempts to deliver the message from a client that invokes the reliable operation to the Web Service implementation. Default value is 3. | int | No
> retryDelay | Specifies the amount of time that elapses between message delivery retry attempts. The retry attempts are between the client's request message on the JMS queue and delivery of the message to the Web Service implementation. Valid values are a number and one of the following terms: `seconds` `minutes` `hours` `days` `years` For example, to specify a retry delay of two days, specify:
>     @ReliabilityBuffer(retryDelay="2 days")
Default value is `5 seconds.` | String | No

### Example

The following sample snippet shows how to use the `@ReliabilityBuffer` annotation at the method-level to change the default retry count and delay of a reliable operation; only relevant Java code is shown:

>     package examples.webservices.reliable;

>     import javax.jws.WebMethod;
>     import javax.jws.WebService;
>     import javax.jws.Oneway;

>     ...

>     import weblogic.jws.ReliabilityBuffer;
>     import weblogic.jws.Policy;

>     @WebService(name="ReliableHelloWorldPortType",
>                   serviceName="ReliableHelloWorldService")

>     ...

>     @Policy(uri="ReliableHelloWorldPolicy.xml",
>               direction=Policy.Direction.inbound,
>               attachToWsdl=true)

>     public class ReliableHelloWorldImpl {

>       @WebMethod()
>       @Oneway()
>       @ReliabilityBuffer(retryCount=10, retryDelay="10 seconds")

>       public void helloWorld(String input) {
>         System.out.println(" Hello World " + input);

>       }
>     }

## weblogic.jws.ServiceClient

### Description

Target: Field

Specifies that the annotated variable in the JWS file is a JAX-RPC stub used to invoke another WebLogic Web Service when using the following features:

- Web Service reliable messaging
- asynchronous request-response
- conversations

You use the reliable messaging and asynchronous request-response features only between two Web Services; this means, for example, that you can invoke a reliable Web Service operation only from within another Web Service, not from a stand-alone client. In the case of reliable messaging, the feature works between any two application servers that implement the WS-ReliableMessaging 1.0 specification In the case of asynchronous request-response, the feature works only between two WebLogic Server instances.

You use the `@ServiceClient` annotation in the client Web Service to specify which variable is a JAX-RPC port type for the Web Service described by the `@ServiceClient` attributes. The Enterprise Application that contains the client Web Service must also include the JAX-RPC stubs of the Web Service you are invoking; you generate the stubs with the `clientgen` Ant task.

See Advanced JWS Programming: Implementing Asynchronous Features, for additional information and examples of using the `@ServiceClient` annotation.

### Attributes

Table B-17 Attributes of the weblogic.jws.ServiceClient JWS Annotation Tag

Name | Description | Data Type | Required?
--- | --- | --- | ---
serviceName | Specifies the name of the Web Service that you are invoking. Corresponds to the `name` attribute of the `<service>` element in the WSDL of the invoked Web Service. If you used a JWS file to implement the invoked Web Service, this attribute corresponds to the `serviceName` attribute of the `@WebService` JWS annotation in the invoked Web Service. | String | Yes
portName | Specifies the name of the port of the Web Service you are invoking. Corresponds to the `name` attribute of the `<port>` child element of the `<service>` element. If you used a JWS file to implement the invoked Web Service, this attribute corresponds to the `portName` attribute of the `@WLHttpTransport` JWS annotation in the invoked Web Service. If you do not specify this attribute, it is assumed that the `<service>` element in the WSDL contains only one `<port>` child element, which `@ServiceClient` uses. If there is more than one port, the client Web Service returns a runtime exception. | String | No.
wsdlLocation | Specifies the WSDL file that describes the Web Service you are invoking. If you do not specify this attribute, the client Web Service uses the WSDL file from which the `clientgen` Ant task created the JAX-RPC `Service` implementation of the Web Service to be invoked. | String | No.
endpointAddress | Specifies the endpoint address of the Web Service you are invoking. If you do not specify this attribute, the client Web Service uses the endpoint address specified in the WSDL file. | String | No.

### Example

The following JWS file excerpt shows how to use the `@ServiceClient` annotation in a client Web Service to annotate a field (`port`) with the JAX-RPC stubs of the Web Service being invoked (called `ReliableHelloWorldService` whose WSDL is at the URL `http://localhost:7001/ReliableHelloWorld/ReliableHelloWorld?WSDL`); only relevant parts of the example are shown:

>     package examples.webservices.reliable;

>     import javax.jws.WebService;

>     ...

>     import weblogic.jws.ServiceClient;

>     import examples.webservices.reliable.ReliableHelloWorldPortType;

>     @WebService(...

>     public class ReliableClientImpl

>     {

>       @ServiceClient(

>          wsdlLocation="http://localhost:7001/ReliableHelloWorld/ReliableHelloWorld?WSDL",
>          serviceName="ReliableHelloWorldService",
>          portName="ReliableHelloWorldServicePort")

>       private ReliableHelloWorldPortType port;

>       @WebMethod

>       public void callHelloWorld(String input, String serviceUrl)

>          throws RemoteException {

>         port.helloWorld(input);

>         System.out.println(" Invoked the ReliableHelloWorld.helloWorld operation reliably." );

>       }

>     }

## weblogic.jws.Transactional

### Description

Target: Class, Method

Specifies whether the annotated operation, or all the operations of the JWS file when the annotation is specified at the class-level, runs or run inside of a transaction. By default, the operations do not run inside of a transaction.

Note: The `@Transactional` annotation only makes sense within the context of an EJB-implemented Web Service. For this reason, you can specify this annotation only inside of a JWS file that explicitly implements `javax.ejb.SessionBean`. See Transaction Design and Management Options in the Programming WebLogic Enterprise JavaBeans guide for additional information about stateless session EJBs that run inside of a transaction. See Should You Implement a Stateless Session EJB? for information about explicitly implementing an EJB in a JWS file.

### Attributes

Table B-18 Attributes of the weblogic.jws.Transactional JWS Annotation Tag

Name | Description | Data Type | Required?
--- | --- | --- | ---
value | Specifies whether the operation (when used at the method level) or all the operations of the Web Service (when specified at the class level) run inside of a transaction. Valid values are `true` and `false`. Default value is `false`. | boolean | No.

### Example

The following sample snippet shows how to use the `@Transactional` annotation to specify that an operation of a Web Service executes as part of a transaction; only relevant parts of the JWS file are shown:

>     package examples.webservices.transactional;

>     import javax.ejb.SessionBean;
>     import javax.ejb.SessionContext;

>     import javax.jws.WebService;

>     import weblogic.jws.Transactional;

>     import weblogic.ejbgen.Session;

>     @Session(
>       ejbName="TransactionEJB",
>       serviceEndpoint="examples.webservices.transactional.TransactionImplPortType")

>     @WebService(name="TransactionPortType", serviceName="TransactionService",
>                 targetNamespace="http://example.org")

>     ...

>     public class TransactionImpl implements SessionBean {

>       @Transactional(value=true)

>       public String sayHello(String message) {
>         System.out.println("sayHello:" + message);
>         return "Here is the message: '" + message + "'";
>       }

>       // Standard EJB methods.  Typically there's no need to override the methods.

>       public void ejbCreate() {}
>       ...

>     }

## weblogic.jws.WLHttpTransport

### Description

Target: Class

Specifies the context path and service URI sections of the URL used to invoke the Web Service over the HTTP transport, as well as the name of the port in the generated WSDL.

You can specify this annotation only once in a JWS file. Additionally, if you specify this annotation, you cannot specify any of the other transport annotations (`@WLHttpsTransport` or `@WLJmsTransport`).

### Attributes

Table B-19 Attributes of the weblogic.jws.WLHttpTransport JWS Annotation Tag

Name | Description | Data Type | Required?
--- | --- | --- | ---
> contextPath | Context path of the Web Service. You use this value in the URL that invokes the Web Service. For example, assume you set the context path for a Web Service to `financial`; a possible URL for the WSDL of the deployed WebLogic Web Service is as follows:
>     http://hostname:7001/financial/GetQuote?WSDL
The default value of this attribute is the name of the JWS file, without its extension. For example, if the name of the JWS file is `HelloWorldImpl.java`, then the default value of its contextPath is `HelloWorldImpl`. | String | No.
> serviceUri | Web Service URI portion of the URL. You use this value in the URL that invokes the Web Service. For example, assume you set this attribute to `GetQuote`; a possible URL for the deployed WSDL of the service is as follows:
>     http://hostname:7001/financial/GetQuote?WSDL
The default value of this attribute is the name of the JWS file, without its extension. For example, if the name of the JWS file is `HelloWorldImpl.java`, then the default value of its serviceUri is `HelloWorldImpl`. | String | No.
portName | The name of the port in the generated WSDL. This attribute maps to the `name` attribute of the `<port>` element in the WSDL. The default value of this attribute is based on the `@javax.jws.WebService` annotation of the JWS file. In particular, the default `portName` is the value of the `name` attribute of `@WebService` annotation, plus the actual text `SoapPort`. For example, if `@WebService.name` is set to `MyService`, then the default portName is `MyServiceSoapPort`. | String | No.

### Example

>     @WLHttpTransport(contextPath="complex",
>                      serviceUri="ComplexService",
>                      portName="ComplexServicePort")

## weblogic.jws.WLHttpsTransport

### Description

Target: Class

Specifies the context path and service URI sections of the URL used to invoke the Web Service over the HTTPS transport, as well as the name of the port in the generated WSDL.

You can specify this annotation only once in a JWS file. Additionally, if you specify this annotation, you cannot specify any of the other transport annotations (`@WLHttpTransport` or `@WLJmsTransport`).

### Attributes

Table B-20 Attributes of the weblogic.jws.WLHttpsTransport JWS Annotation Tag

Name | Description | Data Type | Required?
--- | --- | --- | ---
> contextPath | Context path of the Web Service. You use this value in the URL that invokes the Web Service. For example, assume you set the context path for a Web Service to `financial`; a possible URL for the WSDL of the deployed WebLogic Web Service is as follows:
>     https://hostname:7001/financial/GetQuote?WSDL
The default value of this attribute is the name of the JWS file, without its extension. For example, if the name of the JWS file is `HelloWorldImpl.java`, then the default value of its contextPath is `HelloWorldImpl`. | String | No.
> serviceUri | Web Service URI portion of the URL. You use this value in the URL that invokes the Web Service. For example, assume you set this attribute to `GetQuote`; a possible URL for the deployed WSDL of the service is as follows:
>     https://hostname:7001/financial/GetQuote?WSDL
The default value of this attribute is the name of the JWS file, without its extension. For example, if the name of the JWS file is `HelloWorldImpl.java`, then the default value of its serviceUri is `HelloWorldImpl`. | String | No.
portName | The name of the port in the generated WSDL. This attribute maps to the `name` attribute of the `<port>` element in the WSDL. The default value of this attribute is based on the `@javax.jws.WebService` annotation of the JWS file. In particular, the default `portName` is the value of the `name` attribute of `@WebService` annotation, plus the actual text `SoapPort`. For example, if `@WebService.name` is set to `MyService`, then the default portName is `MyServiceSoapPort`. | String | No.

### Example

>     @WLHttpsTransport(portName="helloSecurePort",
>                      contextPath="secure",
>                      serviceUri="SimpleSecureBean")

## weblogic.jws.WLJmsTransport

### Description

Target: Class

Specifies the context path and service URI sections of the URL used to invoke the Web Service over the JMS transport, as well as the name of the port in the generated WSDL. You also use this annotation to specify the JMS queue to which WebLogic Server queues the SOAP request messages from invokes of the operations.

You can specify this annotation only once in a JWS file. Additionally, if you specify this annotation, you cannot specify any of the other transport annotations (`@WLHttpTransport` or `@WLHttpsTransport`).

### Attributes

Table B-21 Attributes of the weblogic.jws.WLJmsTransport JWS Annotation Tag

Name | Description | Data Type | Required?
--- | --- | --- | ---
contextPath | Context root of the Web Service. You use this value in the URL that invokes the Web Service. | String | No.
serviceUri | Web Service URI portion of the URL used by client applications to invoke the Web Service. | String | No.
queue | The JNDI name of the JMS queue that you have configured for the JMS transport. See Using JMS Transport as the Connection Protocol for details about using JMS transport. The default value of this attribute, if you do not specify it, is `weblogic.wsee.DefaultQueue`. You must still create this JMS queue in the WebLogic Server instance to which you deploy your Web Service. | String | No.
portName | The name of the port in the generated WSDL. This attribute maps to the `name` attribute of the `<port>` element in the WSDL. If you do not specify this attribute, the `jwsc` generates a default name based on the name of the class that implements the Web Service. | String | No.

### Example

The following example shows how to specify that the JWS file implements a Web Service that is invoked using the JMS transport. The JMS queue to which WebLogic Server queues SOAP message requests from invokes of the service operations is `JMSTransportQueue`; it is assumed that this JMS queue has already been configured for WebLogic Server.

>     WLJmsTransport(contextPath="transports",
>                     serviceUri="JMSTransport",
>                     queue="JMSTransportQueue",
>                     portName="JMSTransportServicePort")

## weblogic.jws.WSDL

### Description

Target: Class

Specifies whether to expose the WSDL of a deployed WebLogic Web Service.

By default, the WSDL is exposed at the following URL:

>     http://[host]:[port]/[contextPath]/[serviceUri]?WSDL

where:

- host refers to the computer on which WebLogic Server is running.
- port refers to the port number on which WebLogic Server is listening (default value is `7001`).
- `contextPath` and `serviceUri` refer to the value of the `contextPath` and `serviceUri` attributes, respectively, of the `@WLHttpTransport` JWS annotation of the JWS file that implements your Web Service.

For example, assume you used the following `@WLHttpTransport` annotation:

>     @WLHttpTransport(portName="helloPort",
>                      contextPath="hello",
>                      serviceUri="SimpleImpl")

The URL to get view the WSDL of the Web Service, assuming the service is running on a host called `ariel` at the default port number, is:

>     http://ariel:7001/hello/SimpleImpl?WSDL

### Attributes

Table B-22 Attributes of the weblogic.jws.WSDL JWS Annotation Tag

Name | Description | Data Type | Required?
--- | --- | --- | ---
exposed | Specifies whether to expose the WSDL of a deployed Web Service. Valid values are `true` and `false`. Default value is `true`, which means that by default the WSDL is exposed. | boolean | No.

### Example

The following use of the `@WSDL` annotation shows how to specify that the WSDL of a deployed Web Service not be exposed; only relevant Java code is shown:

>     package examples.webservices;

>     import....

>     @WebService(name="WsdlAnnotationPortType",
>                 serviceName="WsdlAnnotationService",
>                 targetNamespace="http://example.org")

>     @WSDL(exposed=false)

>     public class WsdlAnnotationImpl {

>     ...

>     }

## weblogic.jws.security.RolesAllowed

### Description

Target: Class, Method

JWS annotation used to enable basic authentication for a Web Service. In particular, it specifies an array of `@SecurityRole` JWS annotations that describe the list of roles that are allowed to invoke the Web Service. A user that is mapped to an unspecified role, or is not mapped to any role at all, would not be allowed to invoke the Web Service.

If you use this annotation at the class-level, then the specified roles are allowed to invoke all operations of the Web Service. To specify roles for just a specific set of operations, specify the annotation at the operation-level.

This JWS annotation does not have any attributes.

### Example

>     package examples.webservices.security_roles;

>     ...

>     import weblogic.jws.security.RolesAllowed;
>     import weblogic.jws.security.SecurityRole;

>     @WebService(name="SecurityRolesPortType",
>                 serviceName="SecurityRolesService",
>                 targetNamespace="http://example.org")

>     @RolesAllowed (  {
>         @SecurityRole (role="manager",
>                        mapToPrincipals={ "juliet","amanda" }),
>         @SecurityRole (role="vp")
>     } )

>     public class SecurityRolesImpl {

>     ...

In the example, only the roles `manager` and `vp` are allowed to invoke the Web Service. Within the context of the Web Service, the users `juliet` and `amanda` are assigned the role `manager`. The role `vp`, however, does not include a `mapToPrincipals` attribute, which implies that users have been mapped to this role externally. It is assumed that you have already added the two users (`juliet` and `amanda`) to the WebLogic Server security realm.

## weblogic.jws.security.RolesReferenced

### Description

Target: Class

JWS annotation used to specify the list of role names that reference actual roles that are allowed to invoke the Web Service. In particular, it specifies an array of `@SecurityRoleRef` JWS annotations, each of which describe a link between a referenced role name and an actual role defined by a `@SecurityRole` annotation.

This JWS annotation does not have any attributes.

### Example

>     package examples.webservices.security_roles;

>     ...

>     import weblogic.jws.security.RolesAllowed;
>     import weblogic.jws.security.SecurityRole;
>     import weblogic.jws.security.RolesReferenced;
>     import weblogic.jws.security.SecurityRoleRef;

>     @WebService(name="SecurityRolesPortType",
>                 serviceName="SecurityRolesService",
>                 targetNamespace="http://example.org")

>     @RolesAllowed (  {
>         @SecurityRole (role="manager",
>                        mapToPrincipals={ "juliet","amanda" }),
>         @SecurityRole (role="vp")
>     } )

>     @RolesReferenced (
>         @SecurityRoleRef (role="mgr", link="manager")
>     )

>     public class SecurityRolesImpl {

>     ...

In the example, the role `mgr` is linked to the role `manager`, which is allowed to invoke the Web Service. This means that any user who is assigned to the role of `mgr` is also allowed to invoke the Web Service.

## weblogic.jws.security.RunAs

### Description

Target: Class

Specifies the role and user identity which actually runs the Web Service in WebLogic Server.

For example, assume that the `@RunAs` annotation specifies the `roleA` role and `userA` principal. This means that even if the Web Service is invoked by `userB` (mapped to `roleB`), the relevant operation is actually executed internall as `userA`.

### Attributes

Table B-23 Attributes of the weblogic.jws.security.RunAs JWS Annotation

Name | Description | Data Type | Required?
--- | --- | --- | ---
role | Specifies the role which the Web Service should be run as. | String | Yes.
mapToPrincipal | Specifies the principal user that maps to the role. It is assumed that you have already configured the specified principal (user) as a valid WebLogic Server user, typically using the Administration Console. See Create Users for details. | String | Yes.

### Example

>     package examples.webservices.security_roles;

>     import weblogic.jws.security.RunAs;

>     ...

>     @WebService(name="SecurityRunAsPortType",
>                 serviceName="SecurityRunAsService",
>                 targetNamespace="http://example.org")

>     @RunAs (role="manager", mapToPrincipal="juliet")

>     public class SecurityRunAsImpl {

>     ...

The example shows how to specify that the Web Service is always run as user `juliet`, mapped to the role `manager`, regardless of who actually invoked the Web Service.

## weblogic.jws.security.SecurityRole

### Description

Target: Class, Method

Specifies the name of a role that is allowed to invoke the Web Service. This annotation is always specified in the JWS file as a member of a `@RolesAllowed` array.

When a client application invokes the secured Web Service, it specifies a user and password as part of its basic authentication. It is assumed that an administrator has already configured the user as a valid WebLogic Server user using the Administration Console; for details see Create Users.

The user that is going to invoke the Web Service must also be mapped to the relevant role. You can perform this task in one of the following two ways:

- Use the Administration Console to map the user to the role. In this case, you do not specify the `mapToPrincipals` attribute of the `@SecurityRole` annotation. For details, see Add Users to Roles.
- Map the user to a role only within the context of the Web Service by using the `mapToPrincipals` attribute to specify one or more users.

To specify that multiple roles are allowed to invoke the Web Service, include multiple `@SecurityRole` annotations within the `@RolesAllowed` annotation.

### Attributes

Table B-24 Attributes of the weblogic.jws.security.SecurityRole JWS Annotation

Name | Description | Data Type | Required?
--- | --- | --- | ---
role | The name of the role that is allowed to invoke the Web Service. | String | Yes
mapToPrincipals | An array of user names that map to the role. If you do not specify this attribute, it is assumed that you have externally defined the mapping between users and the role, typically using the Administration Console. | String[] | No

### Example

>     package examples.webservices.security_roles;

>     ...

>     import weblogic.jws.security.RolesAllowed;
>     import weblogic.jws.security.SecurityRole;

>     @WebService(name="SecurityRolesPortType",
>                 serviceName="SecurityRolesService",
>                 targetNamespace="http://example.org")

>     @RolesAllowed (  {
>         @SecurityRole (role="manager",
>                        mapToPrincipals={ "juliet","amanda" }),
>         @SecurityRole (role="vp")
>     } )

>     public class SecurityRolesImpl {

>     ...

In the example, only the roles `manager` and `vp` are allowed to invoke the Web Service. Within the context of the Web Service, the users `juliet` and `amanda` are assigned the role `manager`. The role `vp`, however, does not include a `mapToPrincipals` attribute, which implies that users have been mapped to this role externally. It is assumed that you have already added the two users (`juliet` and `amanda`) to the WebLogic Server security realm.

## weblogic.jws.security.SecurityRoleRef

### Description

Target: Class

Specifies a role name reference that links to an already-specified role that is allowed to invoke the Web Service.

Users that are mapped to the role reference can invoke the Web Service as long as the referenced role is specified in the `@RolesAllowed` annotation of the Web Service.

### Attributes

Table B-25 Attributes of the weblogic.jws.security.SecurityRoleRef JWS Annotation

Name | Description | Data Type | Required?
--- | --- | --- | ---
role | Name of the role reference. | String | Yes.
link | Name of the already-specified role that is allowed to invoke the Web Service. The value of this attribute corresponds to the value of the `role` attribute of a `@SecurityRole annotation` specified in the same JWS file. | String | Yes.

### Example

>     package examples.webservices.security_roles;

>     ...

>     import weblogic.jws.security.RolesAllowed;
>     import weblogic.jws.security.SecurityRole;
>     import weblogic.jws.security.RolesReferenced;
>     import weblogic.jws.security.SecurityRoleRef;

>     @WebService(name="SecurityRolesPortType",
>                 serviceName="SecurityRolesService",
>                 targetNamespace="http://example.org")

>     @RolesAllowed (  {
>         @SecurityRole (role="manager",
>                        mapToPrincipals={ "juliet","amanda" }),
>         @SecurityRole (role="vp")
>     } )

>     @RolesReferenced (
>         @SecurityRoleRef (role="mgr", link="manager")
>     )

>     public class SecurityRolesImpl {

>     ...

In the example, the role `mgr` is linked to the role `manager`, which is allowed to invoke the Web Service. This means that any user who is assigned to the role of `mgr` is also allowed to invoke the Web Service.

## weblogic.jws.security.UserDataConstraint

### Description

Target: Class

Specifies whether the client is required to use the HTTPS transport when invoking the Web Service.

WebLogic Server establishes a Secure Sockets Layer (SSL) connection between the client and Web Service if the `transport` attribute of this annotation is set to either `Transport.INTEGRAL` or `Transport.CONFIDENTIAL` in the JWS file that implements the Web Service.

If you specify this annotation in your JWS file, you must also specify the `weblogic.jws.WLHttpsTransport` annotation (or the `<WLHttpsTransport>` element of the `jwsc` Ant task) to ensure that an HTTPS binding is generated in the WSDL file by the `jwsc` Ant task.

### Attributes

Table B-26 Attributes of the weblogic.jws.security.UserDataConstraint JWS Annotation

Name | Description | Data Type | Required?
--- | --- | --- | ---
transport | Specifies whether the client is required to use the HTTPS transport when invoking the Web Service. Valid values are: `Transport.NONE`—Specifies that the Web Service does not require any transport guarantees. `Transport.INTEGRAL`—Specifies that the Web Service requires that the data be sent between the client and Web Service in such a way that it cannot be changed in transit. `Transport.CONFIDENTIAL`—Specifies that the Web Service requires that data be transmitted so as to prevent other entities from observing the contents of the transmission. Default value is `Transport.NONE`. | enum | No

### Example

>     package examples.webservices.security_https;

>     import weblogic.jws.security.UserDataConstraint;

>     ...

>     @WebService(name="SecurityHttpsPortType",
>                 serviceName="SecurityHttpsService",
>                 targetNamespace="http://example.org")

>     @UserDataConstraint(
>                transport=UserDataConstraint.Transport.CONFIDENTIAL)

>     public class SecurityHttpsImpl {

>     ...

## weblogic.jws.security.WssConfiguration

### Description

Target: Class

Specifies the name of the Web Service security configuration you want the Web Service to use. If you do not specify this annotation in your JWS file, the Web Service is associated with the default security configuration (called `default_wss`) if it exists in your domain.

The `@WssConfiguration` annotation only makes sense if your Web Service is configured for message-level security (encryption and digital signatures). The security configuration, associated to the Web Service using this annotation, specifies information such as whether to use an X.509 certificate for identity, whether to use password digests, the keystore to be used for encryption and digital signatures, and so on.

WebLogic Web Services are not required to be associated with a security configuration; if the default behavior of the Web Services security runtime is adequate then no additional configuration is needed. If, however, a Web Service requires different behavior from the default (such as using an X.509 certificate for identity, rather than the default username/password token), then the Web Service must be associated with a security configuration.

Before you can successfully invoke a Web Service that specifies a security configuration, you must use the Administration Console to create it. For details, see Create a Web Services security configuration. For general information about message-level security, see Configuring Message-Level Security (Digital Signatures and Encryption).

### Attributes

Table B-27 Attributes of the weblogic.jws.security.WssConfiguration JWS Annotation Tag

Name | Description | Data Type | Required?
--- | --- | --- | ---
value | Specifies the name of the Web Service security configuration that is associated with this Web Service. The default configuration is called `default_wss`. You must create the security configuration (even the default one) using the Administration Console before you can successfully invoke the Web Service. | String | Yes.

### Example

The following example shows how to specify that a Web Service is associated with the `my_security_configuration` security configuration; only the relevant Java code is shown:

>     package examples.webservices.wss_configuration;

>     import javax.jws.WebService;
>     ...

>     import weblogic.jws.security.WssConfiguration;

>     @WebService(...
>     ...

>     @WssConfiguration(value="my_security_configuration")

>     public class WssConfigurationImpl {

>     ...

## weblogic.jws.security.SecurityRoles (deprecated)

### Description

Target: Class, Method

Note: The `@weblogic.security.jws.SecurityRoles` JWS annotation is deprecated beginning in WebLogic Server 9.0.

Specifies the roles that are allowed to access the operations of the Web Service.

If you specify this annotation at the class level, then the specified roles apply to all public operations of the Web Service. You can also specify a list of roles at the method level if you want to associate different roles to different operations of the same Web Service.

Note: The `@SecurityRoles` annotation is supported only within the context of an EJB-implemented Web Service. For this reason, you can specify this annotation only inside of a JWS file that explicitly implements `javax.ejb.SessionBean`. See Securing Enterprise JavaBeans (EJBs) for conceptual information about what it means to secure access to an EJB. See Should You Implement a Stateless Session EJB? for information about explicitly implementing an EJB in a JWS file.

### Attributes

Table B-28 Attributes of the weblogic.jws.security.SecurityRoles JWS Annotation

Name | Description | Data Type | Required?
--- | --- | --- | ---
rolesAllowed | Specifies the list of roles that are allowed to access the Web Service. This annotation is the equivalent of the `<method-permission>` element in the `ejb-jar.xml` deployment descriptor of the stateless session EJB that implements the Web Service. | Array of String | No.
rolesReferenced | Specifies a list of roles referenced by the Web Service. The Web Service may access other resources using the credentials of the listed roles. This annotation is the equivalent of the `<security-role-ref>` element in the `ejb-jar.xml` deployment descriptor of the stateless session EJB that implements the Web Service. | Array of String | No.

### Example

The following example shows how to specify, at the class-level, that the Web Service can be invoked only by the `Admin` role; only relevant parts of the example are shown:

>     package examples.webservices.security_roles;

>     import javax.ejb.SessionBean;
>     import javax.ejb.SessionContext;

>     import weblogic.ejbgen.Session;

>     import javax.jws.WebService;

>     ...

>     import weblogic.jws.security.SecurityRoles;

>     @Session(ejbName="SecurityRolesEJB")

>     @WebService(...

>     // Specifies the roles who can invoke the entire Web Service

>     @SecurityRoles(rolesAllowed="Admnin")

>     public class SecurityRolesImpl implements SessionBean {

>     ...

## weblogic.jws.security.SecurityIdentity (deprecated)

### Description

Target: Class

Note: The `@weblogic.security.jws.SecurityIdentity` JWS annotation is deprecated beginning in WebLogic Server 9.1.

Specifies the identity assumed by the Web Service when it is invoked.

Unless otherwise specified, a Web Service assumes the identity of the authenticated invoker. This annotation allows the developer to override this behavior so that the Web Service instead executes as a particular role. The role must map to a user or group in the WebLogic Server security realm.

Note: The `@SecurityIdentity` annotation only makes sense within the context of an EJB-implemented Web Service. For this reason, you can specify this annotation only inside of a JWS file that explicitly implements `javax.ejb.SessionBean`. See Securing Enterprise JavaBeans (EJBs) for conceptual information about what it means to secure access to an EJB. See Should You Implement a Stateless Session EJB? for information about explicitly implementing an EJB in a JWS file.

### Attributes

Table B-29 Attributes of the weblogic.jws.security.SecurityIdentity JWS Annotation

Name | Description | Data Type | Required?
--- | --- | --- | ---
value | Specifies the role which the Web Service assumes when it is invoked. The role must map to a user or group in the WebLogic Server security realm. | String | Yes.

### Example

The following example shows how to specify that the Web Service, when invoked, runs as the `Admin` role:

>     package examples.webservices.security_roles;

>     import javax.ejb.SessionBean;
>     import javax.ejb.SessionContext;

>     import weblogic.ejbgen.Session;

>     import javax.jws.WebService;

>     ...

>     import weblogic.jws.security.SecurityIdentity;

>     @Session(ejbName="SecurityRolesEJB")

>     @WebService(...

>     // Specifies that the Web Service runs as the Admin role

>     @SecurityIdentity( value="Admin")

>     public class SecurityRolesImpl implements SessionBean {

>     ...