Merge pull request iluwatar#544 from kemitix/data-bus

[WIP] Data Bus

Author: iluwatar

data-bus/.gitignore

@@ -0,0 +1 @@
+/target

data-bus/README.md

@@ -0,0 +1,33 @@
+---
+layout: pattern
+title: Data Bus
+folder: data-bus
+permalink: /patterns/data-bus/
+
+categories: Architectural
+tags:
+ - Java
+ - Difficulty-Intermediate
+---
+
+## Intent
+
+Allows send of messages/events between components of an application
+without them needing to know about each other. They only need to know
+about the type of the message/event being sent.
+
+![data bus pattern uml diagram](./etc/data-bus.urm.png "Data Bus pattern")
+
+## Applicability
+Use Data Bus pattern when
+
+* you want your components to decide themselves which messages/events they want to receive
+* you want to have many-to-many communication
+* you want your components to know nothing about each other
+
+## Related Patterns
+Data Bus is similar to
+
+* Mediator pattern with Data Bus Members deciding for themselves if they want to accept any given message
+* Observer pattern but supporting many-to-many communication
+* Publish/Subscribe pattern with the Data Bus decoupling the publisher and the subscriber

data-bus/etc/data-bus.urm.png

@@ -0,0 +1,77 @@
+@startuml
+package com.iluwatar.databus {
+  class AbstractDataType {
+    - dataBus : DataBus
+    + AbstractDataType()
+    + getDataBus() : DataBus
+    + setDataBus(dataBus : DataBus)
+  }
+  ~class App {
+    - log : Logger {static}
+    ~ App()
+    + main(args : String[]) {static}
+  }
+  class DataBus {
+    - INSTANCE : DataBus {static}
+    - listeners : Set<Member>
+    + DataBus()
+    + getInstance() : DataBus {static}
+    + publish(event : DataType)
+    + subscribe(member : Member)
+    + unsubscribe(member : Member)
+  }
+  interface DataType {
+    + getDataBus() : DataBus {abstract}
+    + setDataBus(DataBus) {abstract}
+  }
+  interface Member {
+    + accept(DataType) {abstract}
+  }
+}
+package com.iluwatar.databus.data {
+  class MessageData {
+    - message : String
+    + MessageData(message : String)
+    + getMessage() : String
+    + of(message : String) : DataType {static}
+  }
+  class StartingData {
+    - when : LocalDateTime
+    + StartingData(when : LocalDateTime)
+    + getWhen() : LocalDateTime
+    + of(when : LocalDateTime) : DataType {static}
+  }
+  class StoppingData {
+    - when : LocalDateTime
+    + StoppingData(when : LocalDateTime)
+    + getWhen() : LocalDateTime
+    + of(when : LocalDateTime) : DataType {static}
+  }
+}
+package com.iluwatar.databus.members {
+  class CounterMember {
+    - log : Logger {static}
+    - name : String
+    + CounterMember(name : String)
+    + accept(data : DataType)
+    - handleEvent(data : MessageData)
+  }
+  class StatusMember {
+    - id : int
+    - log : Logger {static}
+    + StatusMember(id : int)
+    + accept(data : DataType)
+    - handleEvent(data : StartingData)
+    - handleEvent(data : StoppingData)
+  }
+}
+AbstractDataType -->  "-dataBus" DataBus
+DataBus -->  "-INSTANCE" DataBus
+DataBus -->  "-listeners" Member
+AbstractDataType ..|> DataType 
+MessageData --|> AbstractDataType 
+StartingData --|> AbstractDataType 
+StoppingData --|> AbstractDataType 
+CounterMember ..|> Member 
+StatusMember ..|> Member 
+@enduml

data-bus/etc/data-bus.urm.puml

@@ -0,0 +1,51 @@
+<?xml version="1.0"?>
+<!--
+
+    The MIT License
+    Copyright (c) 2014-2016 Ilkka Seppälä
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in
+    all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+    THE SOFTWARE.
+
+-->
+<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"
+         xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+    <modelVersion>4.0.0</modelVersion>
+    <properties>
+        <lombok.version>1.16.14</lombok.version>
+    </properties>
+    <parent>
+        <groupId>com.iluwatar</groupId>
+        <artifactId>java-design-patterns</artifactId>
+        <version>1.16.0-SNAPSHOT</version>
+    </parent>
+    <artifactId>data-bus</artifactId>
+    <dependencies>
+        <dependency>
+            <groupId>junit</groupId>
+            <artifactId>junit</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-core</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+</project>

data-bus/pom.xml

@@ -0,0 +1,45 @@
+/*
+The MIT License (MIT)
+
+Copyright (c) 2016 Paul Campbell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+*/
+
+package com.iluwatar.databus;
+
+/**
+ * Base for data to send via the Data-Bus.
+ *
+ * @author Paul Campbell (pcampbell@kemitix.net)
+ */
+public class AbstractDataType implements DataType {
+
+  private DataBus dataBus;
+
+  @Override
+  public DataBus getDataBus() {
+    return dataBus;
+  }
+
+  @Override
+  public void setDataBus(DataBus dataBus) {
+    this.dataBus = dataBus;
+  }
+}

data-bus/src/main/java/com/iluwatar/databus/AbstractDataType.java

@@ -0,0 +1,79 @@
+/**
+ * The MIT License
+ * Copyright (c) 2014-2016 Ilkka Seppälä
+ * <p>
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * <p>
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ * <p>
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+package com.iluwatar.databus;
+
+import com.iluwatar.databus.data.MessageData;
+import com.iluwatar.databus.data.StartingData;
+import com.iluwatar.databus.data.StoppingData;
+import com.iluwatar.databus.members.MessageCollectorMember;
+import com.iluwatar.databus.members.StatusMember;
+
+import java.time.LocalDateTime;
+
+/**
+ * The Data Bus pattern
+ * <p>
+ * <p>{@see http://wiki.c2.com/?DataBusPattern}</p>
+ * <p>
+ * <p>The Data-Bus pattern provides a method where different parts of an application may
+ * pass messages between each other without needing to be aware of the other's existence.</p>
+ * <p>Similar to the {@code ObserverPattern}, members register themselves with the {@link DataBus}
+ * and may then receive each piece of data that is published to the Data-Bus. The member
+ * may react to any given message or not.</p>
+ * <p>It allows for Many-to-Many distribution of data, as there may be any number of
+ * publishers to a Data-Bus, and any number of members receiving the data. All members
+ * will receive the same data, the order each receives a given piece of data, is an
+ * implementation detail.</p>
+ * <p>Members may unsubscribe from the Data-Bus to stop receiving data.</p>
+ * <p>This example of the pattern implements a Synchronous Data-Bus, meaning that
+ * when data is published to the Data-Bus, the publish method will not return until
+ * all members have received the data and returned.</p>
+ * <p>The {@link DataBus} class is a Singleton.</p>
+ * <p>Members of the Data-Bus must implement the {@link Member} interface.</p>
+ * <p>Data to be published via the Data-Bus must implement the {@link DataType} interface.</p>
+ * <p>The {@code data} package contains example {@link DataType} implementations.</p>
+ * <p>The {@code members} package contains example {@link Member} implementations.</p>
+ * <p>The {@link StatusMember} demonstrates using the DataBus to publish a message
+ * to the Data-Bus when it receives a message.</p>
+ *
+ * @author Paul Campbell (pcampbell@kemitix.net)
+ */
+class App {
+
+  public static void main(String[] args) {
+    final DataBus bus = DataBus.getInstance();
+    bus.subscribe(new StatusMember(1));
+    bus.subscribe(new StatusMember(2));
+    final MessageCollectorMember foo = new MessageCollectorMember("Foo");
+    final MessageCollectorMember bar = new MessageCollectorMember("Bar");
+    bus.subscribe(foo);
+    bus.publish(StartingData.of(LocalDateTime.now()));
+    bus.publish(MessageData.of("Only Foo should see this"));
+    bus.subscribe(bar);
+    bus.publish(MessageData.of("Foo and Bar should see this"));
+    bus.unsubscribe(foo);
+    bus.publish(MessageData.of("Only Bar should see this"));
+    bus.publish(StoppingData.of(LocalDateTime.now()));
+  }
+}

data-bus/src/main/java/com/iluwatar/databus/App.java

@@ -0,0 +1,73 @@
+/**
+ * The MIT License
+ * Copyright (c) 2014-2016 Ilkka Seppälä
+ * <p>
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * <p>
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ * <p>
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+package com.iluwatar.databus;
+
+import java.util.HashSet;
+import java.util.Set;
+
+/**
+ * The Data-Bus implementation.
+ *
+ * <p>This implementation uses a Singleton.</p>
+ *
+ * @author Paul Campbell (pcampbell@kemitix.net)
+ */
+public class DataBus {
+
+  private static final DataBus INSTANCE = new DataBus();
+
+  private final Set<Member> listeners = new HashSet<>();
+
+  public static DataBus getInstance() {
+    return INSTANCE;
+  }
+
+  /**
+   * Register a member with the data-bus to start receiving events.
+   *
+   * @param member The member to register
+   */
+  public void subscribe(final Member member) {
+    this.listeners.add(member);
+  }
+
+  /**
+   * Deregister a member to stop receiving events.
+   *
+   * @param member The member to deregister
+   */
+  public void unsubscribe(final Member member) {
+    this.listeners.remove(member);
+  }
+
+  /**
+   * Publish and event to all members.
+   *
+   * @param event The event
+   */
+  public void publish(final DataType event) {
+    event.setDataBus(this);
+    listeners.forEach(listener -> listener.accept(event));
+  }
+}