com.ls.lars.communication
Class QualityOfService

java.lang.Object
  |
  +--com.ls.lars.communication.QualityOfService

public class QualityOfService
extends Object

Offers constants and methods to deal with the quality of service of a message. The quality of service of a message determines, in which conditions the system automatically has to generate a reply for that message. The default quality of service for a message is QOS_REPLY_ERROR, which denotes, that a reply is wanted for any possible error that might occur after the message was sent away.

Version:
$Revision: 1.8 $
Author:
Last modified by $Author: MHeitz $
See Also:
Message.setQualityOfService(int)

Field Summary
static Map constantMap
          for easy conversion of Strings into quality constants
static Map descriptionMap
          for easy conversion of quality constants into Strings
static int QOS_AGENT_FAILURE
          Reply is wished, if the service-specific interpret method (e.g. interpretSetLog) fails with an uncaught exception (this means, that the agent failed to interpret the message).
static int QOS_DELIVERED_INTO_INBOX
          Reply is wished in any case, where the routing succeeded with placing the message into a recipients inbox (QOS_INTERPRET_EXECUTES or QOS_NO_INTERPRET_DUE_TO_SECURITY).
static int QOS_GROUP_UNKNOWN
          Reply is wished, if the group is unknown at the receiving platform's message router.
static int QOS_INTERPRET_EXECUTES
          Reply is wished, if the service-specific interpret method executes (QOS_INTERPRET_TRUE or QOS_INTERPRET_TRUE_AND_NOT_REPLIED_BEFORE or QOS_INTERPRET_FALSE or QOS_AGENT_FAILURE).
static int QOS_INTERPRET_FAILS
          Reply is wished, if the service-specific interpret method (e.g. interpretSetLog) fails for any reason (QOS_INTERPRET_FALSE or QOS_AGENT_FAILURE or QOS_SERVICE_UNKNOWN).
static int QOS_INTERPRET_FALSE
          Reply is wished, if the service-specific interpret method (e.g. interpretSetLog) returns false (this means, that the current message couldn't be interpreted due to a wrong message format).
static int QOS_INTERPRET_SUCCEEDS
          Reply is wished, if the interpret succeeds (only a synonym for QOS_INTERPRET_TRUE, because QOS_INTERPRET_TRUE and QOS_INTERPRET_TRUE_AND_NOT_REPLIED_BEFORE are a either-or-case).
static int QOS_INTERPRET_TRUE
          Reply is wished, if the service-specific interpret method (e.g. interpretSetLog) returns true.
static int QOS_INTERPRET_TRUE_AND_NOT_REPLIED_BEFORE
          Reply is wished, if the service-specific interpret method (e.g. interpretSetLog) returns true and no reply was yet generated for the current message.
static int QOS_LARS_FAILURE
          Reply is wished, if the lars routing mechanism has an internal error.
static int QOS_LIFETIME_EXCEEDS
          Reply is wished, if the message's hop counter exceeds.
static int QOS_MESSAGE_CONVERSION_FAILURE
          Reply is wished, if the delivery fails due to message conversion problems (e.g. a conversion into XML fails or the message's content is not serializable).
static int QOS_MESSENGER_NOT_CONNECTED
          Reply is wished, if the messenger is not connected.
static int QOS_NO_INTERPRET_DUE_TO_SECURITY
          Reply is wished, if the service-specific interpret method (e.g. interpretSetLog) is not called due to any security restrition ((QOS_SERVICE_ACCESS_DENIED or (QOS_PKI_FAILS).
static int QOS_NONE
          This quality of service denotes, that no reply message is needed - not even, if this message is undeliverable.
static int QOS_PKI_FAILS
          Reply is wished, if the PKI decryption fails.
static int QOS_PLATFORM_NOT_REACHABLE
          Reply is wished, if the platform is not reachable.
static int QOS_RECEIVER_INVALID
          Reply is wished, if the receiver is invalid.
static int QOS_RECEIVER_NOT_AVAILABLE
          Reply is wished, if the receiver is not available on the target platform.
static int QOS_REMOTE_MESSENGER_NOT_REACHABLE
          Reply is wished, if the remote messenger cannot be reached due to network or connections problems.
static int QOS_REPLY_ALWAYS
          This quality of service denotes, that always a reply message shall be sent.
static int QOS_REPLY_ERROR
          Reply is wished in case of any error (QOS_INTERPRET_FAILS or QOS_NO_INTERPRET_DUE_TO_SECURITY or QOS_ROUTING_FAILURE).
static int QOS_ROUTING_FAILURE
          Reply is wished in any case, where the recipient cannot be reached (QOS_WRONG_RECIPIENT or QOS_PLATFORM_NOT_REACHABLE or QOS_LIFETIME_EXCEEDS or QOS_MESSENGER_NOT_CONNECTED or QOS_REMOTE_MESSENGER_NOT_REACHABLE or QOS_MESSAGE_CONVERSION_FAILURE or QOS_LARS_FAILURE).
static int QOS_SERVICE_ACCESS_DENIED
          Reply is wished, if the service may not be used by the caller.
static int QOS_SERVICE_NOT_REGISTERED
          Reply is wished, if the service is not registered at the receiving platform's message router.
static int QOS_SERVICE_UNKNOWN
          Reply is wished, if the service-specific interpret method (e.g. interpretSetLog) does not exist (this means, that the current message couldn't be interpreted because the given service is not supported by the receiving agent).
static int QOS_WRONG_RECIPIENT
          Reply is wished in any case, where the recipient cannot be determined (QOS_GROUP_UNKNOWN or QOS_SERVICE_NOT_REGISTERED or QOS_RECEIVER_INVALID or QOS_RECEIVER_NOT_AVAILABLE).
 
Constructor Summary
QualityOfService()
           
 
Method Summary
static SingleMessage createReply(Message message, String serviceOfReply, int failureCode, String reasonDescription, String messengerOfFailure)
          Checks quality of service of the given message and the given failureCode and determines therefrom, if an error notification needs to be sent to the originator of the message.
static int getConstant(String qos)
          returns the int value of the given quality of service
static String getDescription(int qos)
          converts the given int representation of a quality of service into a string.
static String getDetailedDescription(int qos)
          converts the given int representation of a quality of service into a string with the most detailed constants contained in the given qos
static boolean isReplyNeeded(int qos, int failureReasonToCheck)
          returns true, if a reply is needed for the specified quality of service and failure reason
static void main(String[] args)
          prints to System.out the translation of the given quality of service constants
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

QOS_NONE

public static final int QOS_NONE
This quality of service denotes, that no reply message is needed - not even, if this message is undeliverable.
Note, that this does not mean, that no reply may be generated and sent. This quality of service only tells the routing mechanisms and the receiver, that the sender does not need a reply.

QOS_INTERPRET_TRUE

public static final int QOS_INTERPRET_TRUE
Reply is wished, if the service-specific interpret method (e.g. interpretSetLog) returns true.

QOS_INTERPRET_TRUE_AND_NOT_REPLIED_BEFORE

public static final int QOS_INTERPRET_TRUE_AND_NOT_REPLIED_BEFORE
Reply is wished, if the service-specific interpret method (e.g. interpretSetLog) returns true and no reply was yet generated for the current message.

QOS_INTERPRET_SUCCEEDS

public static final int QOS_INTERPRET_SUCCEEDS
Reply is wished, if the interpret succeeds (only a synonym for QOS_INTERPRET_TRUE, because QOS_INTERPRET_TRUE and QOS_INTERPRET_TRUE_AND_NOT_REPLIED_BEFORE are a either-or-case).

QOS_INTERPRET_FALSE

public static final int QOS_INTERPRET_FALSE
Reply is wished, if the service-specific interpret method (e.g. interpretSetLog) returns false (this means, that the current message couldn't be interpreted due to a wrong message format).

QOS_AGENT_FAILURE

public static final int QOS_AGENT_FAILURE
Reply is wished, if the service-specific interpret method (e.g. interpretSetLog) fails with an uncaught exception (this means, that the agent failed to interpret the message).

QOS_SERVICE_UNKNOWN

public static final int QOS_SERVICE_UNKNOWN
Reply is wished, if the service-specific interpret method (e.g. interpretSetLog) does not exist (this means, that the current message couldn't be interpreted because the given service is not supported by the receiving agent).

QOS_INTERPRET_FAILS

public static final int QOS_INTERPRET_FAILS
Reply is wished, if the service-specific interpret method (e.g. interpretSetLog) fails for any reason (QOS_INTERPRET_FALSE or QOS_AGENT_FAILURE or QOS_SERVICE_UNKNOWN).

QOS_INTERPRET_EXECUTES

public static final int QOS_INTERPRET_EXECUTES
Reply is wished, if the service-specific interpret method executes (QOS_INTERPRET_TRUE or QOS_INTERPRET_TRUE_AND_NOT_REPLIED_BEFORE or QOS_INTERPRET_FALSE or QOS_AGENT_FAILURE).

QOS_SERVICE_ACCESS_DENIED

public static final int QOS_SERVICE_ACCESS_DENIED
Reply is wished, if the service may not be used by the caller.

QOS_PKI_FAILS

public static final int QOS_PKI_FAILS
Reply is wished, if the PKI decryption fails.

QOS_NO_INTERPRET_DUE_TO_SECURITY

public static final int QOS_NO_INTERPRET_DUE_TO_SECURITY
Reply is wished, if the service-specific interpret method (e.g. interpretSetLog) is not called due to any security restrition ((QOS_SERVICE_ACCESS_DENIED or (QOS_PKI_FAILS).

QOS_DELIVERED_INTO_INBOX

public static final int QOS_DELIVERED_INTO_INBOX
Reply is wished in any case, where the routing succeeded with placing the message into a recipients inbox (QOS_INTERPRET_EXECUTES or QOS_NO_INTERPRET_DUE_TO_SECURITY).

QOS_LIFETIME_EXCEEDS

public static final int QOS_LIFETIME_EXCEEDS
Reply is wished, if the message's hop counter exceeds.

QOS_GROUP_UNKNOWN

public static final int QOS_GROUP_UNKNOWN
Reply is wished, if the group is unknown at the receiving platform's message router.

QOS_SERVICE_NOT_REGISTERED

public static final int QOS_SERVICE_NOT_REGISTERED
Reply is wished, if the service is not registered at the receiving platform's message router.

QOS_RECEIVER_INVALID

public static final int QOS_RECEIVER_INVALID
Reply is wished, if the receiver is invalid.
See Also:
SingleMessage.hasInvalidReceiver()

QOS_RECEIVER_NOT_AVAILABLE

public static final int QOS_RECEIVER_NOT_AVAILABLE
Reply is wished, if the receiver is not available on the target platform.

QOS_PLATFORM_NOT_REACHABLE

public static final int QOS_PLATFORM_NOT_REACHABLE
Reply is wished, if the platform is not reachable.

QOS_MESSENGER_NOT_CONNECTED

public static final int QOS_MESSENGER_NOT_CONNECTED
Reply is wished, if the messenger is not connected.

QOS_REMOTE_MESSENGER_NOT_REACHABLE

public static final int QOS_REMOTE_MESSENGER_NOT_REACHABLE
Reply is wished, if the remote messenger cannot be reached due to network or connections problems.

QOS_MESSAGE_CONVERSION_FAILURE

public static final int QOS_MESSAGE_CONVERSION_FAILURE
Reply is wished, if the delivery fails due to message conversion problems (e.g. a conversion into XML fails or the message's content is not serializable).

QOS_LARS_FAILURE

public static final int QOS_LARS_FAILURE
Reply is wished, if the lars routing mechanism has an internal error.

QOS_WRONG_RECIPIENT

public static final int QOS_WRONG_RECIPIENT
Reply is wished in any case, where the recipient cannot be determined (QOS_GROUP_UNKNOWN or QOS_SERVICE_NOT_REGISTERED or QOS_RECEIVER_INVALID or QOS_RECEIVER_NOT_AVAILABLE).

QOS_ROUTING_FAILURE

public static final int QOS_ROUTING_FAILURE
Reply is wished in any case, where the recipient cannot be reached (QOS_WRONG_RECIPIENT or QOS_PLATFORM_NOT_REACHABLE or QOS_LIFETIME_EXCEEDS or QOS_MESSENGER_NOT_CONNECTED or QOS_REMOTE_MESSENGER_NOT_REACHABLE or QOS_MESSAGE_CONVERSION_FAILURE or QOS_LARS_FAILURE).

QOS_REPLY_ERROR

public static final int QOS_REPLY_ERROR
Reply is wished in case of any error (QOS_INTERPRET_FAILS or QOS_NO_INTERPRET_DUE_TO_SECURITY or QOS_ROUTING_FAILURE).

QOS_REPLY_ALWAYS

public static final int QOS_REPLY_ALWAYS
This quality of service denotes, that always a reply message shall be sent. This includes as well the case of an error (see QOS_REPLY_ERROR) as also the case, that the receiving agent did not generate a reply (replyCounter == 0) after finishing his interpret() call.

descriptionMap

public static Map descriptionMap
for easy conversion of quality constants into Strings

constantMap

public static Map constantMap
for easy conversion of Strings into quality constants
Constructor Detail

QualityOfService

public QualityOfService()
Method Detail

isReplyNeeded

public static boolean isReplyNeeded(int qos,
                                    int failureReasonToCheck)
returns true, if a reply is needed for the specified quality of service and failure reason
Parameters:
qos - quality of service
failureReasonToCheck - reason to check
Returns:
true, if a reply is needed in case of failureReasonToCheck with the given quality of service

createReply

public static SingleMessage createReply(Message message,
                                        String serviceOfReply,
                                        int failureCode,
                                        String reasonDescription,
                                        String messengerOfFailure)
Checks quality of service of the given message and the given failureCode and determines therefrom, if an error notification needs to be sent to the originator of the message. If yes, it creates that error notification with the given service, which contains a map representation of the original message in its content. If the generated reply has a valid receiver (see SingleMessage.hasInvalidReceiver()), the reply is returned.
Parameters:
message - message that caused the failure
serviceOfReply - service to use in the reply message
failureCode - code of the failure (see QualityOfService)
reasonDescription - contains the textual description of the reason for the failure
messengerOfFailure - messenger, where the failure occurred (may be null)
Returns:
null, if no error notification is needed; else the error notification message

getDescription

public static String getDescription(int qos)
converts the given int representation of a quality of service into a string.
Parameters:
qos - the quality of service
Returns:
string representation of the qos argument

getDetailedDescription

public static String getDetailedDescription(int qos)
converts the given int representation of a quality of service into a string with the most detailed constants contained in the given qos
Parameters:
qos - the quality of service
Returns:
string representation of the qos argument

getConstant

public static int getConstant(String qos)
                       throws IllegalArgumentException
returns the int value of the given quality of service
Parameters:
qos - a string representation of a quality of service
Returns:
an int value of the given quality of service
Throws:
IllegalArgumentException - if the given string does not represent a quality of service

main

public static void main(String[] args)
prints to System.out the translation of the given quality of service constants
Parameters:
args - int or String representations of quality of service constants coming from the command line