Merge pull request #2 from 7orivorian/3.2.0

3.2.0

.gitignore

@@ -1,3 +1,4 @@
 /.idea/
 /target/
 /dependency-reduced-pom.xml
+/developer-docs/

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 7orivorian
+Copyright (c) 2021-2024 7orivorian
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -31,7 +31,7 @@ Lightweight Java event library created and maintained by [7orivorian](https://gi
 <dependency>
     <groupId>com.github.7orivorian</groupId>
     <artifactId>Wraith</artifactId>
-    <version>3.1.0</version>
+    <version>3.2.0</version>
 </dependency>
 ```
 
@@ -51,13 +51,13 @@ repositories {
 
 ```gradle
 dependencies {
-    implementation 'com.github.7orivorian:Wraith:3.1.0'
+    implementation 'com.github.7orivorian:Wraith:3.2.0'
 }
 ```
 
 ### Other
 
-Download a `.jar` file from [releases](https://github.com/7orivorian/Wraith/releases/tag/3.1.0)
+Download a `.jar` file from [releases](https://github.com/7orivorian/Wraith/releases/tag/3.2.0)
 
 # Building
 
@@ -66,11 +66,12 @@ Download a `.jar` file from [releases](https://github.com/7orivorian/Wraith/rele
 
 Packaged file can be found in the `target/` directory.
 
-# Usage
+# Quick-Start Guide
 
 While the code itself is thoroughly documented, here's a simple guide to help you get started with the latest features.
 
 ### Subscribers
+
 <details>
 <summary><i>Details...</i></summary>
 
@@ -95,11 +96,13 @@ public class ExampleSubscriber implements ISubscriber {
 Once you've defined your subscriber, you can subscribe it to an event bus directly within the subscriber's constructor:
 
 ```java
-public class ExampleSubscriber extends Subscriber {
+public class Consts {
     private static final IEventBus EVENT_BUS = new EventBus();
+}
+public class ExampleSubscriber extends Subscriber {
 
     public ExampleSubscriber() {
-        EVENT_BUS.subscribe(this);
+        Consts.EVENT_BUS.subscribe(this);
     }
 }
 ```
@@ -115,9 +118,11 @@ public class Example {
     }
 }
 ```
+
 </details>
 
 ### Defining Events
+
 <details>
 <summary><i>Details...</i></summary>
 
@@ -141,26 +146,10 @@ public class ExampleEvent {
 }
 ```
 
-To create a cancelable event, you can:
-
-Extend the Cancelable class:
-
-```java
-public class CancelableEvent extends Cancelable {
-// ...
-}
-```
-
-Implement the ICancelable interface:
-
-```java
-public class CancelableEvent implements ICancelable {
-// ...
-}
-```
 </details>
 
 ### Listeners
+
 <details>
 <summary><i>Details...</i></summary>
 
@@ -175,9 +164,7 @@ public class ExampleListener extends EventListener<ExampleEvent> {
 
     @Override
     public void invoke(ExampleEvent event) {
-        if (event.getStage() == EventStage.POST) {
-            event.setMessage("I feel wonderful!");
-        }
+        event.setMessage("Hello world!");
     }
 }
 ```
@@ -200,22 +187,20 @@ public class ExampleSubscriber extends Subscriber {
     public ExampleSubscriber() {
         // Register the listener
         registerListener(
-                new LambdaEventListener<>(ExampleEvent.class, event -> {
-                    if (event.getStage() == EventStage.PRE) {
-                        event.setMessage("Hello world!");
-                    }
-                })
+                new LambdaEventListener<>(ExampleEvent.class, event -> event.setMessage("Hello world!"))
         );
     }
 }
 ```
+
 </details>
 
 ### Dispatching Events
+
 <details>
 <summary><i>Details...</i></summary>
 
-To dispatch an event to an event bus, simply call one of the `dispatch` methods defined in any `IEventBus`
+To dispatch an event to an event bus, call one of the `dispatch` methods defined in any `IEventBus`
 implementation, passing your event as a parameter:
 
 ```java
@@ -227,19 +212,18 @@ public class Example {
 
     public static void main(String[] args) {
 
-        ExampleEvent event = new ExampleEvent("Initial message");
+        ExampleEvent event = new ExampleEvent("world greetings");
 
         EVENT_BUS.dispatch(event);
 
-        if (!event.isCanceled()) {
-            System.out.println(event.getMessage());
-        }
+        System.out.println(event.getMessage());
     }
 }
 ```
+
 </details>
 
-Feel free to explore the [example folder](examples/java/me/tori/example) for more Wraith implementations.
+Please explore the [example folder](./examples/java/me/tori/example) for _even more_ Wraith implementations!
 
 # Contributing
 
@@ -261,7 +245,7 @@ To make a contribution, follow these steps:
 
 # License
 
-[Wraith is licensed under MIT](src/main/resources/LICENSE.md)
+[Wraith is licensed under MIT](./LICENSE)
 
 ### MIT License Summary:
 

SECURITY.md

@@ -6,10 +6,6 @@
 |-----------|--------------------|
 | \>= 3.0.0 | :white_check_mark: |
 | 2.0.1     | :white_check_mark: |
-| 2.0.0     | :x:                |
-| < 2.0.0   | :x:                |
+| <= 2.0.0  | :x:                |
 
-## Reporting a Vulnerability
-
-Vulnerabilities can be reported by visiting the 'Security'
-tab on this repo and clicking 'Report a vulnerability'.
+[Report a vulnerability.](https://github.com/7orivorian/Wraith/security/advisories/new)

examples/java/me/tori/example/expanded/ExampleEvent.java

@@ -1,3 +1,24 @@
+/*
+ * Copyright (c) 2021-2024 7orivorian.
+ *
+ * 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 me.tori.example.expanded;
 
 import me.tori.wraith.event.cancelable.CancelableEvent;

examples/java/me/tori/example/expanded/ExampleListener.java

@@ -1,3 +1,24 @@
+/*
+ * Copyright (c) 2021-2024 7orivorian.
+ *
+ * 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 me.tori.example.expanded;
 
 import me.tori.wraith.event.staged.EventStage;

examples/java/me/tori/example/expanded/ExampleMain.java

@@ -1,3 +1,24 @@
+/*
+ * Copyright (c) 2021-2024 7orivorian.
+ *
+ * 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 me.tori.example.expanded;
 
 import me.tori.wraith.bus.EventBus;

examples/java/me/tori/example/expanded/ExampleSubscriber.java

@@ -1,3 +1,24 @@
+/*
+ * Copyright (c) 2021-2024 7orivorian.
+ *
+ * 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 me.tori.example.expanded;
 
 import me.tori.wraith.event.staged.EventStage;

examples/java/me/tori/example/persistence/PersistenceExample.java

@@ -0,0 +1,57 @@
+/*
+ * Copyright (c) 2021-2024 7orivorian.
+ *
+ * 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 me.tori.example.persistence;
+
+import me.tori.wraith.bus.EventBus;
+import me.tori.wraith.bus.IEventBus;
+import me.tori.wraith.listener.LambdaEventListener;
+import me.tori.wraith.subscriber.Subscriber;
+
+/**
+ * A simple example of listener persistence.
+ * <p>
+ * Last updated for version <b>3.1.0</b>
+ *
+ * @author <a href="https://github.com/7orivorian">7orivorian</a>
+ * @since 3.2.0
+ */
+class PersistenceExample {
+
+    private static final IEventBus EVENT_BUS = new EventBus();
+    private static final Subscriber SUBSCRIBER = new Subscriber() {{
+        // Register a listener that prints a single
+        // String event & is then removed from the event bus
+        registerListener(new LambdaEventListener<>(String.class, null, IEventBus.DEFAULT_PRIORITY, 1, System.out::println));
+    }};
+
+    public static void main(String[] args) {
+        // Subscribe our subscriber. This will never be removed from the event bus.
+        EVENT_BUS.subscribe(SUBSCRIBER);
+
+        // After this event is dispatched, and it's listener invoked,
+        // the listener will be removed since it's set to only persist once.
+        EVENT_BUS.dispatch("Hello world!");
+
+        // You can still dispatch events to remaining listeners.
+        EVENT_BUS.dispatch("I wont be printed :(");
+    }
+}

examples/java/me/tori/example/simple/SimpleExample.java

@@ -1,3 +1,24 @@
+/*
+ * Copyright (c) 2021-2024 7orivorian.
+ *
+ * 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 me.tori.example.simple;
 
 import me.tori.wraith.bus.EventBus;
@@ -7,7 +28,8 @@
 
 /**
  * One-class example
- * <p>Last updated for version <b>3.1.0</b>
+ * <p>
+ * Last updated for version <b>3.1.0</b>
  *
  * @author <b><a href="https://github.com/7orivorian">7orivorian</a></b>
  */