Interface ITopic<E>

  • Type Parameters:
    E - the type of the message
    All Superinterfaces:
    DistributedObject

    public interface ITopic<E>
    extends DistributedObject
    Hazelcast provides distribution mechanism for publishing messages that are delivered to multiple subscribers, which is also known as a publish/subscribe (pub/sub) messaging model. Publish and subscriptions are cluster-wide.

    When a member subscribes for a topic, it is actually registering for messages published by any member in the cluster, including the new members joined after you added the listener.

    Messages are ordered, meaning that listeners(subscribers) will process the messages in the order they are actually published. If cluster member M publishes messages m1, m2, m3...mn to a topic T, then Hazelcast makes sure that all of the subscribers of topic T will receive and process m1, m2, m3...mn in order.

    Since Hazelcast 3.5 it is possible to have reliable topics. Normally all topics rely on the shared eventing system and shared threads. With Hazelcast 3.5 it is possible to configure a topic to be reliable and to get its own Ringbuffer to store events and to get its own executor to process events. The events in the ringbuffer are replicated, so they won't get lost when a node goes down.

    • Method Detail

      • getName

        java.lang.String getName()
        Returns the name of this ITopic instance.
        Specified by:
        getName in interface DistributedObject
        Returns:
        name of this ITopic instance
      • publish

        void publish​(@Nonnull
                     E message)
        Publishes the message to all subscribers of this topic.
        Parameters:
        message - the message to publish to all subscribers of this topic
        Throws:
        TopicOverloadException - if the consumer is too slow (only works in combination with reliable topic)
      • publishAsync

        java.util.concurrent.CompletionStage<java.lang.Void> publishAsync​(@Nonnull
                                                                          E message)
        Publishes the message asynchronously to all subscribers of this topic.
        Parameters:
        message - the message to publish asynchronously to all subscribers of this topic
        Returns:
        the CompletionStage to synchronize on completion.
      • addMessageListener

        @Nonnull
        java.util.UUID addMessageListener​(@Nonnull
                                          MessageListener<E> listener)
        Subscribes to this topic. When a message is published, the MessageListener.onMessage(Message) method of the given MessageListener is called. More than one message listener can be added on one instance. See ReliableMessageListener to better integrate with a reliable topic.
        Parameters:
        listener - the MessageListener to add
        Returns:
        returns the registration ID
        Throws:
        java.lang.NullPointerException - if listener is null
      • removeMessageListener

        boolean removeMessageListener​(@Nonnull
                                      java.util.UUID registrationId)
        Stops receiving messages for the given message listener.

        If the given listener already removed, this method does nothing.

        Parameters:
        registrationId - ID of listener registration
        Returns:
        true if registration is removed, false otherwise
      • getLocalTopicStats

        @Nonnull
        LocalTopicStats getLocalTopicStats()
        Returns statistics about this topic, like total number of publishes/receives. The statistics are local to this member and represent the activity on this member, not the entire cluster.
        Returns:
        statistics about this topic
      • publishAll

        void publishAll​(@Nonnull
                        java.util.Collection<? extends E> messages)
                 throws java.util.concurrent.ExecutionException,
                        java.lang.InterruptedException
        Publishes all messages to all subscribers of this topic.
        Parameters:
        messages - the messages to publish to all subscribers of this topic
        Throws:
        TopicOverloadException - if the consumer is too slow (only works in combination with reliable topic)
        java.util.concurrent.ExecutionException
        java.lang.InterruptedException
      • publishAllAsync

        java.util.concurrent.CompletionStage<java.lang.Void> publishAllAsync​(@Nonnull
                                                                             java.util.Collection<? extends E> messages)
        Publishes all messages asynchronously to all subscribers of this topic.
        Parameters:
        messages - the messages to publish asynchronously to all subscribers of this topic
        Returns:
        the CompletionStage to synchronize on completion.