Class EfsSubscribeStatus.Builder<E extends IEfsEvent>

java.lang.Object
org.efs.bus.EfsSubscribeStatus.Builder<E>
Type Parameters:
E - efs event class.
All Implemented Interfaces:
IEfsEventBuilder<EfsSubscribeStatus<E>>
Enclosing class:
EfsSubscribeStatus<E extends IEfsEvent>
public static final class EfsSubscribeStatus.Builder<E extends IEfsEvent> extends Object implements IEfsEventBuilder<EfsSubscribeStatus<E>>
Builder for constructing EfsSubscribeStatus events.

Purpose:
Builder is used to construct EfsSubscribeStatus events sent to publishing agents to inform them of the current subscriber count for a given type+topic key. Publishers receive these status updates when subscribers join or leave a topic, allowing them to manage publishing resources efficiently.

Immutability and Thread Safety:

While the builder itself is not thread-safe, the resulting EfsSubscribeStatus events are immutable and fully thread-safe. It is recommended that a new builder be used for each new event rather than re-using a builder across multiple events.

Fluent API:

All setter methods return this to enable method chaining: 


 EfsSubscribeStatus<MyEvent> status = EfsSubscribeStatus.builder()
     .topicKey(myTopicKey)
     .previousSubscribers(5)
     .activeSubscribers(7)
     .build();

Required Fields:

The following fields must be set before calling build():

  • topicKey: Status applies to this type+topic key.
  • previousSubscribers: Previous subscriber count (≥ 0)
  • activeSubscribers: Current active subscriber count (≥ 0)

If any required field is not set, build() throws a ValidationException.

Basic Usage Example


 // Create a builder
 EfsSubscribeStatus.Builder<OrderEvent> builder = EfsSubscribeStatus.builder();

 // Set the topic
 builder.topicKey(EfsTopicKey.getKey(OrderEvent.class, "orders"));

 // Set subscriber counts when a new subscriber joins
 builder.previousSubscribers(5);   // Was 5 subscribers
 builder.activeSubscribers(6);     // Now 6 subscribers

 // Build the status event
 EfsSubscribeStatus<OrderEvent> status = builder.build();

Use Case 1: Tracking Growing Subscriber Interest

A publisher can use the status updates to decide whether to allocate more resources for publishing: 


 private void handleSubscriberStatusChange(EfsSubscribeStatus<SensorEvent> status) {
     int previous = status.previousSubscribers();
     int active = status.activeSubscribers();

     // Subscribers added
     if (active > previous) {
         System.out.println("Subscribers increased from " + previous + " to " + active);
         allocatePublishingResources();

     // Subscribers removed
     } else if (active < previous) {
         System.out.println("Subscribers decreased from " + previous + " to " + active);

         if (active == 0) {
             System.out.println("No more subscribers, stopping publisher");
             stopPublisher();
         }
     }
 }

Use Case 2: Event Bus Publishing Flow

When a publisher advertises a type+topic key, this builder is used internally by the event bus to construct status events sent back to the publisher: 


 // Inside EfsEventBus.TopicFeed (internal usage)
 private void forwardSubscribeStatus(final int previousCount, final int activeCount) {
     if (!mPublishers.isEmpty()) {
         final EfsSubscribeStatus.Builder<E> builder =
             EfsSubscribeStatus.builder();
         final EfsSubscribeStatus<E> status =
             builder.topicKey(mTopicKey)
                    .previousSubscribers(previousCount)
                    .activeSubscribers(activeCount)
                    .build();

         // Dispatch to all publishers
         for (Advertisement<E> ad : mPublishers.values()) {
             ad.forwardSubscribeStatus(status);
         }
     }
 }

Use Case 3: Method Chaining Pattern

Take full advantage of the fluent API for concise and readable code: 


 // Clean, readable one-liner
 EfsSubscribeStatus<PaymentEvent> status = EfsSubscribeStatus.builder()
     .topicKey(EfsTopicKey.getKey(PaymentEvent.class, "payments/processing"))
     .previousSubscribers(10)
     .activeSubscribers(12)
     .build();

 // Different approach: step-by-step
 EfsSubscribeStatus.Builder<PaymentEvent> builder = EfsSubscribeStatus.builder();
 builder.topicKey(paymentTopic);
 if (newSubscriberJoined()) {
     builder.previousSubscribers(currentCount - 1);
     builder.activeSubscribers(currentCount);
 }
 EfsSubscribeStatus<PaymentEvent> status = builder.build();

Validation Behavior:

When build() is called, the builder validates:

Error Examples: 


 // Error: topicKey not set
 try {
     EfsSubscribeStatus<MyEvent> status = EfsSubscribeStatus.builder()
         .previousSubscribers(5)
         .activeSubscribers(6)
         .build();
 } catch (ValidationException e) {
     // topicKey is required
 }

 // Error: negative subscriber count
 try {
     EfsSubscribeStatus<MyEvent> status = EfsSubscribeStatus.builder()
         .topicKey(myTopic)
         .previousSubscribers(-1)  // Invalid!
         .activeSubscribers(5)
         .build();
 } catch (IllegalArgumentException e) {
     System.out.println(e.getMessage()); // "subscriber count < 0"
 }

 // Error: null topic key
 try {
     EfsSubscribeStatus<MyEvent> status = EfsSubscribeStatus.builder()
         .topicKey(null)  // Invalid!
         .previousSubscribers(5)
         .activeSubscribers(6)
         .build();
 } catch (NullPointerException e) {
     // topicKey is null
 }
Author:
Charles W. Rapp
See Also:

  • Method Details

    • build

      public EfsSubscribeStatus<E> build()
      Returns a new EfsSubscribeStatus event based on this builder's settings.
      Specified by:
      build in interface IEfsEventBuilder<E extends IEfsEvent>
      Returns:
      new EfsSubscribeStatus event.
      Throws:
      net.sf.eBus.util.ValidationException - if this builder's setting are incorrectly set.

    • topicKey

      public EfsSubscribeStatus.Builder<E> topicKey(@Nonnull EfsTopicKey<E> topicKey)
      Sets topic key to given value.
      Parameters:
      topicKey - subscribe status event is for this topic key.
      Returns:
      this Builder instance.
      Throws:
      NullPointerException - if topicKey is null.

    • previousSubscribers

      public EfsSubscribeStatus.Builder<E> previousSubscribers(int n)
      Sets previous subscriber count to given value. This value must ≥ zero. There is no maximum value limit.
      Parameters:
      n - previous subscribers count.
      Returns:
      this Builder instance.
      Throws:
      IllegalArgumentException - if n < zero.

    • activeSubscribers

      public EfsSubscribeStatus.Builder<E> activeSubscribers(int n)
      Sets active subscriber count to given value. This value must ≥ zero. There is no maximum value limit.
      Parameters:
      n - active subscribers count.
      Returns:
      this Builder instance.
      Throws:
      IllegalArgumentException - if n < zero.