com.usefulmilk.pubsub.package-info Maven / Gradle / Ivy
Show all versions of commons-pubsub Show documentation
/*
* Copyright 2016 UsefulMilk
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* This library is intended to follow publish–subscribe pattern.
*
* It has three main classes: {@link com.usefulmilk.pubsub.MilkPublisher},
* {@link com.usefulmilk.pubsub.MilkSubscriber} and {@link com.usefulmilk.pubsub.MilkMessage}.
*
* {@link com.usefulmilk.pubsub.MilkPublisher} intents to publish a MilkMessage.
* {@link com.usefulmilk.pubsub.MilkSubscriber} intents to listen MilkMessage. Actually,
* it is an abstract class and you have to implements it to handle the MilkMessage.
* {@link com.usefulmilk.pubsub.MilkMessage} is an abstract class where you can customize
* the message as you want. To send the message to the subscriber, you just need to
* call {@link com.usefulmilk.pubsub.MilkMessage#publish()}.
*
* The best way to show how it can be used is through an example.
* Let's consider an use case where we need to publish a domain event to know
* when a new user is created in our system. Keep in mind that each MilkMessage
* and each MilkSubscriber work together, if you create a new MilkMessage class,
* you will need to create a new MilkSubscriber class.
*
* It is a good practice to create UserCreatedEvent following method chaining syntax:
*
*
* public class UserCreatedEvent extends MilkMessage {
* private String userId;
* private String userName;
*
* public UserCreatedEvent(MilkPublisher milkPublisher) {
* super(milkPublisher);
* }
*
* public String userId() {
* return userId;
* }
*
* public UserCreatedEvent userId(String userId) {
* this.userId = userId;
* return this;
* }
*
* public String userName() {
* return userName;
* }
*
* public UserCreatedEvent userName(String userName) {
* this.userName = userName;
* return this;
* }
* }
*
*
* Once UserCreatedEvent was created, we need to create an specific MilkSubscriber<UserCreatedEvent>
* class to handle messages through handleMilkMessage(UserCreatedEvent milkMessage) method. We also
* add a String name in constructor to track this subscriber.
*
*
* public class UserCreatedEventSubscriber extends MilkSubscriber<UserCreatedEvent> {
* private String name;
*
* public UserCreatedEventSubscriber(String name) {
* super(UserCreatedEvent.class);
* this.name = name;
* }
*
* {@literal}@Override
* public void handleMilkMessage(UserCreatedEvent milkMessage) {
* System.out.println("Subscriber " + name + " received a new UserCreatedEvent:");
* System.out.println("\tuser id:" + milkMessage.userId());
* System.out.println("\tuser name:" + milkMessage.userName());
* System.out.println();
* }
* }
*
*
* Finally, we need to publish the message. Only instance of UserCreatedEventSubscriber
* will receive this message. Let's do it into main:
*
*
* public class Main {
* private static MilkPublisher publisher = new MilkPublisher();
*
* public static void main(String[] args) throws InterruptedException {
* UserCreatedEventSubscriber userCreatedEventSubscriber1 = new UserCreatedEventSubscriber("logger");
* UserCreatedEventSubscriber userCreatedEventSubscriber2 = new UserCreatedEventSubscriber("analytics");
*
* publisher.add(userCreatedEventSubscriber1);
* publisher.add(userCreatedEventSubscriber2);
*
* new UserCreatedEvent(publisher)
* .userId("1234")
* .userName("Paulo")
* .publish();
* }
* }
*
*
* The output:
*
*
* Subscriber logger received a new UserCreatedEvent:
* user id:1234
* user name:Paulo
*
* Subscriber analytics received a new UserCreatedEvent:
* user id:1234
* user name:Paulo
*
*/
package com.usefulmilk.pubsub;