mirror of
https://github.com/eclipse-sailing-analytics/sailing-analytics.git
synced 2026-10-17 01:31:01 +00:00
Added JavaDocs to Settings related classes
This commit is contained in:
Steffen Schaefer committed
1 parent
716969dee6
commit
0d7c19a984
6 files changed
+41
-90
No files matched your search
@@ -1,63 +1,15 @@
|
||||
package com.sap.sse.common.settings;
|
||||
|
||||
import com.sap.sse.common.settings.generic.Setting;
|
||||
|
||||
/**
|
||||
* Common superclass for custom Settings used by Components. The following example shows how to implement custom
|
||||
* Settings:
|
||||
*
|
||||
* <pre>
|
||||
* <code>
|
||||
* public final class ExampleSettings extends AbstractSettings {
|
||||
* private transient StringSetting myString;
|
||||
* private transient BooleanSetting myBoolean;
|
||||
*
|
||||
* // Used to create instances for a component
|
||||
* public ExampleSettings() {
|
||||
* }
|
||||
*
|
||||
* // Used to create nested settings
|
||||
* public ExampleSettings(String name, AbstractSettings parentSettings) {
|
||||
* super(name, parentSettings);
|
||||
* }
|
||||
*
|
||||
* @Override
|
||||
* protected void addChildSettings() {
|
||||
* myString = new UUIDSetting("myString", this)
|
||||
* myBoolean = new BooleanSetting("myBoolean", this);
|
||||
* }
|
||||
*
|
||||
* public String getMyString() {
|
||||
* return this.myString.getValue();
|
||||
* }
|
||||
*
|
||||
* public void setMyString(String myString) {
|
||||
* return this.myString.setValue(myString);
|
||||
* }
|
||||
*
|
||||
* public boolean isMyBoolean() {
|
||||
* return this.myBoolean.getValue();
|
||||
* }
|
||||
*
|
||||
* public void setMyBoolean(boolean myBoolean) {
|
||||
* return this.myBoolean.setValue(myBoolean);
|
||||
* }
|
||||
* }
|
||||
* </code>
|
||||
* </pre>
|
||||
*
|
||||
* To correctly support several kinds of Serialization (Java, GWT and Custom), you need to ensure the following:
|
||||
* Common superclass for custom Settings used by Components. This kind of Settings is not serializable at all. There are
|
||||
* more specific super classes for different serialization needs:
|
||||
* <ul>
|
||||
* <li>the Settings class must have a default constructor</li>
|
||||
* <li>child settings fields need to be transient</li>
|
||||
* <li>child settings instances must be initialized in {@link #addChildSettings()} method</li>
|
||||
* <li>{@link SerializableSettings} can be used for {@link Settings} that need to be Java-serializable and/or
|
||||
* GWT-RPC-compatible</li>
|
||||
* <li>{@link com.sap.sse.common.settings.generic.AbstractGenericSerializableSettings} support a wide variety of serialization mechanisms by using a generic
|
||||
* mechanism to declare the settings that requires that implementers comply to some specific rules</li>
|
||||
* </ul>
|
||||
*
|
||||
* If a custom Settings class only has {@link Setting} oder {@link Settings} children that are correctly attached by
|
||||
* calling their constructor with a name and the parent {@link Settings} you do not need to implement
|
||||
* {@link #hashCode()}, {@link #equals(Object)} and {@link #toString()}. There are generic implementations of those methods that are
|
||||
* based on the child {@link Setting}s which should be sufficient for most cases.
|
||||
*
|
||||
*/
|
||||
public abstract class AbstractSettings implements Settings {
|
||||
public abstract class AbstractSettings implements Settings {
|
||||
}
|
||||
@@ -2,6 +2,9 @@ package com.sap.sse.common.settings;
|
||||
|
||||
import java.io.Serializable;
|
||||
|
||||
/**
|
||||
* Super class for {@link Settings} that need to be Java-serializable or compatible with GWT-RPC.
|
||||
*/
|
||||
public abstract class SerializableSettings extends AbstractSettings implements Serializable {
|
||||
private static final long serialVersionUID = -2710627501473421333L;
|
||||
}
|
||||
@@ -1,40 +1,11 @@
|
||||
package com.sap.sse.common.settings;
|
||||
|
||||
import com.sap.sse.common.settings.generic.Setting;
|
||||
|
||||
/**
|
||||
* A generic format to keep the settings for a <code>Component</code>. Such settings may be initialized with defaults.
|
||||
* Usually they can be edited by a user using a <code>SettingsDialogComponent</code> displayed by a
|
||||
* <code>SettingsDialog</code>. The interface is homed in this server-side, shared bundle because settings may as well
|
||||
* be handled on the server side, e.g., in order to store them in the user store or to apply them to a server-side
|
||||
* component.
|
||||
* <p>
|
||||
*
|
||||
* Settings need to be serialized and de-serialized to/from different formats. In a URL they should try to follow
|
||||
* reasonable URL parameter encoding conventions and be human readable/editable. They may also be stored in a cookie or
|
||||
* in the user-specific preferences store where JSON may be a useful format to keep them as a {@link String}.
|
||||
* <p>
|
||||
*
|
||||
* The following serializers are available:
|
||||
* <ul>
|
||||
* <li>
|
||||
* {@link com.sap.sse.common.settings.serializer.SettingsToStringMapSerializer}: Serializes to a Map containing String
|
||||
* keys and values</li>
|
||||
* <li>
|
||||
* {@link com.sap.sse.gwt.settings.SettingsToUrlSerializer}: Serializes to a GWT UrlBuilder</li>
|
||||
* <li>
|
||||
* {@link com.sap.sse.shared.settings.SettingsToJsonSerializer}: Serializes to org.json.simple objects usable in the
|
||||
* backend and on Android</li>
|
||||
* <li>
|
||||
* {@link com.sap.sse.gwt.settings.SettingsToJsonSerializerGWT}: Serializes to GWT's JSON types. The resliting JSON
|
||||
* String is compatible with the backend-side SettingsToJsonSerializer.</li>
|
||||
* </ul>
|
||||
*
|
||||
* In order to enable mapping the settings to URL parameters or JSON structures, each setting needs an associated name
|
||||
* and the {@link Settings} hierarchy must be ensured. For this every {@link Setting} has a constructor requiring it's
|
||||
* name and parent Settings object. To make {@link Settings} able to be nested in other {@link Settings} you need to
|
||||
* provide the very same constructor that can simply call super on {@link AbstractSettings}. This way, generic
|
||||
* serializers/de-serializers can take over the serialization from/to the various formats.
|
||||
*
|
||||
* @author Axel Uhl (D043530)
|
||||
*
|
||||
|
||||
+1
-1
@@ -18,7 +18,7 @@ import com.sap.sse.common.settings.value.Value;
|
||||
*
|
||||
* <pre>
|
||||
* <code>
|
||||
* public final class ExampleSettings extends AbstractSettings {
|
||||
* public final class ExampleSettings extends AbstractGenericSerializableSettings {
|
||||
* private transient StringSetting myString;
|
||||
* private transient BooleanSetting myBoolean;
|
||||
*
|
||||
|
||||
+28
-1
@@ -5,10 +5,37 @@ import java.util.Map;
|
||||
|
||||
import com.sap.sse.common.settings.Settings;
|
||||
|
||||
/**
|
||||
* {@link Settings} that need to be serialized and de-serialized to/from different formats. In a URL they should try to follow
|
||||
* reasonable URL parameter encoding conventions and be human readable/editable. They may also be stored in a cookie or
|
||||
* in the user-specific preferences store where JSON may be a useful format to keep them as a {@link String}.
|
||||
* <p>
|
||||
*
|
||||
* The following serializers are available:
|
||||
* <ul>
|
||||
* <li>
|
||||
* {@link com.sap.sse.common.settings.serializer.SettingsToStringMapSerializer}: Serializes to a Map containing String
|
||||
* keys and values</li>
|
||||
* <li>
|
||||
* {@link com.sap.sse.gwt.settings.SettingsToUrlSerializer}: Serializes to a GWT UrlBuilder</li>
|
||||
* <li>
|
||||
* {@link com.sap.sse.shared.settings.SettingsToJsonSerializer}: Serializes to org.json.simple objects usable in the
|
||||
* backend and on Android</li>
|
||||
* <li>
|
||||
* {@link com.sap.sse.gwt.settings.SettingsToJsonSerializerGWT}: Serializes to GWT's JSON types. The resulting JSON
|
||||
* String is compatible with the backend-side SettingsToJsonSerializer.</li>
|
||||
* </ul>
|
||||
*
|
||||
* In order to enable mapping the settings to URL parameters or JSON structures, each setting needs an associated name
|
||||
* and the {@link Settings} hierarchy must be ensured. For this every {@link Setting} has a constructor requiring it's
|
||||
* name and parent Settings object. To make {@link Settings} able to be nested in other {@link Settings} you need to
|
||||
* provide the very same constructor that can simply call super on {@link AbstractSettings}. This way, generic
|
||||
* serializers/de-serializers can take over the serialization from/to the various formats.
|
||||
*/
|
||||
public interface GenericSerializableSettings extends Settings, Setting, Serializable {
|
||||
|
||||
/**
|
||||
* Path separator for serializers that construct flat keys for the hierachical settings structures (e.g. URL).
|
||||
* Path separator for serializers that construct flat keys for the hierarchical settings structures (e.g. URL).
|
||||
*/
|
||||
public static final String PATH_SEPARATOR = ".";
|
||||
|
||||
|
||||
@@ -1,10 +1,8 @@
|
||||
package com.sap.sse.common.settings.generic;
|
||||
|
||||
import com.sap.sse.common.settings.AbstractSettings;
|
||||
|
||||
/**
|
||||
* A setting as contained as values in the map returned by {@link AbstractSettings#getSettings()}. This generic
|
||||
* view on a {@link AbstractSettings} object can then be used by one or more serializer / de-serializer combos
|
||||
* A setting as contained as values in the map returned by {@link GenericSerializableSettings#getSettings()}. This generic
|
||||
* view on a {@link GenericSerializableSettings} object can then be used by one or more serializer / de-serializer combos
|
||||
* for different serialized formats such as URLs, human-readable strings, obfuscated strings, JSON, or
|
||||
* a binary format.
|
||||
*
|
||||
|
||||
Reference in new issue
Block a user