From 3f8702b17c541d91e9da7628e649837631b2fd38 Mon Sep 17 00:00:00 2001 From: kske Date: Mon, 23 Dec 2019 16:59:57 +0100 Subject: [PATCH] Added Javadoc for SettingsItem and SerializationUtils. --- src/main/java/envoy/client/SettingsItem.java | 54 +++++++++++++++++-- .../envoy/client/ui/PrimaryToggleSwitch.java | 9 ++-- .../envoy/client/util/SerializationUtils.java | 21 +++++++- 3 files changed, 76 insertions(+), 8 deletions(-) diff --git a/src/main/java/envoy/client/SettingsItem.java b/src/main/java/envoy/client/SettingsItem.java index 4c26201..287b6e9 100644 --- a/src/main/java/envoy/client/SettingsItem.java +++ b/src/main/java/envoy/client/SettingsItem.java @@ -10,11 +10,16 @@ import javax.swing.JComponent; import envoy.client.ui.PrimaryToggleSwitch; /** + * Encapsulates a persistent value that is directly or indirectly mutable by the + * user.
+ *
* Project: envoy-clientChess
* File: SettingsItem.java
* Created: 23.12.2019
* + * @param the type of this {@link SettingsItem}'s value * @author Kai S. K. Engelbart + * @since Envoy v0.3-alpha */ public class SettingsItem implements Serializable { @@ -32,17 +37,42 @@ public class SettingsItem implements Serializable { componentClasses.put(Boolean.class, PrimaryToggleSwitch.class); } + /** + * Initializes a {@link SettingsItem}. The default value's class will be mapped + * to a {@link JComponent} that can be used to display this {@link SettingsItem} + * to the user. + * + * @param value the default value + * @param userFriendlyName the user friendly name (short) + * @param description the description (long) + * @since Envoy v0.3-alpha + */ public SettingsItem(T value, String userFriendlyName, String description) { this(value, componentClasses.get(value.getClass())); this.userFriendlyName = userFriendlyName; this.description = description; } + /** + * Initializes a {@link SettingsItem}. The default value's class will be mapped + * to a specific {@link JComponent}. The mapping can also be disables if this + * parameter is {@code null}. In that case a {@link NullPointerException} will + * be thrown if the method {@link SettingsItem#getComponent()} is called. + * + * @param value the default value + * @param componentClass the class of the {@link JComponent} to represent this {@link SettingsItem} with + * @since Envoy v0.3-alpha + */ public SettingsItem(T value, Class componentClass) { this.value = value; this.componentClass = componentClass; } + /** + * @return an instance of the {@link JComponent} that represents this {@link SettingsItem} + * @throws ReflectiveOperationException if the component initialization failed + * @throws SecurityException if the component initialization failed + */ public JComponent getComponent() throws ReflectiveOperationException, SecurityException { if (componentClass == null) throw new NullPointerException("Component class is null"); return componentClass.getConstructor(SettingsItem.class).newInstance(this); @@ -50,50 +80,68 @@ public class SettingsItem implements Serializable { /** * @return the value + * @since Envoy v0.3-alpha */ public T get() { return value; } /** + * Changes the value of this {@link SettingsItem}. If a {@code ChangeHandler} if + * defined, it will be invoked with this value. + * * @param value the value to set + * @since Envoy v0.3-alpha */ public void set(T value) { - if(changeHandler != null && value != this.value) - changeHandler.accept(value); + if (changeHandler != null && value != this.value) changeHandler.accept(value); this.value = value; } /** * @return the componentClass + * @since Envoy v0.3-alpha */ public Class getComponentClass() { return componentClass; } /** * @param componentClass the componentClass to set + * @since Envoy v0.3-alpha */ public void setComponentClass(Class componentClass) { this.componentClass = componentClass; } /** * @return the userFriendlyName + * @since Envoy v0.3-alpha */ public String getUserFriendlyName() { return userFriendlyName; } /** * @param userFriendlyName the userFriendlyName to set + * @since Envoy v0.3-alpha */ public void setUserFriendlyName(String userFriendlyName) { this.userFriendlyName = userFriendlyName; } /** * @return the description + * @since Envoy v0.3-alpha */ public String getDescription() { return description; } /** * @param description the description to set + * @since Envoy v0.3-alpha */ public void setDescription(String description) { this.description = description; } /** + * Sets a {@code ChangeHandler} for this {@link SettingsItem}. It will be + * invoked with the current value once during the registration and every time + * when the value changes. + * * @param changeHandler the changeHandler to set + * @since Envoy v0.3-alpha */ - public void setChangeHandler(Consumer changeHandler) { this.changeHandler = changeHandler; changeHandler.accept(value); } + public void setChangeHandler(Consumer changeHandler) { + this.changeHandler = changeHandler; + changeHandler.accept(value); + } } \ No newline at end of file diff --git a/src/main/java/envoy/client/ui/PrimaryToggleSwitch.java b/src/main/java/envoy/client/ui/PrimaryToggleSwitch.java index 591f060..2882a05 100644 --- a/src/main/java/envoy/client/ui/PrimaryToggleSwitch.java +++ b/src/main/java/envoy/client/ui/PrimaryToggleSwitch.java @@ -9,8 +9,8 @@ import envoy.client.Settings; import envoy.client.SettingsItem; /** - * This Component can be used to toggle between two options. e.g. on and - * off.
+ * This component can be used to toggle between two options. This will change + * the state of a {@code boolean} {@link SettingsItem}.
*
* Project: envoy-client
* File: PrimaryToggleSwitch.java
@@ -27,9 +27,10 @@ public class PrimaryToggleSwitch extends JButton { private static final long serialVersionUID = -721155303106833184L; /** - * This is the constructor for the PrimaryToggleSwitch. + * Initializes a {@link PrimaryToggleSwitch}. * - * @param settingsItem + * @param settingsItem the {@link SettingsItem} that is controlled by this + * {@link PrimaryToggleSwitch} * @since Envoy v0.3-alpha */ public PrimaryToggleSwitch(SettingsItem settingsItem) { diff --git a/src/main/java/envoy/client/util/SerializationUtils.java b/src/main/java/envoy/client/util/SerializationUtils.java index 5a4b842..f0cc70f 100644 --- a/src/main/java/envoy/client/util/SerializationUtils.java +++ b/src/main/java/envoy/client/util/SerializationUtils.java @@ -10,11 +10,22 @@ import envoy.exception.EnvoyException; * Created: 23.12.2019
* * @author Kai S. K. Engelbart + * @since Envoy v0.3-alpha */ public class SerializationUtils { private SerializationUtils() {} + /** + * Deserializes an arbitrary {@link Serializable} object from a file. + * + * @param the type of the object to deserialize + * @param file the file deserialize from + * @param serializedClass the class of the object to deserialize + * @return the deserialized object + * @throws EnvoyException if an error occurred during deserialization + * @since Envoy v0.3-alpha + */ public static T read(File file, Class serializedClass) throws EnvoyException { if (file == null) throw new NullPointerException("File is null"); try (ObjectInputStream in = new ObjectInputStream(new FileInputStream(file))) { @@ -24,6 +35,14 @@ public class SerializationUtils { } } + /** + * Serializes an arbitrary object to a file. + * + * @param file the file to serialize to + * @param obj the object to serialize + * @throws IOException if an error occurred during serialization + * @since Envoy v0.3-alpha + */ public static void write(File file, Object obj) throws IOException { if (file == null) throw new NullPointerException("File is null"); if (obj == null) throw new NullPointerException("Object to serialize is null"); @@ -35,4 +54,4 @@ public class SerializationUtils { out.writeObject(obj); } } -} +} \ No newline at end of file