Package org.apache.axis2.client

Class OperationClient

  • public abstract class OperationClient
extends 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.

    • 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​(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 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