Added Javadoc for SettingsItem and SerializationUtils.

This commit is contained in:
Kai S. K. Engelbart 2019-12-23 16:59:57 +01:00
parent 5c7563a06b
commit f6d6ef0a3a
3 changed files with 76 additions and 8 deletions

View File

@ -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.<br>
* <br>
* Project: <strong>envoy-clientChess</strong><br>
* File: <strong>SettingsItem.java</strong><br>
* Created: <strong>23.12.2019</strong><br>
*
* @param <T> the type of this {@link SettingsItem}'s value
* @author Kai S. K. Engelbart
* @since Envoy v0.3-alpha
*/
public class SettingsItem<T> implements Serializable {
@ -32,17 +37,42 @@ public class SettingsItem<T> 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<T> 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<T> changeHandler) { this.changeHandler = changeHandler; changeHandler.accept(value); }
public void setChangeHandler(Consumer<T> changeHandler) {
this.changeHandler = changeHandler;
changeHandler.accept(value);
}
}

View File

@ -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.<br>
* This component can be used to toggle between two options. This will change
* the state of a {@code boolean} {@link SettingsItem}.<br>
* <br>
* Project: <strong>envoy-client</strong><br>
* File: <strong>PrimaryToggleSwitch.java</strong><br>
@ -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<Boolean> settingsItem) {

View File

@ -10,11 +10,22 @@ import envoy.exception.EnvoyException;
* Created: <strong>23.12.2019</strong><br>
*
* @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 <T> 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 extends Serializable> T read(File file, Class<T> 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);
}
}
}
}