org.apache.axis2.client
Class OperationClient

java.lang.Object
  org.apache.axis2.client.OperationClient

public abstract class OperationClient
extends java.lang.Object

An operation client is the way an advanced user interacts with Axis2. Actual operation clients understand a specific MEP and hence their behavior is defined by their MEP. To interact with an operation client, you first get one from a specific AxisOperation. Then you set the messages into it one by one (whatever is available). Then, when you call execute() the client will execute what it can at that point. If executing the operation client results in a new message being created, then if a message receiver is registered with the client then the message will be delivered to that client.

Field Summary

protected AxisCallback	axisCallback
protected AxisOperation	axisOp
protected Callback	callback
protected boolean	completed
protected OperationContext	oc
protected Options	options
protected ServiceContext	sc

Constructor Summary

protected

OperationClient(AxisOperation axisOp, ServiceContext sc, Options options)

Method Summary

abstract void	addMessageContext(MessageContext messageContext) Add a message context to the client for processing.
protected void	addReferenceParameters(MessageContext msgctx)
void	complete(MessageContext msgCtxt) To close the transport if necessary , can call this method.
void	execute(boolean block) Execute the MEP.
abstract void	executeImpl(boolean block) Execute the MEP.
abstract MessageContext	getMessageContext(java.lang.String messageLabel) Return a message from the client - will return null if the requested message is not available.
OperationContext	getOperationContext() To get the operation context of the operation client
Options	getOptions() Return the options used by this client.
protected void	prepareMessageContext(ConfigurationContext configurationContext, MessageContext mc) prepareMessageContext gets a fresh new MessageContext ready to be sent.
void	reset() Reset the operation client to a clean status after the MEP has completed.
void	setCallback(AxisCallback callback) Set the callback to be executed when a message comes into the MEP and the operation client is executed.
abstract void	setCallback(Callback callback) Deprecated. Please use the AxisCallback interface rather than Callback, which has been deprecated
protected void	setMessageID(MessageContext mc) Create a message ID for the given message context if needed.
void	setOptions(Options options) Sets the options that should be used for this particular client.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

axisOp

protected AxisOperation axisOp

sc

protected ServiceContext sc

options

protected Options options

oc

protected OperationContext oc

callback

protected Callback callback

axisCallback

protected AxisCallback axisCallback

completed

protected boolean completed

Constructor Detail

OperationClient

protected OperationClient(AxisOperation axisOp,
                          ServiceContext sc,
                          Options options)

Method Detail

setOptions

public void setOptions(Options options)

Sets the options that should be used for this particular client. This resets the entire set of options to use the new options - so you'd lose any option cascading that may have been set up.

Parameters:

options - the options

getOptions

public Options getOptions()

Return the options used by this client. If you want to set a single option, then the right way is to do getOptions() and set specific options.

Returns:

the options, which will never be null.

addMessageContext

public abstract void addMessageContext(MessageContext messageContext)
                                throws AxisFault

Add a message context to the client for processing. This method must not process the message - it only records it in the operation client. Processing only occurs when execute() is called.

Parameters:

messageContext - the message context

Throws:

AxisFault - if this is called inappropriately.

getMessageContext

public abstract MessageContext getMessageContext(java.lang.String messageLabel)
                                          throws AxisFault

Return a message from the client - will return null if the requested message is not available.

Parameters:

messageLabel - the message label of the desired message context

Returns:

the desired message context or null if its not available.

Throws:

AxisFault - if the message label is invalid

setCallback

public abstract void setCallback(Callback callback)

Deprecated. Please use the AxisCallback interface rather than Callback, which has been deprecated

Set the callback to be executed when a message comes into the MEP and the operation client is executed. This is the way the operation client provides notification that a message has been received by it. Exactly when its executed and under what conditions is a function of the specific operation client.

Parameters:

callback - the callback to be used when the client decides its time to use it

setCallback

public final void setCallback(AxisCallback callback)

Set the callback to be executed when a message comes into the MEP and the operation client is executed. This is the way the operation client provides notification that a message has been received by it. Exactly when its executed and under what conditions is a function of the specific operation client.

Parameters:

callback - the callback to be used when the client decides its time to use it

execute

public final void execute(boolean block)
                   throws AxisFault

Execute the MEP. This method is final and only serves to set (if appropriate) the lastOperationContext on the ServiceContext, and then it calls executeImpl(), which does the actual work.

Parameters:

block - Indicates whether execution should block or return ASAP. What block means is of course a function of the specific operation client.

Throws:

AxisFault - if something goes wrong during the execution of the operation client.

executeImpl

public abstract void executeImpl(boolean block)
                          throws AxisFault

Execute the MEP. What this does depends on the specific operation client. The basic idea is to have the operation client execute and do something with the messages that have been added to it so far. For example, if its an Out-In MEP, then if the Out message has been set, then executing the client asks it to send the message and get the In message, possibly using a different thread.

Parameters:

block - Indicates whether execution should block or return ASAP. What block means is of course a function of the specific operation client.

Throws:

AxisFault - if something goes wrong during the execution of the operation client.

reset

public void reset()
           throws AxisFault

Reset the operation client to a clean status after the MEP has completed. This is how you can reuse an operation client. NOTE: this does not reset the options; only the internal state so the client can be used again.

Throws:

AxisFault - if reset is called before the MEP client has completed an interaction.

complete

public void complete(MessageContext msgCtxt)
              throws AxisFault

To close the transport if necessary , can call this method. The main usage of this method is when client uses two tarnsports for sending and receiving , and we need to remove entries for waiting calls in the transport listener queue. Note : DO NOT call this method if you are not using two transports to send and receive

Parameters:

msgCtxt - : MessageContext# which has all the transport information

Throws:

AxisFault - : throws AxisFault if something goes wrong

getOperationContext

public OperationContext getOperationContext()

To get the operation context of the operation client

Returns:

OperationContext

setMessageID

protected void setMessageID(MessageContext mc)

Create a message ID for the given message context if needed. If user gives an option with MessageID then just copy that into MessageContext , and with that there can be multiple message with same MessageID unless user call setOption for each invocation.

If user want to give message ID then the better way is to set the message ID in the option and call setOption for each invocation then the right thing will happen.

If user does not give a message ID then the new one will be created and set that into Message Context.

Parameters:

mc - the message context whose id is to be set

addReferenceParameters

protected void addReferenceParameters(MessageContext msgctx)

prepareMessageContext

protected void prepareMessageContext(ConfigurationContext configurationContext,
                                     MessageContext mc)
                              throws AxisFault

prepareMessageContext gets a fresh new MessageContext ready to be sent. It sets up the necessary properties, transport information, etc.

Parameters:

configurationContext - the active ConfigurationContext

mc - the MessageContext to be configured

Throws:

AxisFault - if there is a problem