A Annotation Reference

This appendix describes the asynchronous Web service and policy annotations that are used by Oracle Infrastructure Web services.

Overview of Annotations
@AddressingPolicy Annotation
@AsyncWebService Annotation
@AsyncWebServiceQueue Annotation
@AsyncWebServiceResponseQueue Annotation
@CallbackAddressingPolicy Annotation
@CallbackMethod Annotation
@CallbackManagementPolicy Annotation
@CallbackMtomPolicy Annotation
@CallbackProperties Annotation
@CallbackProperty Annotation
@CallbackSecurityPolicy Annotation
@ManagementPolicy Annotation
@MtomPolicy Annotation
@PortableWebService Annotation
@ReliabilityPolicy Annotation
@ResponseWebService Annotation
@SecurityPolicies Annotation
@SecurityPolicy Annotation

Overview of Annotations

The WebLogic Web Services programming model uses the JDK 5.0 metadata annotations at http://java.sun.com/j2se/1.5.0/docs/relnotes/features.html#annotations feature (specified by JSR-175 at http://www.jcp.org/en/jsr/detail?id=175). In this programming model, you create an annotated Java file to specify the shape and characteristics of the Web service.

Table A-1 summarizes the asynchronous Web service and policy annotations described in this appendix.

For more information about the annotations available, see Oracle Fusion Middleware Java API Reference for Oracle Web Services. For more information about the predefined policies, see "Predefined Polices" in Oracle Fusion Middleware Security and Administrator's Guide for Web Services.

Table A-1 Oracle Infrastructure Web Service Annotations

Annotation	Description
@AddressingPolicy Annotation	Attaches a WS-Addressing policy to the Web service.
@AsyncWebService Annotation	Declares a Web service to be an asynchronous Web service.
@AsyncWebServiceQueue Annotation	Specifies the details of a queue used for saving the request for later processing.
@AsyncWebServiceResponseQueue Annotation	Defines the queue used to save the response for later processing
@CallbackAddressingPolicy Annotation	Not used in this release.
@CallbackMethod Annotation	Enables you to customize the names of the WSDL entities for the corresponding operation in the callback portType and set whether a method is synchronous or asynchronous.
@CallbackManagementPolicy Annotation	Attaches a management policy to the callback client of the asynchronous Web service that will connect to the callback service.
@CallbackMtomPolicy Annotation	Attaches an MTOM policy to the callback client of the asynchronous Web service that will connect to the callback service.
@CallbackProperties Annotation	Enables you to specify properties that are required in the message context when calling the callback service.
@CallbackProperty Annotation	Enables you to specify properties that are required in the message context when calling the callback service.
@CallbackSecurityPolicy Annotation	Attaches one or more security polices to the callback client of the asynchronous Web service that will connect to the callback service.
@ManagementPolicy Annotation	Attaches a management policy to the Web service.
@MtomPolicy Annotation	Attaches an MTOM policy to the Web service.
@PortableWebService Annotation	Specifies, at the class level, that the JWS file implements an Oracle Infrastructure Web service.
@ReliabilityPolicy Annotation	Attaches a reliable messaging policy to the Web service.
@ResponseWebService Annotation	Customizes the response Web service port information.
@SecurityPolicies Annotation	Attaches a list of security policies to the Web service.
@SecurityPolicy Annotation	Attaches a security policy to the Web service.

@AddressingPolicy Annotation

The oracle.webservices.annotations.AddressingPolicy annotation attaches a WS-Addressing policy to the Web service.

For example:

@AddressingPolicy(
       value="oracle/wsaddr_policy",         enabled = "true")

The following table defines the attributes that can be passed to the oracle.webservices.annotations.AddressingPolicy annotation.

Table A-2 Attributes for oracle.webservices.annotations.AddressingPolicy Annotation

Attribute	Description	Default
value	Specifies the location from which to retrieve the WS-Policy file. Use the `http:` prefix to specify the URL of a WS-Policy file on the Web. Use the `policy:` prefix to specify that the WS-Policy file is packaged in the policy repository.	""
enabled	Boolean value that specifies whether or not the policy is enabled.	true

@AsyncWebService Annotation

The oracle.webservices.annotations.async.AsyncWebService annotation declares a Web service to be an asynchronous Web service.

By default, all operations associated with the Web service are asynchronous. To mark a specific method as synchronous, see @CallbackMethod Annotation. If you want to be able to call a method both synchronously and asynchronously, you will have to create two methods and annotate them accordingly.

For example:

@PortableWebService
@AsyncWebService
public class HelloService {
   public String hello(String name) {
      return "Hi " + name;
   }
}

@AsyncWebServiceQueue Annotation

The oracle.webservices.annotations.async.AsyncWebServiceQueue annotation defines the queue used to save the request for later processing. For more information, see Configuring the Request and Response Queues.

For example:

@AsyncWebServiceQueue (
    connectionFactory = "weblogic.jms.XAConnectionFactory",
    queue = "oracle.j2ee.ws.server.async.NonDefaultRequestQueue",
    enableTransaction = true
)

The following table defines the attributes that can be passed to the oracle.webservices.annotations.async.AsyncWebServiceQueue annotation.

Table A-3 Attributes for oracle.webservices.annotations.async.AsyncWebService Queue Annotation

Attribute	Description	Default
connectionFactory	Name of the JMS Queue Connection Factory for the request queue.	weblogic.jmx.XAConnectionFactory
queue	Name of the JMS queue used to store asynchronous requests.	oracle.j2ee.ws.server.async.DefaultRequestQueue
enableTransaction	Flag that specifies whether the MDB should process the asynchronous request as a transaction. Note: A user transaction is maintained separately from the MDB transaction so that they can be committed or rolled back independently.	false

Attribute

Description

Default

connectionFactory

Name of the JMS Queue Connection Factory for the request queue.

weblogic.jmx.XAConnectionFactory

queue

Name of the JMS queue used to store asynchronous requests.

oracle.j2ee.ws.server.async.DefaultRequestQueue

enableTransaction

Flag that specifies whether the MDB should process the asynchronous request as a transaction.

Note: A user transaction is maintained separately from the MDB transaction so that they can be committed or rolled back independently.

false

@AsyncWebServiceResponseQueue Annotation

The oracle.webservices.annotations.async.AsyncWebServiceResponseQueue annotation defines the queue used to save the response for later processing.

For example:

@AsyncWebServiceQueue (
    connectionFactory = "weblogic.jms.XAConnectionFactory",
    queue = "oracle.j2ee.ws.server.async.NonDefaultResponseQueue",
    enableTransaction = true
)

The following table defines the attributes that can be passed to the oracle.webservices.annotations.async.AsyncWebServiceResponseQueue annotation.

Table A-4 Attributes for oracle.webservices.annotations.async.AsyncWebService ResponseQueue Annotation

Attribute	Description	Default
enabled	Flag that specifies whether the response queue is enabled. If enabled, the request MDB processes the request and stores the response in the response queue. If disabled, the response processing is performed by the request MDB.	true
connectionFactory	Name of the JMS Queue Connection Factory for the response queue.	weblogic.jmx.XAConnectionFactory
queue	Name of the JMS queue used to asynchronous response. The response MDB retrieves messages from the response queue and forwards them to the callback service.	oracle.j2ee.ws.server.async.DefaultResponseQueue
enableTransaction	Flag that specifies whether the MDB should process the asynchronous response as a transaction. Note: A user transaction is maintained separately from the MDB transaction so that they can be committed or rolled back independently.	false

@CallbackAddressingPolicy Annotation

The oracle.webservices.annotations.async.CallbackAddressingPolicy annotation is not used in this release as WS-Addressing is used by default to correlate the response message with the callback service. In the future, it may be used to advertise the policy to the callback exchange.

@CallbackMethod Annotation

The oracle.webservices.annotations.async.CallbackMethod annotation enables you to customize the names of the WSDL entities for the corresponding operation in the callback portType and set whether a method is synchronous or asynchronous. This annotation is similar to the javax.jws.WebMethod annotation.

For example:

@CallbackMethod(exclude=true)

The following table defines the attributes that can be passed to the oracle.webservices.annotations.async.CallbackMethod annotation.

Table A-5 Attributes for oracle.webservices.annotations.async.CallbackMethod Annotation

Attribute	Description	Default
name	Name of the callback method in the callback portType that corresponds to the annotated method. This annotation is ignored at runtime; it is only used when generating a callback interface from a POJO implementation class.	"onResult" + <name of the annotated method>
operationName	Name of the wsdl:operation for this method in the callback portType.	"onResult" + <name of the annotated method>
action	Name of the action for this method in the callback portType. For SOAP bindings, this value determines the value of the SOAP action.	Name of the operation
serviceRefName	Name used for the service reference used to send the response message. This value must be unique for the deployed archive and is used to define: <service-ref-name> and <display-name> elements under the <service-ref> element in the standard deployment descriptor. Name attribute in the <service-ref-mapping> element in the proprietary deployment descriptor	<name of the annotated class> + "ResponseWebService.SERVICE_REF_NAME_SUFFIX"
exclude	Flag that specifies whether the method is asynchronous. Setting this value to true specifies that the method is synchronous; in this case, all other attribute settings are ignored.	false

@CallbackManagementPolicy Annotation

The oracle.webservices.annotations.async.CallbackManagementPolicy annotation attaches a management policy to the callback client of the asynchronous Web service that will connect to the callback service. By default, no management policy is attached.

For example:

@CallbackManagementPolicy("oracle/log_policy")

The following table defines the attributes that can be passed to the oracle.webservices.annotations.async.CallbackManagementPolicy annotation.

Table A-6 Attributes for oracle.webservices.annotations.async.CallbackManagementPolicy Annotation

Attribute	Description	Default
value	String value that specifies the URI of a management policy.	""
enabled	Flag that specifies whether the specified security policies are enabled for the callback client.	true

@CallbackMtomPolicy Annotation

The oracle.webservices.annotations.async.CallbackMtomPolicy annotation attaches an MTOM policy to the callback client of the asynchronous Web service that will connect to the callback service. By default, no MTOM policy is attached.

For example:

@CallbackMtomPolicy("oracle/wsmtom_policy")

The following table defines the attributes that can be passed to the oracle.webservices.annotations.async.CallbackMtomPolicy annotation.

Table A-7 Attributes for oracle.webservices.annotations.async.CallbackMtomPolicy Annotation

Attribute	Description	Default
value	String value that specifies the URI of an MTOM policy.	""
enabled	Flag that specifies whether the specified security policies are enabled for the callback client.	true

@CallbackProperties Annotation

The oracle.webservices.annotations.async.CallbackProperties annotation enables you to specify a set of properties that are required in the message context when calling the callback service.

For example:

@CallbackProperties(     {
   @Property(
       name = SecurityConstants.ClientConstants.WSS_CSF_KEY,         value = "basic.credentials")
   } )

The following table defines the attributes that can be passed to the oracle.webservices.annotations.async.CallbackProperties annotation.

Table A-8 Attributes for oracle.webservices.annotations.async.CallbackProperties Annotation

Attribute	Description	Default
value	Array of oracle.webservices.annotations.Property type values. Each property specifies a key-value pair.	""

@CallbackProperty Annotation

The oracle.webservices.annotations.async.CallbackProperty annotation enables you to specify a single property that is required in the message context when calling the callback service.

For example:

@Property(
       name = SecurityConstants.ClientConstants.WSS_CSF_KEY,         value = "basic.credentials")

The following table defines the attributes that can be passed to the oracle.webservices.annotations.async.CallbackProperty annotation.

Table A-9 Attributes for oracle.webservices.annotations.async.CallbackProperty Annotation

Attribute	Description	Default
key	String type value that specifies the message context property name.	""
value	String type value that specifies the message context property value.	""

@CallbackSecurityPolicy Annotation

The oracle.webservices.annotations.async.CallbackSecurityPolicy annotation attaches one or more security polices to the callback client of the asynchronous Web service that will connect to the callback service. By default, no security policies are attached.

For example:

@CallbackSecurityPolicy("oracle/wss10_saml_token_with_message_protection_client_policy")

The following table defines the attributes that can be passed to the oracle.webservices.annotations.async.CallbackSecurityPolicy annotation.

Table A-10 Attributes for oracle.webservices.annotations.async.CallbackSecurityPolicy Annotation

Attribute	Description	Default
value	Array of String type values that specifies the URL of a client-side security policy.	""
enabled	Flag that specifies whether the specified security policies are enabled for the callback client.	true

@ManagementPolicy Annotation

The oracle.webservices.annotations.ManagementPolicy annotation attaches a management policy to the Web service.

For example:

@ManagementPolicy(
       value="oracle/log_policy",         enabled = "true")

The following table defines the attributes that can be passed to the oracle.webservices.annotations.ManagementPolicy annotation.

Table A-11 Attributes for oracle.webservices.annotations.ManagementPolicy Annotation

Attribute	Description	Default
value	String type value that specifies the management policy.	""
enabled	Boolean value that specifies whether or not the policy is enabled.	""

@MtomPolicy Annotation

The oracle.webservices.annotations.MtomPolicy annotation attaches an MTOM policy to the Web service.

For example:

@MtomPolicy(
       value="oracle/wsmtom_policy",         enabled = "true")

The following table defines the attributes that can be passed to the oracle.webservices.annotations.MtomPolicy annotation.

Table A-12 Attributes for oracle.webservices.annotations.MtomPolicy Annotation

Attribute	Description	Default
value	String type value that specifies the MTOM policy.	""
enabled	Boolean value that specifies whether or not the policy is enabled.	""

@PortableWebService Annotation

The oracle.webservices.annotations.PortableWebService annotation specifies, at the class level, that the JWS file implements an Oracle Infrastructure Web service.

For example:

@PortableWebService
@AsyncWebService
public class HelloService {
   public String hello(String name) {
      return "Hi " + name;
   }
}

The following table defines the attributes that are passed to the oracle.webservices.annotations.PortableWebServices annotation.

Table A-13 Attributes for oracle.webservices.annotations.PortableWebServiceAnnotation

Attribute	Description	Default
endpointInterface	Name of the service endpoint interface defining the service's abstract Web service contract. This annotation allows you to separate the interface contract from the implementation. If this annotation is present, the service endpoint interface is used to determine the abstract WSDL contract (portType and bindings). The service endpoint interface can include JSR-181 annotations to customize the mapping from Java to WSDL. The service implementation may implement the service endpoint interface, but this is not required. If this attribute is not specified, the Web service contract is generated from the annotations defined for the service implementation. If a service endpoint interface is required by the target environment, it will be generated into an implementation-defined package with an implementation-defined name. Note: This attribute is invalid when annotating an endpoint interface.	""
name	Name of the Web service. This name is used for the wsdl:portType when mapped to WSDL 1.1.	""
portName	Port name of the Web service. This name is used for the wsdl:port when mapped to WSDL 1.1. Note: This attribute is invalid when annotating an endpoint interface.	""
serviceName	Service name of the Web service. This name is used for the wsdl:service when mapped to WSDL 1.1. Note: This attribute is invalid when annotating an endpoint interface.	""
targetNamespace	Target namespace. If annotating a service endpoint interface, the target namespace used for the wsdl:portType and all associated elements. If annotating a service implementation that does not reference a service endpoint interface (through the endpointInterface attribute), the target namespace is used for the wsdl:portType, wsdl:service, and the associated XML elements. If annotating a service implementation that references a service endpoint interface (through the endpointInterface attribute), the target namespace is used for the wsdl:portType, wsdl:service, and the associated XML elements.	""
wsdlLocation	Location of the predefined WSLD describing the Web service. The value is a URL (relative or absolute) that refers to a pre-existing WSDL file. This attribute indicates that the service implementation is implementing a predefined WSDL contract. If there is an inconsistency between the service implementation and the portType and bindings declared in the WSDL, an error message is returned. Note that a single WSDL file may contain multiple portTypes and multiple bindings. The annotations on the service implementation determine the specific portType and bindings that correspond to the Web service.	""

@ReliabilityPolicy Annotation

The oracle.webservices.annotations.ReliabilityPolicy annotation attaches a reliable messaging policy to the Web service.

For example:

@MtomPolicy(
       value="oracle/wsrm11_policy",         enabled = "true")

The following table defines the attributes that can be passed to the oracle.webservices.annotations.ReliabilityPolicy annotation.

Table A-14 Attributes for oracle.webservices.annotations.ReliabilityPolicy Annotation

Attribute	Description	Default
value	String type value that specifies the reliable messaging policy.	""
enabled	Boolean value that specifies whether or not the policy is enabled.	""

@ResponseWebService Annotation

The oracle.webservices.annotations.async.ResponseWebService annotation enables you to customize the response Web service port information.

The following table defines the attributes that are passed to the oracle.webservices.annotations.async.ResponseWebService annotation.

Table A-15 Attributes for oracle.webservices.annotations.async.ResponseWebService Annotation

Attribute	Description	Default
name	Name of the response portType. Used as the name of the wsdl:portType when mapped to WSDL 1.1.	<name of the annotated class> + "Response"
targetNamespace	Target namespace used for the wsdl:portType, wsdl:service, and all associated elements.	Same as the asynchronous Web service target namespace
partnerLinkRole	Role name of the callback portType used in the partner link element of the WSDL.	N/A
serviceRefName	Service reference name used for the service reference that is used to send the response message. This value must be unique for the deployed archive and is used to define: <service-ref-name> and <display-name> elements under the <service-ref> element in the standard deployment descriptor. Name attribute in the <service-ref-mapping> element in the proprietary deployment descriptor	<name of the annotated class> + "ResponseWebService.SERVICE_REF_NAME_SUFFIX"
serviceName	Not used in this release.	N/A
portName	Not used in this release.	N/A

@SecurityPolicies Annotation

The oracle.webservices.annotations.SecurityPolicies annotation specifies an array of @SecurityPolicy annotations. Use this annotation if you want to attach more than one WS-Policy files to a class.

For example:

@SecurityPolicies({
    @SecurityPolicy(value=
    "policy:oracle/wss10_username_token_with_message_protection_server_policy"),
    @SecurityPolicy(value=
    "policy:oracle/authorization_policy")})

@SecurityPolicy Annotation

The oracle.webservices.annotations.SecurityPolicy annotation attaches a security policy to the request or response SOAP message. This annotation can be used on its own to apply a single WS-Policy file to a class. If you want to apply more than one WS-Policy file to a class, use the @SecurityPolicies annotation to group them together.

For example:

@SecurityPolicy(value=
    "policy:oracle/wss10_username_token_with_message_protection_server_policy"),

The following table summarizes the attributes that you can pass to the oracle.webservices.annotations.SecurityPolicy annotation.

Table A-16 Attributes for oracle.webservices.annotations.SecurityPolicy Annotation

Attribute	Description	Default
value	Location from which to retrieve the WS-Policy file. Use the `http:` prefix to specify the URL of a WS-Policy file on the Web. Use the `policy:` prefix to specify that the WS-Policy file is packaged in the policy repository.	""
enabled	Optional. Boolean value that specifies whether the policy is enabled.	true
Properties	Optional. Array of property value-name pairs.	""