4-4 Programming Advanced Features of JAX-RPC Web Services for Oracle WebLogic Server
4.3 Programming Guidelines for the Conversational JWS File
The following example shows a simple JWS file that implements a conversational Web service; see the explanation after the example for coding guidelines that correspond to
the Java code in bold.
package examples.webservices.conversation;
import java.io.Serializable;
import weblogic.jws.WLHttpTransport; import weblogic.jws.Conversation;
import weblogic.jws.Conversational; import weblogic.jws.Context;
import weblogic.wsee.jws.JwsContext; import weblogic.wsee.jws.ServiceHandle;
import javax.jws.WebService; import javax.jws.WebMethod;
ConversationalmaxIdleTime=10 minutes, maxAge=1 day,
runAsStartUser=false, singlePrincipal=false
WebServicename=ConversationalPortType, serviceName=ConversationalService,
targetNamespace=http:examples.org
WLHttpTransportcontextPath=conv, serviceUri=ConversationalService,
portName=ConversationalServicePort
Conversational Web service.
public class ConversationalServiceImpl implements Serializable { Context
private JwsContext ctx; public String status = undefined;
WebMethod Conversation Conversation.Phase.START
public String start {
ServiceHandle handle = ctx.getService; String convID = handle.getConversationID;
status = start; return Starting conversation, with ID + convID + and status equal to + status;
} WebMethod
Conversation Conversation.Phase.CONTINUE public String middleString message {
status = middle; return Middle of conversation; the message is: + message + and status is + status;
}
Creating Conversational Web Services 4-5
WebMethod Conversation Conversation.Phase.FINISH
public String finishString message {
status = finish; return End of conversation; the message is: + message + and status is + status;
} }
Follow these guidelines when programming the JWS file that implements a conversational Web service. Code snippets of the guidelines are shown in bold in the
preceding example.
■
Conversational Web services must implement java.io.Serializable, so you must first import the class into your JWS file:
import java.io.Serializable;
■
Import the conversational JWS annotations: import weblogic.jws.Conversation;
import weblogic.jws.Conversational;
■
If you want to access runtime information about the conversational Web service, import the Context annotation and context APIs:
import weblogic.jws.Context; import weblogic.wsee.jws.JwsContext;
import weblogic.wsee.jws.ServiceHandle; See Accessing Runtime Information about a Web service in Getting Started With
JAX-RPC Web Services for Oracle WebLogic Server for more information about the runtime Web service context.
■
Use the class-level Conversational annotation to specify that the Web service is conversational. Although this annotation is optional assuming you are
specifying the Conversation method-level annotation, it is a best practice to always use it in your JWS file to clearly specify that your Web service is
conversational.
Specify any of the following optional attributes: maxIdleTime is the maximum amount of time that the Web service can be idle before WebLogic Server finishes
the conversation; maxAge is the maximum age of the conversation; runAsStartUser
indicates whether the continue and finish phases of an existing conversation are run as the user who started the conversation; and
singlePrincipal indicates whether users other than the one who started a
conversation are allowed to execute the continue and finish phases of the conversation.
ConversationalmaxIdleTime=10 minutes, maxAge=1 day,
runAsStartUser=false, singlePrincipal=false
If a JWS file includes the Conversational annotation, all operations of the Web service are conversational. The default phase of an operation, if it does not
have an explicit Conversation annotation, is continue. However, because a
4-6 Programming Advanced Features of JAX-RPC Web Services for Oracle WebLogic Server
conversational Web service is required to include at least one start and one finish operation, you must use the method-level Conversation annotation to specify
which methods implement these operations.
See weblogic.jws.Conversational in WebLogic Web Services Reference for Oracle WebLogic Server for additional information and default values for the attributes.
■
Your JWS file must implement java.io.Serializable: public class ConversationalServiceImpl implements Serializable {
■
To access runtime information about the Web service, annotate a private class variable, of data type weblogic.wsee.jws.JwsContext, with the field-level
Context JWS annotation:
Context private JwsContext ctx;
■
Use the Conversation annotation to specify the methods that implement the start, continue, and finish phases of your conversation. A conversation is required
to have at least one start and one finish operation; the continue operation is optional. Use the following parameters to the annotation to specify the phase:
Conversation.Phase.START
, Conversation.Phase.CONTINUE, or Conversation.Phase.FINISH
. The following example shows how to specify the start operation:
WebMethod Conversation Conversation.Phase.START
public String start {...
If you mark just one method of the JWS file with the Conversation annotation, then the entire Web service becomes conversational and each operation is
considered part of the conversation; this is true even if you have not used the optional class-level Conversational annotation in your JWS file. Any methods
not explicitly annotated with Conversation are, by default, continue operations. This means that, for example, if a client application invokes one of
these continue methods without having previously invoked a start operation, the Web service returns a runtime error.
Finally, if you plan to invoke the conversational Web service from a stand-alone Java client, the start operation is required to be request-response, or in other
words, it cannot be annotated with the Oneway JWS annotation. The operation can return void. If you are going to invoke the Web service only from client
applications that run in WebLogic Server, then this requirement does not apply.
See weblogic.jws.Conversation in WebLogic Web Services Reference for Oracle WebLogic Server for additional information.
■
Use the JwsContext instance to get runtime information about the Web service. For example, the following code in the start operation gets the ID that WebLogic
Server assigns to the new conversation: ServiceHandle handle = ctx.getService;
String convID = handle.getConversationID; See Accessing Runtime Information about a Web service in Getting Started With
JAX-RPC Web Services for Oracle WebLogic Server for detailed information on using the context-related APIs.
Creating Conversational Web Services 4-7
4.4 Programming Guidelines for the JWS File That Invokes a Conversational Web Service
Kategori