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 extends JComponent> 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 extends JComponent> getComponentClass() { return componentClass; }
/**
* @param componentClass the componentClass to set
+ * @since Envoy v0.3-alpha
*/
public void setComponentClass(Class extends JComponent> 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