A Annotation Reference

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

This appendix includes the following topics:

Overview of Annotations
@AddressingPolicy Annotation
@AsyncWebService Annotation
@AsyncWebServiceQueue Annotation
@AsyncWebServiceResponseQueue Annotation
@CallbackAddressingPolicy Annotation
@CallbackManagementPolicy Annotation
@CallbackMethod Annotation
@CallbackMtomPolicy Annotation
@CallbackProperties Annotation
@CallbackSecurityPolicy Annotation
@ManagementPolicy Annotation
@MtomPolicy Annotation
@PortableWebService Annotation
@PortableWebServiceProvider Annotation
@Property Annotation
@ResponseWebService Annotation
@Retry 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 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.
@CallbackManagementPolicy Annotation	Attaches a management policy to the callback client of the asynchronous Web service that will connect to the callback service.
@CallbackMethod Annotation	Enables you to customize the names of the WSDL entities for the corresponding operation in the callback portType, set whether a method is synchronous or asynchronous, and disable the automatic sending of the response.
@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.
@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.
@Property Annotation	Enables you to specify a single property that is required in the message context when calling the callback 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	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 Creating the Request and Response Queues.

For example:

@AsyncWebServiceQueue (
    connectionFactory = "weblogic.jms.XAConnectionFactory",
    queue = "oracle.j2ee.ws.server.async.NonDefaultRequestQueue",
    enableTransaction = true
    transactionTimeout=3600
    messageProcessorInitialPoolSize=1
    messageProcessorMaxPoolSize=16
)

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
`transactionTimeout`	Transaction timeout in seconds for processing a queued message. This attribute is meaningful only if the transaction is enabled or the method is non-idempotent. The timeout is applied to the MDB that processes the request messages.	0—Server-level configured value is used by default.
`messageProcessorInitialPoolSize`	Initial number of message processor instances that are available in the pool to process asynchronous requests. For guidance on setting this value, see "Creating Custom Request and Response Queues".	1
`messageProcessorMaxPoolSize`	Maximum number of message processor instances that are available in the pool to process asynchronous requests. The larger the value, the more throughput. However, more resources, such as threads and database connections, will be used. The exact resource requirements are dependent on the type of persistence store used for saving the asynchronous request messages. For guidance on setting this value, see "Creating Custom Request and Response Queues".	16

@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
    messageProcessorInitialPoolSize=1
    messageProcessorMaxPoolSize=16
)

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
`messageProcessorInitialPoolSize`	Initial number of message processor instances that are available in the pool to process asynchronous responses. For guidance on setting this value, see "Creating Custom Request and Response Queues".	1
`messageProcessorMaxPoolSize`	Maximum number of message processor instances that are available in the pool to process asynchronous responses. The larger the value, the more throughput. However, more resources, such as threads and database connections, will be used. The exact resource requirements are dependent on the type of persistence store used for saving the asynchronous request messages. For guidance on setting this value, see "Creating Custom Request and Response Queues".	16

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

@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-5 Attributes for oracle.webservices.annotations.async.CallbackManagementPolicy Annotation

Attribute	Description	Default
`value`	URI of a management policy.	""
`enabled`	Flag that specifies whether the specified security policies are enabled for the callback client.	true
`sendAutoResponse`	Flag that specifies whether the response is sent automatically upon completion of the asynchronous operation. In some cases, you may wish to disable automatic sending of the response, and access it manually, when the application is ready.	true

@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-6 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

@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`	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(
       key = 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.	""

@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-9 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-10 Attributes for oracle.webservices.annotations.ManagementPolicy Annotation

Attribute	Description	Default
`value`	URI of a 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-11 Attributes for oracle.webservices.annotations.MtomPolicy Annotation

Attribute	Description	Default
`value`	URI of an 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.PortableWebService annotation.

Table A-12 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 WSDL 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.	""

@PortableWebServiceProvider Annotation

The oralce.webservices.annotations.PortableWebServiceProvider annotation marks a Java class as implementing an Oracle Infrastructure Web Services Provider.

For example:

@PortableWebServiceProvider
@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.PortableWebServiceProvider annotation.

Table A-13 Attributes for oracle.webservices.annotations.PortableWebServiceProvider Annotation

Attribute	Description	Default
`portName`	Name of the Web service port.	""
`serviceName`	Name of the Web service.	""
`targetNamespace`	Target namespace.	""
`wsdlLocation`	Location of the predefined WSDL 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.	""

@Property Annotation

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

For example:

@Property(
       key = SecurityConstants.ClientConstants.WSS_CSF_KEY,

        value = "basic.credentials")

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

Table A-14 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.	""

@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

@Retry Annotation

The oracle.webservices.annotations.async.Retry annotation specifies whether the asynchronous method is idempotent, or retriable, in the event that its execution is terminated abnormally (for example, due to system failure). This annotation can be applied at the class or method level; the method-level setting overrides the class-level setting.

By default, all asynchronous methods are idempotent; this implies that there are no side effects of calling the asynchronous method more than once. If an asynchronous method is not idempotent, you should explicitly set this annotation with the enable attribute set to false.

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

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

Attribute Description Default

Attribute	Description	Default
`enable`	Flag that specifies whether the method is idempotent and can be retried safely in the event that execution is abnormally terminated.	true
`supportsGlobalTransaction`	Flag that specifies whether the method can participate in the global transaction. This field is used only if there are no other annotations specifying the global transaction behavior, such as `javax.ejb.TransactionAttribute` or WS-AT annotation. For example, if the transaction type is set to "Required", "Mandatory" and "Supports" then the method is assumed to participate in the global transaction. Note: If this field is specified in addition to a global transaction specific annotation, then their values should be consistent. If the method can participate in a global transaction, set the `supportsGlobalTransaction` attribute to true. In this case, the system can achieve the non-idempotent behavior in the most reliable way. The execution of the method and the posting of the response are accomplished within a single global transaction. If any of the processing steps result in an abnormal termination, the transaction will be rolled back and the method will be executed again in a new transaction. In this scenario, it is guaranteed that the method is executed only once, as part of a completed transaction, and the result of the execution is posted only once to the response queue. If the method cannot participate in a global transaction, set the `supportsGlobalTransaction` to false. In this case, the system guarantees that the non-idempotent method is executed "at most once." A fault response message is returned to the callback service in the event either of the following occurs: If execution of the asynchronous method does not complete due to abnormal termination. If there is an abnormal termination after completely executing the method, but before the response has been posted to the queue.	false

enable

Flag that specifies whether the method is idempotent and can be retried safely in the event that execution is abnormally terminated.

true

supportsGlobalTransaction

Flag that specifies whether the method can participate in the global transaction.

This field is used only if there are no other annotations specifying the global transaction behavior, such as javax.ejb.TransactionAttribute or WS-AT annotation. For example, if the transaction type is set to "Required", "Mandatory" and "Supports" then the method is assumed to participate in the global transaction.

Note: If this field is specified in addition to a global transaction specific annotation, then their values should be consistent.

If the method can participate in a global transaction, set the supportsGlobalTransaction attribute to true. In this case, the system can achieve the non-idempotent behavior in the most reliable way. The execution of the method and the posting of the response are accomplished within a single global transaction. If any of the processing steps result in an abnormal termination, the transaction will be rolled back and the method will be executed again in a new transaction. In this scenario, it is guaranteed that the method is executed only once, as part of a completed transaction, and the result of the execution is posted only once to the response queue.

If the method cannot participate in a global transaction, set the supportsGlobalTransaction to false. In this case, the system guarantees that the non-idempotent method is executed "at most once." A fault response message is returned to the callback service in the event either of the following occurs:

If execution of the asynchronous method does not complete due to abnormal termination.
If there is an abnormal termination after completely executing the method, but before the response has been posted to the queue.

false

@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-17 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.	""