|
|
The following sections provide reference documentation about standard (JSR-181) and WebLogic-specific JWS annotations:
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()public int echoInt(
@WebResult(name="IntegerOutput",
targetNamespace="http://example.org/complex")@WebParam(name="IntegerInput",int input)
targetNamespace="http://example.org/complex")
{
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")public BasicStruct echoStruct(BasicStruct struct)
@WebResult(name="EchoStructReturnMessage",
targetNamespace="http://example.org/complex")
{
System.out.println("echoComplexType called");
return struct;
}
}
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:
Specifies that the JWS file implements a Web Service.
|
The default value is specified by the
JAX-RPC specification.
|
|||||
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.
|
|||||
@WebService(name="JMSTransportPortType",
serviceName="JMSTransportService",
targetNamespace="http://example.org")
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.
@WebMethod(operationName="echoComplexType")public BasicStruct echoStruct(BasicStruct struct)
{
...
}
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.
@WebMethod()@Oneway()public void helloWorld(String input) {
...
}
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.
|
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.
|
|||
@WebMethod()
public int echoInt(@WebParam(name="IntegerInput",int input)
targetNamespace="http://example.org/complex")
{
...
}
Customizes the mapping between the Web Service operation return value and the corresponding element of the generated WSDL file.
@WebMethod(operationName="echoComplexType")@WebResult(name="EchoStructReturnMessage",public BasicStruct echoStruct(BasicStruct struct)
targetNamespace="http://example.org/complex")
{
...
}
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:
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.
package examples.webservices.handler;
...
@WebService (...)
@HandlerChain(file="HandlerConfig.xml", name="SimpleChain")public class HandlerChainImpl {...
}
Specifies the mapping of the Web Service onto the SOAP message protocol.
package examples.webservices.bindings;
...
@WebService (...)
@SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
use=SOAPBinding.Use.LITERAL,
parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)public class BindingsImpl {...
}
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.
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 {...
}
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.
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:
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.
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 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:
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:
void.onMethodNameAsyncFailure, 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.
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 (onMethodNameAsyncFailure) 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.
|
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); |
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.
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:
void.onMethodNameAsyncResponse, 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.
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 (onMethodNameAsyncResponse) 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.
|
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); |
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.
Specifies whether the Web Service uses version 1.1 or 1.2 of the Simple Object Access Protocol (SOAP) implementation when accepting or sending SOAP messages. By default, WebLogic Web Services use SOAP 1.1.
The following example shows how to specify SOAP 1.2; only the relevant code is shown:
package examples.webservices.soap12;
...
import javax.jws.WebMethod;
import javax.jws.WebService;import weblogic.jws.Binding;@WebService(name="SOAP12PortType",
serviceName="SOAP12Service",
targetNamespace="http://example.org")
@Binding(Binding.Type.SOAP12)public class SOAP12Impl {@WebMethod()
public String sayHello(String message) {
...
}
}
Specifies the JNDI name of the JMS queue to which WebLogic Server:
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.
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);
}
}
Specifies that the annotated variable is a callback, which means that you can use the variable to send callback events back to the client Web Service that invoked an operation of the target Web Service.
You specify the @Callback annotation in the target Web Service so that it can call back to the client Web Service. The data type of the annotated variable is the callback interface.
The callback feature works between two WebLogic Web Services. When you program the feature, however, you create the following three Java files:
jwsc Ant task automatically generates an implementation of the interface. The implementation simply passes a message from the target Web Service back to the client Web Service. The generated Web Service is deployed to the same WebLogic Server that hosts the client Web Service.See Using Callbacks to Notify Clients of Events for additional overview and procedural information about programming callbacks.
The @Callback annotation does not have any attributes.
The following example shows a very simple target Web Service in which a variable called callback is annotated with the @Callback annotation. The data type of the variable is CallbackInterface; this means a callback Web Service must exist with this name. After the variable is injected with the callback information, you can invoke the callback methods defined in CallbackInterface; in the example, the callback method is callbackOperation().
The text in bold shows the relevant code:
package examples.webservices.callback;
import weblogic.jws.WLHttpTransport;import weblogic.jws.Callback;
import javax.jws.WebService;
import javax.jws.WebMethod;
@WebService(name="CallbackPortType",
serviceName="TargetService",
targetNamespace="http://examples.org/")
@WLHttpTransport(contextPath="callback",
serviceUri="TargetService",
portName="TargetServicePort")
public class TargetServiceImpl { @Callback
CallbackInterface callback;@WebMethod
public void targetOperation (String message) {
callback.callbackOperation (message);}
}
Specifies the method in the client Web Service that handles the messages it receives from the callback Web Service. Use the attributes to link the callback message handler methods in the client Web Service with the callback method in the callback interface.
The callback feature works between two WebLogic Web Services. When you program the feature, however, you create the following three Java files:
jwsc Ant task automatically generates an implementation of the interface. The implementation simply passes a message from the target Web Service back to the client Web Service. The generated Web Service is deployed to the same WebLogic Server that hosts the client Web Service.See Using Callbacks to Notify Clients of Events for additional overview and procedural information about programming callbacks.
The following example shows a method of a client Web Service annotated with the @CallbackMethod annotation. The attributes show that a variable called port must have previously been injected with JAX-RPC stub information and that the annotated method will handle messages received from a callback operation called callbackOperation().
@CallbackMethod(target="port", operation="callbackOperation")@CallbackRolesAllowed(@SecurityRole(role="engineer", mapToPrincipals="shackell"))
public void callbackHandler(String msg) {
System.out.println (msg);
}
Specifies that the JWS file is actually a Java interface that describes a callback Web Service. This annotation is analogous to the @javax.jws.WebService, but specific to callbacks and with a reduced set of attributes.
The callback feature works between two WebLogic Web Services. When you program the feature, however, you create the following three Java files:
jwsc Ant task automatically generates an implementation of the interface. The implementation simply passes a message from the target Web Service back to the client Web Service. The generated Web Service is deployed to the same WebLogic Server that hosts the client Web Service.
Use the @CallbackInterface annotation to specify that the Java file is a callback interface file.
When you program the callback interface, you specify one or more callback methods; as with standard non-callback Web Services, you annotate these methods with the @javax.jws.WebMethod annotation to specify that they are Web Service operations. However, contrary to non-callback methods, you never write the actual implementation code for these callback methods; rather, when you compile the client Web Service with the jwsc Ant task, the task automatically creates an implementation of the interface and packages it into a Web Service. This generated implementation specifies that the callback methods all do the same thing: send a message from the target Web Service that invokes the callback method back to the client Web Service.
See Using Callbacks to Notify Clients of Events for additional overview and procedural information about programming callbacks.
The following example shows a very simple callback interface. The resulting callback Web Service has one callback method, callbackOperation().
package examples.webservices.callback;
import weblogic.jws.CallbackService;import javax.jws.Oneway;
import javax.jws.WebMethod;
@CallbackServicepublic interface CallbackInterface {@WebMethod
@Onewaypublic void callbackOperation (String msg);
}
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.
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() {
...
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.
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. 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. Specifies that the method explicitly finishes a conversation in progress. |
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}
}
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.
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.
|
|||
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.
|
|||
Specifies whether users other than the one who started a conversation are allowed to execute the continue and finish phases of the conversation.
|
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 {...
Specifies which public methods of a JWS are buffered. If specified at the class-level, then all public methods are buffered; if you want only a subset of the methods to be buffered, specify the annotation at the appropriate method-level.
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.
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.
@MessageBuffer(retryDelay="2 days") |
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, ret