ImaSubscription ("Eclipse Amlen" Javadoc Reference)

Package com.ibm.ima.jms

## Interface ImaSubscription

-     public interface ImaSubscription

  Allow access to shared subscriptions from JMS 1.1.

  JMS 2.0 adds the concept of shared subscriptions and the IBM MessageSight JMS client allows these methods to be accessed with a JMS 1.1 client using the ImaSubscription interface. The Session object returned by the IBM MssageSight JMS client implements the ImaSubscription interface which adds new methods for shared subscriptions. These methods match the design for the shared subscription support added in JMS 2.0.

  To use these methods you must cast the returned Session object to ImaSubscription:

       Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
       MessageConsumer consumer = ((ImaSubscription)session).createSharedConsumer(topic, "Subscription");

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static String` | `COPYRIGHT` |

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `javax.jms.MessageConsumer` | `createDurableConsumer​(javax.jms.Topic topic, String name)` | Creates a durable subscription and returns a message consumer over it.
    `javax.jms.MessageConsumer` | `createDurableConsumer​(javax.jms.Topic topic, String name, String selector, boolean noLocal)` | Creates a durable subscription and returns a message consumer over it.
    `javax.jms.MessageConsumer` | `createSharedConsumer​(javax.jms.Topic topic, String name)` | Creates a shared non-durable subscription and returns a message consumer over it.
    `javax.jms.MessageConsumer` | `createSharedConsumer​(javax.jms.Topic topic, String name, String selector)` | Creates a shared non-durable subscription and returns a message consumer over it.
    `javax.jms.MessageConsumer` | `createSharedDurableConsumer​(javax.jms.Topic topic, String name)` | Creates a shared durable subscription and returns a message consumer over it.
    `javax.jms.MessageConsumer` | `createSharedDurableConsumer​(javax.jms.Topic topic, String name, String selector)` | Creates a shared durable subscription and returns a message consumer over it.

- - ### Field Detail

    - #### COPYRIGHT

          static final String COPYRIGHT

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### createSharedConsumer

          javax.jms.MessageConsumer createSharedConsumer​(javax.jms.Topic topic,
                                                         String name)
                                                  throws javax.jms.JMSException

      Creates a shared non-durable subscription and returns a message consumer over it.

      Creates a shared non-durable subscription with the specified name on the specified topic (if one does not already exist) and creates a consumer on that subscription. This method creates the non-durable subscription without a message selector.

      If a shared non-durable subscription already exists with the same name and client identifier (if set), and the same topic and message selector has been specified, then this method creates a MessageConsumer on the existing subscription.

      A non-durable shared subscription is used by a client which needs to be able to share the work of receiving messages from a topic subscription amongst multiple consumers. A non-durable shared subscription may therefore have more than one consumer. Each message from the subscription will be delivered to only one of the consumers on that subscription. Such a subscription is not persisted and will be deleted (together with any undelivered messages associated with it) when there are no consumers on it. The term "consumer" here means a MessageConsumer object in any client.

      A shared non-durable subscription is identified by a name specified by the client and by the client identifier (which may be unset). An application which subsequently wishes to create a consumer on that shared non-durable subscription must use the same client identifier.

      If a shared non-durable subscription already exists with the same name and client identifier (if set) but a different topic or message selector has been specified, and there is a consumer already active (i.e. not closed) on the subscription, then a JMSException will be thrown.

      There is no restriction on durable subscriptions and shared non-durable subscriptions having the same name and clientId (which may be unset). Such subscriptions would be completely separate.

      Parameters:
        `topic` - - The topic to subscribe to
        `name` - - The subscription name
      Returns:
        A message consumer
      Throws:
        `javax.jms.JMSException` - -
        - if the name already exists but the topic or selector are different and there are already consumers,
        - if a nonshared non-durable subscription already exists with the same name
        - if the subscription or consumer cannot be created due to an internal error
        `javax.jms.InvalidDestinationException` - - if an invalid topic is specified
      Since:
        IBM MessageSight V1.1

    - #### createSharedConsumer

          javax.jms.MessageConsumer createSharedConsumer​(javax.jms.Topic topic,
                                                         String name,
                                                         String selector)
                                                  throws javax.jms.JMSException

      Creates a shared non-durable subscription and returns a message consumer over it.

      Creates a shared non-durable subscription with the specified name on the specified topic (if one does not already exist) specifying a message selector, and creates a consumer on that subscription.

      If a shared non-durable subscription already exists with the same name and client identifier (if set), and the same topic and message selector has been specified, then this method creates a MessageConsumer on the existing subscription.

      A non-durable shared subscription is used by a client which needs to be able to share the work of receiving messages from a topic subscription amongst multiple consumers. A non-durable shared subscription may therefore have more than one consumer. Each message from the subscription will be delivered to only one of the consumers on that subscription. Such a subscription is not persisted and will be deleted (together with any undelivered messages associated with it) when there are no consumers on it. The term "consumer" here means a MessageConsumer object in any client.

      A shared non-durable subscription is identified by a name specified by the client and by the client identifier (which may be unset). An application which subsequently wishes to create a consumer on that shared non-durable subscription must use the same client identifier.

      If a shared non-durable subscription already exists with the same name and client identifier (if set) but a different topic or message selector has been specified, and there is a consumer already active (i.e. not closed) on the subscription, then a JMSException will be thrown.

      There is no restriction on durable subscriptions and shared non-durable subscriptions having the same name and clientId (which may be unset). Such subscriptions would be completely separate.

      Parameters:
        `topic` - - The topic to subscribe to
        `name` - - The subscription name
        `selector` - - The message selector
      Returns:
        A message consumer
      Throws:
        `javax.jms.JMSException` - -
        - if the name already exists but the topic or selector are different and there are already consumers,
        - if a nonshared non-durable subscription already exists with the same name
        - if the subscription or consumer cannot be created due to an internal error
        `javax.jms.InvalidDestinationException` - - if an invalid topic is specified
        `javax.jms.InvalidSelectorException` - - if the message selector is not valid
      Since:
        IBM MessageSight V1.1

    - #### createSharedDurableConsumer

          javax.jms.MessageConsumer createSharedDurableConsumer​(javax.jms.Topic topic,
                                                                String name)
                                                         throws javax.jms.JMSException

      Creates a shared durable subscription and returns a message consumer over it.

      Creates a shared durable subscription on the specified topic (if one does not already exist), and creates a consumer on that durable subscription. This method creates the durable subscription without a message selector.

      A durable subscription is used by an application which needs to receive all the messages published on a topic, including the ones published when there is no active consumer associated with it. The JMS provider retains a record of this durable subscription and ensures that all messages from the topic's publishers are retained until they are delivered to, and acknowledged by, a consumer on this durable subscription or until they have expired.

      A durable subscription will continue to accumulate messages until it is deleted using the unsubscribe method.

      This method may only be used with shared durable subscriptions. Any durable subscription created using this method will be shared. This means that multiple active (i.e. not closed) consumers on the subscription may exist at the same time. The term "consumer" here means a MessageConsumer object in any client.

      A shared durable subscription is identified by a name specified by the client and by the client identifier (which may be unset). An application which subsequently wishes to create a consumer on that shared durable subscription must use the same client identifier.

      If a shared durable subscription already exists with the same name and client identifier (if set), and the same topic and message selector has been specified, then this method creates a MessageConsumer on the existing shared durable subscription.

      If a shared durable subscription already exists with the same name and client identifier (if set) but a different topic or message selector has been specified, and there is no consumer already active ( i.e. any existing consumers are closed) on the durable subscription then this is equivalent to unsubscribing (deleting) the old one and creating a new one.

      If a shared durable subscription already exists with the same name and client identifier (if set) but a different topic or message selector has been specified, and there is a consumer already active ( i.e. not closed) on the durable subscription, then a JMSException will be thrown.

      A shared durable subscription and an unshared durable subscription may not have the same name and client identifier (if set). If an unshared durable subscription already exists with the same name and client identifier (if set) then a JMSException is thrown.

      There is no restriction on durable subscriptions and shared non-durable subscriptions having the same name and clientId (which may be unset). Such subscriptions would be completely separate.

      Parameters:
        `topic` - - The topic to subscribe to
        `name` - - The subscription name
      Returns:
        A message consumer
      Throws:
        `javax.jms.JMSException` - -
        - if the name already exists but the topic or selector are different and there are already consumers,
        - if a nonshared durable subscription already exists with the same name
        - if the subscription or consumer cannot be created due to an internal error
        `javax.jms.InvalidDestinationException` - - if an invalid topic is specified
      Since:
        IBM MessageSight V1.1

    - #### createSharedDurableConsumer

          javax.jms.MessageConsumer createSharedDurableConsumer​(javax.jms.Topic topic,
                                                                String name,
                                                                String selector)
                                                         throws javax.jms.JMSException

      Creates a shared durable subscription and returns a message consumer over it.

      Creates a shared durable subscription on the specified topic (if one does not already exist), specifying a message selector, and creates a consumer on that durable subscription. This method creates the durable subscription with a message selector.

      A durable subscription is used by an application which needs to receive all the messages published on a topic, including the ones published when there is no active consumer associated with it. The JMS provider retains a record of this durable subscription and ensures that all messages from the topic's publishers are retained until they are delivered to, and acknowledged by, a consumer on this durable subscription or until they have expired.

      A durable subscription will continue to accumulate messages until it is deleted using the unsubscribe method.

      This method may only be used with shared durable subscriptions. Any durable subscription created using this method will be shared. This means that multiple active (i.e. not closed) consumers on the subscription may exist at the same time. The term "consumer" here means a MessageConsumer object in any client.

      A shared durable subscription is identified by a name specified by the client and by the client identifier (which may be unset). An application which subsequently wishes to create a consumer on that shared durable subscription must use the same client identifier.

      If a shared durable subscription already exists with the same name and client identifier (if set), and the same topic and message selector has been specified, then this method creates a MessageConsumer on the existing shared durable subscription.

      If a shared durable subscription already exists with the same name and client identifier (if set) but a different topic or message selector has been specified, and there is no consumer already active ( i.e. any existing consumers are closed) on the durable subscription then this is equivalent to unsubscribing (deleting) the old one and creating a new one.

      If a shared durable subscription already exists with the same name and client identifier (if set) but a different topic or message selector has been specified, and there is a consumer already active ( i.e. not closed) on the durable subscription, then a JMSException will be thrown.

      A shared durable subscription and an unshared durable subscription may not have the same name and client identifier (if set). If an unshared durable subscription already exists with the same name and client identifier (if set) then a JMSException is thrown.

      There is no restriction on durable subscriptions and shared non-durable subscriptions having the same name and clientId (which may be unset). Such subscriptions would be completely separate.

      Parameters:
        `topic` - - The topic to subscribe to
        `name` - - The subscription name
        `selector` - - The message selector
      Returns:
        A message consumer
      Throws:
        `javax.jms.JMSException` - -
        - if the name already exists but the topic or selector are different and there are already consumers,
        - if a nonshared durable subscription already exists with the same name
        - if the subscription or consumer cannot be created due to an internal error
        `javax.jms.InvalidDestinationException` - - if an invalid topic is specified
        `javax.jms.InvalidSelectorException` - - if the message selector is not valid
      Since:
        IBM MessageSight V1.1

    - #### createDurableConsumer

          javax.jms.MessageConsumer createDurableConsumer​(javax.jms.Topic topic,
                                                          String name)
                                                   throws javax.jms.JMSException

      Creates a durable subscription and returns a message consumer over it.

      Creates an unshared durable subscription on the specified topic (if one does not already exist) and creates a consumer on that durable subscription. This method creates the durable subscription without a message selector and with a noLocal value of false.

      A durable subscription is used by an application which needs to receive all the messages published on a topic, including the ones published when there is no active consumer associated with it. The JMS provider retains a record of this durable subscription and ensures that all messages from the topic's publishers are retained until they are delivered to, and acknowledged by, a consumer on this durable subscription or until they have expired.

      A durable subscription will continue to accumulate messages until it is deleted using the unsubscribe method.

      This method may only be used with unshared durable subscriptions. Any durable subscription created using this method will be unshared. This means that only one active (i.e. not closed) consumer on the subscription may exist at a time. The term "consumer" here means a TopicSubscriber or MessageConsumer object in any client.

      An unshared durable subscription is identified by a name specified by the client and by the client identifier, which must be set. An application which subsequently wishes to create a consumer on that unshared durable subscription must use the same client identifier.

      If an unshared durable subscription already exists with the same name and client identifier, and the same topic, message selector and noLocal value has been specified, and there is no consumer already active (i.e. any previously existing consumers are closed) on the durable subscription then this method creates a MessageConsumer on the existing durable subscription.

      If an unshared durable subscription already exists with the same name and client identifier, and there is a consumer already active (i.e. not closed) on the durable subscription, then a JMSException will be thrown.

      If an unshared durable subscription already exists with the same name and client identifier but a different topic, message selector or noLocal value has been specified, and there is no consumer already active (i.e. any previously existing consumers are closed) on the durable subscription then this is equivalent to unsubscribing (deleting) the old one and creating a new one.

      A shared durable subscription and an unshared durable subscription may not have the same name and client identifier. If a shared durable subscription already exists with the same name and client identifier then a JMSException is thrown.

      There is no restriction on durable subscriptions and shared non-durable subscriptions having the same name and clientId. Such subscriptions would be completely separate.

      This method is identical to the corresponding createDurableSubscriber method except that it returns a MessageConsumer rather than a TopicSubscriber to represent the consumer.

      Parameters:
        `topic` - - the topic to subscribe to
        `name` - - the subscription name
      Returns:
        A message consumer object
      Throws:
        `javax.jms.JMSException` - -
        - if an unshared durable subscription already exists with the same name and client identifier, and there is a consumer already active.
        - if a shared durable subscription already exists with the same name and client identifier
        - if the the subscription or MessageConsumer cannot be created due to some internal error
        `javax.jms.InvalidDestinationException` - - if an invalid topic is specified
        `IllegalStateException` - - if the client identifier is not set
      Since:
        IBM MessageSight v1.1

    - #### createDurableConsumer

          javax.jms.MessageConsumer createDurableConsumer​(javax.jms.Topic topic,
                                                          String name,
                                                          String selector,
                                                          boolean noLocal)
                                                   throws javax.jms.JMSException

      Creates a durable subscription and returns a message consumer over it.

      Creates an unshared durable subscription on the specified topic (if one does not already exist) specifying a message selector and the noLocal parameter, and creates a consumer on that durable subscription.

      A durable subscription is used by an application which needs to receive all the messages published on a topic, including the ones published when there is no active consumer associated with it. The JMS provider retains a record of this durable subscription and ensures that all messages from the topic's publishers are retained until they are delivered to, and acknowledged by, a consumer on this durable subscription or until they have expired.

      A durable subscription will continue to accumulate messages until it is deleted using the unsubscribe method.

      This method may only be used with unshared durable subscriptions. Any durable subscription created using this method will be unshared. This means that only one active (i.e. not closed) consumer on the subscription may exist at a time. The term "consumer" here means a TopicSubscriber or MessageConsumer object in any client.

      An unshared durable subscription is identified by a name specified by the client and by the client identifier, which must be set. An application which subsequently wishes to create a consumer on that unshared durable subscription must use the same client identifier.

      If an unshared durable subscription already exists with the same name and client identifier, and the same topic, message selector and noLocal value has been specified, and there is no consumer already active (i.e. any previously existing consumers are closed) on the durable subscription then this method creates a MessageConsumer on the existing durable subscription.

      If an unshared durable subscription already exists with the same name and client identifier, and there is a consumer already active (i.e. not closed) on the durable subscription, then a JMSException will be thrown.

      If an unshared durable subscription already exists with the same name and client identifier but a different topic, message selector or noLocal value has been specified, and there is no consumer already active (i.e. any previously existing consumers are closed) on the durable subscription then this is equivalent to unsubscribing (deleting) the old one and creating a new one.

      A shared durable subscription and an unshared durable subscription may not have the same name and client identifier. If a shared durable subscription already exists with the same name and client identifier then a JMSException is thrown.

      There is no restriction on durable subscriptions and shared non-durable subscriptions having the same name and clientId. Such subscriptions would be completely separate.

      This method is identical to the corresponding createDurableSubscriber method except that it returns a MessageConsumer rather than a TopicSubscriber to represent the consumer.

      Parameters:
        `topic` - - the topic to subscribe to
        `name` - - the subscription name
        `selector` - - the message selector
        `noLocal` - - if true then any messages published to the topic from a connection with the same client identifier will not be added to the durable subscription.
      Returns:
        A message consumer object
      Throws:
        `javax.jms.JMSException` - -
        - if an unshared durable subscription already exists with the same name and client identifier, and there is a consumer already active.
        - if a shared durable subscription already exists with the same name and client identifier
        - if the the subscription or MessageConsumer cannot be created due to some internal error
        `javax.jms.InvalidDestinationException` - - if an invalid topic is specified
        `IllegalStateException` - - if the client identifier is not set
        `javax.jms.InvalidSelectorException` - - if the message selector is not valid
      Since:
        IBM MessageSight v1.1