Package com.softwareag.entirex.aci

Class Conversation

  • public class Conversation
extends BrokerCommunication
    Represents a conversational communication with a participant.
    When a new instance of a Conversation object is created, the first send or sendReceive call will establish a new conversation. The caller plays the role of a client in this conversation.
    When a new instance of a Conversation object is created, the first receive call will wait for a new conversation established by a client. The caller plays the role of a server in this conversation.
    An instance of a Conversation object is automatically created when a new conversation is received from the receive call of a BrokerService object.
    See Also:
    BrokerService.receive(java.lang.String)

    • Constructor Detail

      • Conversation

        public Conversation​(BrokerService brokerService)
        Creates a new Conversation object and attaches it to the specified BrokerService.
        If the next method call on this object is a send or a sendReceive, this call will establish a new conversation.
        If the next method call on this object is a receive, this call will wait until a request for a new conversation is issued by a client.
        Parameters:
        brokerService - an instance of a BrokerService object.

      • Conversation

        public Conversation​(BrokerService brokerService,
                    ConversationState cstate)
             throws java.lang.IllegalArgumentException
        Creates a new Conversation object and attaches it to the specified BrokerService.
        The conversation is restored from the ConversationState object.
        If the next method call on this object is a send or a sendReceive, this call will establish a new conversation.
        If the next method call on this object is a receive, this call will wait until a request for a new conversation is issued by a client.
        Parameters:
        brokerService - an instance of a BrokerService object.
        cstate - the ConversationState object to be restored.
        Throws:
        java.lang.IllegalArgumentException - if ConversationState object is null.
        Since:
        7.1.1.10
        See Also:
        ConversationState

    • Method Detail

      • ignoreEOC

        public void ignoreEOC​(boolean sendEOC)
        Per default the call to receive and receivePreview methods will return null for the 0003 0005 error (Partner finished the conversation) only.
        Once the ignoreEOC method has been called all errors from the class 0003 will force the receive methods to return null instead of throwing a BrokerException. Optionally an EOC can be sent to Broker (only if conversation still exists).
        Parameters:
        sendEOC - if true send automatically an EOC to Broker for this conversation
        Since:
        7.1.1.20

      • send

        public void send​(BrokerMessage msg)
          throws BrokerException
        Sends an asynchronous conversational message.
        Send the message to the Broker without waiting for an answer. Suitable for immediate, uni-directional messages.
        Parameters:
        msg - BrokerMessage to send.
        Throws:
        BrokerException - A Broker exception.

      • sendReceive

        public BrokerMessage sendReceive​(BrokerMessage msg,
                                 java.lang.String wait)
                          throws BrokerException
        Sends a synchronous conversational message.
        Sends the message to the Broker and waits the specified time to receive an answer. The answer is returned in the BrokerMessage object. Uses the maximum receive length.
        Parameters:
        msg - BrokerMessage to send.
        wait - A timeout period, how long to wait for an immediate reply, measured in seconds/minutes/hours (depending on the trailing S/M/H character).
        Returns:
        the Broker message received.
        Throws:
        BrokerException - A Broker exception.
        java.lang.IllegalArgumentException - if parameter is invalid.

      • sendReceive

        public BrokerMessage sendReceive​(BrokerMessage msg)
                          throws BrokerException
        Sends a synchronous conversational message.
        Sends the message to the Broker and waits to receive an answer. The answer is returned in the BrokerMessage object. Uses the maximum receive length and the default wait time of the service.
        Parameters:
        msg - the message to send.
        Returns:
        the Broker message received.
        Throws:
        BrokerException - A Broker exception.
        java.lang.IllegalArgumentException - if parameter is invalid.
        Since:
        EntireX 5.2.1

      • end

        public void end()
         throws BrokerException
        Ends the current conversation. The partner can receive messages sent before the end of conversation was issued.
        Create a new Conversation object for the next conversation after calling this method.
        Throws:
        BrokerException - A Broker exception.

      • cancel

        public void cancel()
            throws BrokerException
        Cancels the current conversation.
        Create a new Conversation object for the next conversation after calling this method.
        Throws:
        BrokerException - A Broker exception.

      • receive

        public BrokerMessage receive​(java.lang.String wait)
                      throws BrokerException
        Receives an incoming request and waits the specified time for an answer.
        Depending on the state of the Conversation object this receive method will accept either a new conversation and receive the first message of this conversation or it will receive the next unprocessed message belonging to the current conversation.
        The answer is returned in the BrokerMessage object. If the conversation has been terminated normally by the partner (via the end() method call), null is returned. Uses the maximum receive length.
        Parameters:
        wait - A timeout period, how long to wait for a receive, measured in seconds/minutes/hours (depending on the trailing S/M/H character). When null or "NO" is specified, the operation is non-blocked. If no message is available, a Broker Exception with errorclass=74 and errorcode=74 is thrown.
        Returns:
        A BrokerMessage object, or null if the conversation has been ended normally.
        Throws:
        BrokerException - A Broker exception.
        java.lang.IllegalArgumentException - Thrown if parameter is invalid.

      • receive

        public BrokerMessage receive()
                      throws BrokerException
        Receives an incoming request and waits for an answer.
        Depending on the state of the Conversation object this receive method will accept either a new conversation and receive the first message of this conversation or it will receive the next unprocessed message belonging to the current conversation.
        The answer is returned in the BrokerMessage object. If the conversation has been terminated normally by the partner (via the end() method call), null is returned. Uses the maximum receive length and the default wait time from the service. If no message is available a Broker Exception with errorclass=74 and errorcode=74 is thrown.
        Returns:
        A BrokerMessage object, or null if the conversation has been ended normally.
        Throws:
        BrokerException - A Broker exception.
        Since:
        EntireX 5.2.1

      • receiveLast

        public BrokerMessage receiveLast()
                          throws BrokerException
        Re-reads the last message that was received for this conversation.
        This method can be called as often as necessary.
        The answer is returned in the BrokerMessage object. Uses the maximum receive length.
        Returns:
        A BrokerMessage object.
        Throws:
        BrokerException - A Broker exception.

      • receivePreview

        public BrokerMessage receivePreview​(java.lang.String wait)
                             throws BrokerException
        Receives an incoming request in preview mode and waits the specified time for an answer.
        Depending on the state of the Conversation object this receive method will accept either a new conversation and receive the first message of this conversation or it will receive the next unprocessed message belonging to the current conversation.
        A subsequent receive method call will return this previewed message again.
        The answer is returned in the BrokerMessage object. If the conversation has been terminated normally by the partner (via the end() method call) null is returned. Uses the maximum receive length.
        Parameters:
        wait - A timeout period, how long to wait for a receive, measured in seconds/minutes/hours (depending on the trailing S/M/H character). When null or "NO" is specified, the operation is non-blocked. If no message is available, a Broker Exception with errorclass=74 and errorcode=74 is thrown.
        Returns:
        A BrokerMessage object, or null if the conversation has been ended normally.
        Throws:
        BrokerException - A Broker exception.
        java.lang.IllegalArgumentException - Thrown if parameter is invalid.

      • receivePreview

        public BrokerMessage receivePreview()
                             throws BrokerException
        Receives an incoming request in preview mode and waits the default time for an answer.
        Depending on the state of the Conversation object this receive method will accept either a new conversation and receive the first message of this conversation or it will receive the next unprocessed message belonging to the current conversation.
        A subsequent receive method call will return this previewed message again.
        The answer is returned in the BrokerMessage object. If the conversation has been terminated normally by the partner (via the end() method call), null is returned. Uses the maximum receive length.
        Returns:
        A BrokerMessage object, or null if the conversation has been ended normally.
        Throws:
        BrokerException - A Broker exception.