This appendix describes the asynchronous Web service and policy annotations that are used by Oracle Infrastructure Web services.
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 |
|---|---|
|
Attaches a WS-Addressing policy to the Web service. |
|
|
Declares a Web service to be an asynchronous Web service. |
|
|
Specifies the details of a queue used for saving the request for later processing. |
|
|
Defines the queue used to save the response for later processing |
|
|
Not used in this release. |
|
|
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. |
|
|
Attaches a management policy to the callback client of the asynchronous Web service that will connect to the callback service. |
|
|
Attaches an MTOM policy to the callback client of the asynchronous Web service that will connect to the callback service. |
|
|
Enables you to specify properties that are required in the message context when calling the callback service. |
|
|
Enables you to specify properties that are required in the message context when calling the callback service. |
|
|
Attaches one or more security polices to the callback client of the asynchronous Web service that will connect to the callback service. |
|
|
Attaches a management policy to the Web service. |
|
|
Attaches an MTOM policy to the Web service. |
|
|
Specifies, at the class level, that the JWS file implements an Oracle Infrastructure Web service. |
|
|
Attaches a reliable messaging policy to the Web service. |
|
|
Customizes the response Web service port information. |
|
|
Attaches a list of security policies to the Web service. |
|
|
Attaches a security policy to the Web service. |
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 |
"" |
|
enabled |
Boolean value that specifies whether or not the policy is enabled. |
true |
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;
}
}
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 |
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 |
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.
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:
|
<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 |
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 |
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.
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.
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.
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 |
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.
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.
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. |
"" |
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.
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:
|
<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 |
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")})
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 |
"" |
|
enabled |
Optional. Boolean value that specifies whether the policy is enabled. |
true |
|
Properties |
Optional. Array of property value-name pairs. |
"" |