diff --git a/common/src/main/java/com/dfsek/terra/api/addons/TerraAddon.java b/common/src/main/java/com/dfsek/terra/api/addons/TerraAddon.java index 6fd5e6f82..c202f9e39 100644 --- a/common/src/main/java/com/dfsek/terra/api/addons/TerraAddon.java +++ b/common/src/main/java/com/dfsek/terra/api/addons/TerraAddon.java @@ -6,20 +6,39 @@ import com.dfsek.terra.api.addons.annotations.Author; import com.dfsek.terra.api.addons.annotations.Version; import org.jetbrains.annotations.NotNull; +/** + * Represents an entry point for an addon. Implementations must be annotated with {@link Addon}. + */ public abstract class TerraAddon { + /** + * Gets the version of this addon. + * + * @return Addon version. + */ public final @NotNull String getVersion() { Version version = getClass().getAnnotation(Version.class); return version == null ? "0.1.0" : version.value(); } + /** + * Gets the author of this addon. + * + * @return Addon author. + */ public final @NotNull String getAuthor() { Author author = getClass().getAnnotation(Author.class); return author == null ? "Anon Y. Mous" : author.value(); } + /** + * Gets the name (ID) of this addon. + * + * @return Addon ID. + */ public final @NotNull String getName() { Addon addon = getClass().getAnnotation(Addon.class); - if(addon == null) throw new IllegalStateException("Addon annotation not present"); // This should never happen; the presence of this annotation is checked by the addon loader. + if(addon == null) + throw new IllegalStateException("Addon annotation not present"); // This should never happen; the presence of this annotation is checked by the addon loader. return addon.value(); } diff --git a/common/src/main/java/com/dfsek/terra/api/event/EventListener.java b/common/src/main/java/com/dfsek/terra/api/event/EventListener.java index f5d3dcf60..cde546369 100644 --- a/common/src/main/java/com/dfsek/terra/api/event/EventListener.java +++ b/common/src/main/java/com/dfsek/terra/api/event/EventListener.java @@ -1,4 +1,12 @@ package com.dfsek.terra.api.event; +import com.dfsek.terra.api.event.events.Event; + +/** + * Marker interface for a class that contains event listener methods. + * + * @see Event + * @see EventManager + */ public interface EventListener { } diff --git a/common/src/main/java/com/dfsek/terra/api/event/EventManager.java b/common/src/main/java/com/dfsek/terra/api/event/EventManager.java index 96378ede4..de6ba0e19 100644 --- a/common/src/main/java/com/dfsek/terra/api/event/EventManager.java +++ b/common/src/main/java/com/dfsek/terra/api/event/EventManager.java @@ -3,13 +3,23 @@ package com.dfsek.terra.api.event; import com.dfsek.terra.api.addons.TerraAddon; import com.dfsek.terra.api.event.events.Event; +/** + * Manages event registration and triggering. + */ public interface EventManager { /** * Call an event, and return the execution status. + * * @param event Event to pass to all registered EventListeners. * @return False if the event is cancellable and has been cancelled, otherwise true. */ boolean callEvent(Event event); + /** + * Register an {@link EventListener} under an {@link TerraAddon}. + * + * @param addon Addon to register listener for. + * @param listener Listener to register. + */ void registerListener(TerraAddon addon, EventListener listener); } diff --git a/common/src/main/java/com/dfsek/terra/api/event/annotations/Global.java b/common/src/main/java/com/dfsek/terra/api/event/annotations/Global.java index 5084f527a..d162c00d9 100644 --- a/common/src/main/java/com/dfsek/terra/api/event/annotations/Global.java +++ b/common/src/main/java/com/dfsek/terra/api/event/annotations/Global.java @@ -1,12 +1,15 @@ package com.dfsek.terra.api.event.annotations; +import com.dfsek.terra.api.event.events.PackEvent; + import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Specifies that an event handler is to handle all events. + * Specifies that an event handler is to handle all {@link PackEvent}s, regardless of whether the pack + * depends on the addon's listener. */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) diff --git a/common/src/main/java/com/dfsek/terra/api/event/events/Cancellable.java b/common/src/main/java/com/dfsek/terra/api/event/events/Cancellable.java index bfac9adb2..ca7bccdf7 100644 --- a/common/src/main/java/com/dfsek/terra/api/event/events/Cancellable.java +++ b/common/src/main/java/com/dfsek/terra/api/event/events/Cancellable.java @@ -2,10 +2,21 @@ package com.dfsek.terra.api.event.events; /** * Events that implement this interface may be cancelled. - * + *

* Cancelling an event is assumed to stop the execution of whatever action triggered the event. */ public interface Cancellable extends Event { + /** + * Get the cancellation status of the event. + * + * @return Whether event is cancelled. + */ boolean isCancelled(); - void setCancelled(); + + /** + * Set the cancellation status of the event. + * + * @param cancelled Whether event is cancelled. + */ + void setCancelled(boolean cancelled); } diff --git a/common/src/main/java/com/dfsek/terra/api/event/events/Event.java b/common/src/main/java/com/dfsek/terra/api/event/events/Event.java index 2a65f4116..67d12a029 100644 --- a/common/src/main/java/com/dfsek/terra/api/event/events/Event.java +++ b/common/src/main/java/com/dfsek/terra/api/event/events/Event.java @@ -1,4 +1,7 @@ package com.dfsek.terra.api.event.events; +/** + * An event that addons may listen to. + */ public interface Event { } diff --git a/common/src/main/java/com/dfsek/terra/api/event/events/PackEvent.java b/common/src/main/java/com/dfsek/terra/api/event/events/PackEvent.java index adddf8b19..66f7b7d6c 100644 --- a/common/src/main/java/com/dfsek/terra/api/event/events/PackEvent.java +++ b/common/src/main/java/com/dfsek/terra/api/event/events/PackEvent.java @@ -1,8 +1,20 @@ package com.dfsek.terra.api.event.events; +import com.dfsek.terra.api.event.annotations.Global; import com.dfsek.terra.config.pack.ConfigPack; +/** + * An event with functionality directly linked to a {@link ConfigPack}. + *

+ * PackEvents are only invoked when the pack specifies the addon in its + * {@code addon} key (or when the listener is annotated {@link Global}). + */ @SuppressWarnings("InterfaceMayBeAnnotatedFunctional") public interface PackEvent extends Event { + /** + * Get the {@link ConfigPack} associated with this event. + * + * @return ConfigPack associated with the event. + */ ConfigPack getPack(); } diff --git a/common/src/main/java/com/dfsek/terra/api/event/events/config/ConfigPackLoadEvent.java b/common/src/main/java/com/dfsek/terra/api/event/events/config/ConfigPackLoadEvent.java index a6a4c5c12..7aa7ab8a4 100644 --- a/common/src/main/java/com/dfsek/terra/api/event/events/config/ConfigPackLoadEvent.java +++ b/common/src/main/java/com/dfsek/terra/api/event/events/config/ConfigPackLoadEvent.java @@ -3,6 +3,9 @@ package com.dfsek.terra.api.event.events.config; import com.dfsek.terra.api.event.events.PackEvent; import com.dfsek.terra.config.pack.ConfigPack; +/** + * An event related to the loading process of config packs. + */ public abstract class ConfigPackLoadEvent implements PackEvent { private final ConfigPack pack; diff --git a/common/src/main/java/com/dfsek/terra/api/injection/Injector.java b/common/src/main/java/com/dfsek/terra/api/injection/Injector.java index 8156ac142..c19a680fa 100644 --- a/common/src/main/java/com/dfsek/terra/api/injection/Injector.java +++ b/common/src/main/java/com/dfsek/terra/api/injection/Injector.java @@ -9,18 +9,51 @@ import java.lang.reflect.Modifier; import java.util.HashSet; import java.util.Set; +/** + * Dynamic dependency injector. + *

+ * Stores an object to inject, and injects it into objects passed to {@link #inject(Object)}. + * + * @param Type of object to inject. + */ public class Injector { private final T value; private final Set> targets = new HashSet<>(); + /** + * Instantiate an Injector with a value to inject + * + * @param value Value to inject + */ public Injector(T value) { this.value = value; } + /** + * Add an explicit class as a target. Useful for applications where subclasses may cause issues with DI. + * + * @param target Target class type. + */ public void addExplicitTarget(Class target) { targets.add(target); } + /** + * Inject the stored object into an object. + *

+ * Injects the stored object into any non-static, non-final fields + * annotated with {@link Inject}, + * with type matching the stored object or any explicit targets + * ({@link #addExplicitTarget(Class)}. + * + * @param object Object to inject into + * @throws InjectionException If: + *

+ */ public void inject(Object object) throws InjectionException { for(Field field : ReflectionUtil.getFields(object.getClass())) { Inject inject = field.getAnnotation(Inject.class); diff --git a/common/src/main/java/com/dfsek/terra/api/injection/exception/InjectionException.java b/common/src/main/java/com/dfsek/terra/api/injection/exception/InjectionException.java index 93e0d258c..314dd5e93 100644 --- a/common/src/main/java/com/dfsek/terra/api/injection/exception/InjectionException.java +++ b/common/src/main/java/com/dfsek/terra/api/injection/exception/InjectionException.java @@ -1,5 +1,10 @@ package com.dfsek.terra.api.injection.exception; +import com.dfsek.terra.api.injection.Injector; + +/** + * Thrown when dynamic dependency injection cannot be completed by an {@link Injector}. + */ public class InjectionException extends Exception { private static final long serialVersionUID = -6929631447064215387L;