com.softwareag.entirex.aci
Class Conversation

java.lang.Object
  com.softwareag.entirex.aci.BrokerCommunication
      com.softwareag.entirex.aci.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)

Field Summary

Fields inherited from class com.softwareag.entirex.aci.BrokerCommunication

brokerService

Constructor Summary

Conversation(BrokerService brokerService)
Creates a new Conversation object and attaches it to the specified BrokerService.

Conversation(BrokerService brokerService, ConversationState cstate)
Creates a new Conversation object and attaches it to the specified BrokerService.

Method Summary

void	cancel() Cancels the current conversation.
void	end() Ends the current conversation.
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.
BrokerMessage	receive() Receives an incoming request and waits for an answer.
BrokerMessage	receive(java.lang.String wait) Receives an incoming request and waits the specified time for an answer.
BrokerMessage	receiveLast() Re-reads the last message that was received for this conversation.
BrokerMessage	receivePreview() Receives an incoming request in preview mode and waits the default time for an answer.
BrokerMessage	receivePreview(java.lang.String wait) Receives an incoming request in preview mode and waits the specified time for an answer.
void	send(BrokerMessage msg) Sends an asynchronous conversational message.
BrokerMessage	sendReceive(BrokerMessage msg) Sends a synchronous conversational message.
BrokerMessage	sendReceive(BrokerMessage msg, java.lang.String wait) Sends a synchronous conversational message.

Methods inherited from class com.softwareag.entirex.aci.BrokerCommunication

dispose, getBrokerService, getUserData, saveState, setUserData

Methods inherited from class java.lang.Object

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

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 send 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.