com.ibm.websphere.sib.mediation.session

Interface SIMediationSession

public interface SIMediationSession

The SIMediationSession interface defines all the methods used by a mediation for querying and interacting with the service integration bus. It also includes methods that provide information on where the Mediation is being invoked from.

An instance of the SIMediationSession is only valid for a single invocation of a mediation and should not be cached. Attempts to make calls on the instance outside of the context of the mediation it was created, or from a different thread that the original mediation runs on will result in an IllegalStateException.

Security related checks are performed using the mediation's identity. The mediation's identity is the EJB run-as identity defined in the deployment descriptor for the mediation's session bean. If the EJB inherits the callers identity then the mediation identity is the identity defined in the bus administration panels as the mediation authentication alias.

Methods for which the security implications are not explicitly documented do not have any security considerations, do not check security permissions and do not affect any secured resources.

Method Summary

Methods

Modifier and Type	Method and Description
java.lang.String	getBusName() This method returns the name of the bus the Mediation is defined on.
java.lang.String	getDestinationName() This method returns the name of the Destination with which the Mediation is associated.
java.lang.String	getDiscriminator() This method returns the discriminator that is defined in the mediation definition.
java.lang.String	getMediationName() This method returns the name of the mediation that is being executed.
java.lang.String	getMessageSelector() This method returns the message selector that is defined in the mediation definition.
java.lang.String	getMessagingEngineName() This method returns the name of the messaging engine which the mediation point is assigned to.
SIDestinationConfiguration	getSIDestinationConfiguration(SIDestinationAddress destinationAddress) This method returns the SIDestinationConfiguration object associated with the specified Destination.
SIDestinationConfiguration	getSIDestinationConfiguration(java.lang.String destinationName) This method returns the SIDestinationConfiguration object associated with the specified Destination.
SIMessage	receive(SIDestinationAddress destinationAddress) This variant on receive will receive any message without any wait in the current unit of work.
SIMessage	receive(SIDestinationAddress destinationAddress, long timeout, java.lang.String discriminator, java.lang.String messageSelector, boolean autoCommit) This method receives an SIMessage from the Service integration bus.
SIMessage	receive(java.lang.String destinationName) This variant on receive will receive any message without any wait in the current unit of work.
SIMessage	receive(java.lang.String destinationName, long timeout, java.lang.String discriminator, java.lang.String messageSelector, boolean autoCommit) This method receives an SIMessage from the Service integration bus.
void	resetIdentity(SIMessage message) This method will change the identity of the given message to the mediation's identity.
void	send(SIMessage message, boolean autoCommit) This method will send an SIMessage to the Service integration bus.

Method Detail

getBusName

java.lang.String getBusName()

This method returns the name of the bus the Mediation is defined on.

Returns:

the bus name

getMessagingEngineName

java.lang.String getMessagingEngineName()

This method returns the name of the messaging engine which the mediation point is assigned to.

Returns:

the messaging engine name

getMediationName

java.lang.String getMediationName()

This method returns the name of the mediation that is being executed.

Returns:

the mediation name

getDestinationName

java.lang.String getDestinationName()

This method returns the name of the Destination with which the Mediation is associated.

Returns:

the destination name.

getDiscriminator

java.lang.String getDiscriminator()

This method returns the discriminator that is defined in the mediation definition. The message will be mediated if the topic discriminator in the message is accepted by this discriminator.

Returns:

the discriminator that the message matched.

getMessageSelector

java.lang.String getMessageSelector()

This method returns the message selector that is defined in the mediation definition. The message will be mediated if the message is accepted by this message selector.

Returns:

the messageSelector that the message matched.

getSIDestinationConfiguration

SIDestinationConfiguration getSIDestinationConfiguration(SIDestinationAddress destinationAddress)
                                                         throws SIDestinationNotFoundException,
                                                                SINotAuthorizedException,
                                                                SIMediationSessionException,
                                                                java.lang.NullPointerException,
                                                                java.lang.IllegalStateException

This method returns the SIDestinationConfiguration object associated with the specified Destination.

An SINotAuthorizedException will be thrown if any of the following condition is true:

• If the mediation's identity is not in the bus connector role.

Parameters:

destinationAddress - the address of the destination being queried.

Returns:

the SIDestinationConfiguration for the given Destination

Throws:

SIDestinationNotFoundException - if the specified Destination does not exist.

SINotAuthorizedException - if the authorization check fails.

SIMediationSessionException - if some form of exception occurs while quering the SI Bus.

java.lang.NullPointerException - if the destination address is null.

java.lang.IllegalStateException - if the method has been called after the mediation it was created for has completed, or if it has been called from a thread other than the one that invoked the mediation.

getSIDestinationConfiguration

SIDestinationConfiguration getSIDestinationConfiguration(java.lang.String destinationName)
                                                         throws SIDestinationNotFoundException,
                                                                SINotAuthorizedException,
                                                                SIMediationSessionException,
                                                                java.lang.NullPointerException,
                                                                java.lang.IllegalStateException

This method returns the SIDestinationConfiguration object associated with the specified Destination.

An SINotAuthorizedException will be thrown if any of the following condition is true:

• If the mediation's identity is not in the bus connector role.

Parameters:

destinationName - the name of the destination being queried.

Returns:

the SIDestinationConfiguration for the given Destination

Throws:

SIDestinationNotFoundException - if the specified Destination does not exist.

SINotAuthorizedException - if the authorization check fails.

SIMediationSessionException - if some form of exception occurs while quering the SI Bus.

java.lang.NullPointerException - if the destination name is null

java.lang.IllegalStateException - if the method has been called after the mediation it was created for has completed, or if it has been called from a thread other than the one that invoked the mediation.

send

void send(SIMessage message,
        boolean autoCommit)
          throws SIMediationRoutingException,
                 SIDestinationNotFoundException,
                 SINotAuthorizedException

This method will send an SIMessage to the Service integration bus. The message gets sent to the first Destination listed in the forward routing path of the sent message. If the message contains an empty forward routing path the message will be made available to consumers listening at the destination being mediated without the message itself being mediated.

An SINotAuthorizedException will be thrown if any of the following conditions are true:

• If the mediation's identity is not in the bus connector role.
• If the mediation's identity is not in the sender role for the destination at the head of the message's forward routing path.

Parameters:

message - the message to be sent.

autoCommit - Whether to send the message in the current unit of work or not.

• true if the message should be sent outside the current transaction. This has the effect of suspending the current transaction, sending the message and then resuming the transaction. If the mediations transaction is rolledback the message will still be available to consumers.
• false if the message should be sent inside the current transaction.

Throws:

SIMediationRoutingException - if an error occurs while sending the message.

SIDestinationNotFoundException - if the Destination at the head of the Forward Routing Path does not exist.

SINotAuthorizedException - if the authorization checks fails.

java.lang.IllegalStateException - if the method has been called after the mediation it was created for has completed, or if it has been called from a thread other than the one that invoked the mediation.

receive

SIMessage receive(java.lang.String destinationName,
                long timeout,
                java.lang.String discriminator,
                java.lang.String messageSelector,
                boolean autoCommit)
                  throws SIMediationRoutingException,
                         SIDestinationNotFoundException,
                         SINotAuthorizedException,
                         java.lang.NullPointerException

This method receives an SIMessage from the Service integration bus. The message is received from the specified Destination Name. If no message is found within the specified timeout then null will be returned. Unlike other APIs a timeout of zero means receive with no wait.

It should be noted that if the named Destination is a TopicSpace type Destination then the receive will have the effect of doing a subscribe followed by a receive followed by an unsubscribe.

An SINotAuthorizedException will be thrown if any of the following conditions are true:

• If the mediation's identity is not in the bus connector role.
• If the mediation's identity is not in the receiver role for the destination.

Parameters:

destinationName - The name of the destination to receive a message from.

timeout - The minimum length of time to wait for a message. Unlike many API calls a timeout of zero means receive with no wait. This is because Mediations are not long running so should not wait indefinatly.

discriminator - The topic discriminator to be used to receive the message.

messageSelector - The message selector to be used to receive the message.

autoCommit - Whether to receive the message in the current unit of work or not.

• true if the message should be sent outside the current transaction. This has the effect of suspending the current transaction, receiving a message and then resuming the transaction. This means that if the mediations transaction is rolledback the message will not be received again.
• false if the message should be received inside the current transaction.

Returns:

the received message

Throws:

SIMediationRoutingException - if an error occurs while sending the message

SIDestinationNotFoundException - if the Destination specified does not exist.

SINotAuthorizedException - if the authorization checks fails.

java.lang.NullPointerException - if the destination name is null

java.lang.IllegalStateException - if the method has been called after the mediation it was created for has completed, or if it has been called from a thread other than the one that invoked the mediation.

receive

SIMessage receive(java.lang.String destinationName)
                  throws SIMediationRoutingException,
                         SIDestinationNotFoundException,
                         SINotAuthorizedException,
                         java.lang.NullPointerException

This variant on receive will receive any message without any wait in the current unit of work.

This method has the effect of calling receive(destinationName, 0, null, null, false);

An SINotAuthorizedException will be thrown if any of the following conditions are true:

• If the mediation's identity is not in the bus connector role.
• If the mediation's identity is not in the receiver role for the destination.

Parameters:

destinationName - The name of the destination to receive a message from.

Returns:

the received message

Throws:

SIMediationRoutingException - if an error occurs while sending the message

SIDestinationNotFoundException - if the Destination specified does not exist.

SINotAuthorizedException - if the authorization checks fails.

java.lang.NullPointerException - if the destination name is null

java.lang.IllegalStateException - if the method has been called after the mediation it was created for has completed, or if it has been called from a thread other than the one that invoked the mediation.

receive

SIMessage receive(SIDestinationAddress destinationAddress,
                long timeout,
                java.lang.String discriminator,
                java.lang.String messageSelector,
                boolean autoCommit)
                  throws SIMediationRoutingException,
                         SIDestinationNotFoundException,
                         SINotAuthorizedException

This method receives an SIMessage from the Service integration bus. The message is received from the specified Destination Name. If no message is found within the specified timeout then null will be returned. Unlike other APIs a timeout of zero means receive with no wait.

It should be noted that if the named Destination is a TopicSpace type Destination then the receive will have the effect of doing a subscribe followed by a receive followed by an unsubscribe.

An SINotAuthorizedException will be thrown if any of the following conditions are true:

• If the mediation's identity is not in the bus connector role.
• If the mediation's identity is not in the receiver role for the destination.

Parameters:

destinationAddress - The name of the destination to receive a message from.

timeout - The minimum length of time to wait for a message. Unlike many API calls a timeout of zero means receive with no wait. This is because Mediations are not long running so should not wait indefinatly.

discriminator - The topic discriminator to be used to receive the message.

messageSelector - The message selector to be used to receive the message.

autoCommit - Whether to receive the message in the current unit of work or not.

• true if the message should be sent outside the current transaction. This has the effect of suspending the current transaction, receiving a message and then resuming the transaction. This means that if the mediations transaction is rolledback the message will not be received again.
• false if the message should be received inside the current transaction.

Returns:

the received message

Throws:

SIMediationRoutingException - if an error occurs while sending the message

SIDestinationNotFoundException - if the Destination specified does not exist.

SINotAuthorizedException - if the authorization checks fails.

java.lang.NullPointerException - if the destination name is null

java.lang.IllegalStateException - if the method has been called after the mediation it was created for has completed, or if it has been called from a thread other than the one that invoked the mediation.

receive

SIMessage receive(SIDestinationAddress destinationAddress)
                  throws SIMediationRoutingException,
                         SIDestinationNotFoundException,
                         SINotAuthorizedException

This variant on receive will receive any message without any wait in the current unit of work.

This method has the effect of calling receive(destinationName, 0, null, null, false);

An SINotAuthorizedException will be thrown if any of the following conditions are true:

• If the mediation's identity is not in the bus connector role.
• If the mediation's identity is not in the receiver role for the destination.

Parameters:

destinationAddress - The name of the destination to receive a message from.

Returns:

the received message

Throws:

SIMediationRoutingException - if an error occurs while sending the message

SIDestinationNotFoundException - if the Destination specified does not exist.

SINotAuthorizedException - if the authorization checks fails.

java.lang.IllegalStateException - if the method has been called after the mediation it was created for has completed, or if it has been called from a thread other than the one that invoked the mediation.

resetIdentity

void resetIdentity(SIMessage message)
                   throws SIMediationSessionException

This method will change the identity of the given message to the mediation's identity. It is important to note that a send call on the SIMediationSession includes an implicit resetIdentity.

The intention of this method is that the message that is routed on after the MediationHandler returns true will be forwarded on using the mediation's identity after this call completes.

When this method is called on the message being mediated it modifies the identity used for future access checks as that message travels through the bus. The identity in the message must be in the sender role for the destinations on the forward routing path. If the message has a forward routing path containing destinations the mediation's identity does not have access to they will be routed to the exception destination instead.

Parameters:

message - the message whose identity should be changed.

Throws:

SIMediationSessionException - thrown if there is an error changing the identity.