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.
IBM WebSphere Application ServerTM
Release 9.0