From 5bc2a5ed9dab58aca2caca778a9f96a2b5a04249 Mon Sep 17 00:00:00 2001 From: Steffen Schaefer Date: Wed, 16 Mar 2016 17:51:58 +0100 Subject: [PATCH] bug 2775: Added some JavaDocs to the central classes of the Settings framework --- .../com/sap/sse/common/settings/Settings.java | 34 ++++++++++++++----- .../gwt/settings/SettingsToUrlSerializer.java | 10 ++++++ .../settings/SettingsToJsonSerializer.java | 13 ++----- 3 files changed, 38 insertions(+), 19 deletions(-) diff --git a/java/com.sap.sse.common/src/com/sap/sse/common/settings/Settings.java b/java/com.sap.sse.common/src/com/sap/sse/common/settings/Settings.java index 6f7df127e71..34b87b1845a 100644 --- a/java/com.sap.sse.common/src/com/sap/sse/common/settings/Settings.java +++ b/java/com.sap.sse.common/src/com/sap/sse/common/settings/Settings.java @@ -3,8 +3,8 @@ package com.sap.sse.common.settings; import java.util.Map; /** - * A generic format to keep the non-default settings for a Component. Such settings may be initialized with - * defaults. Usually they can be edited by a user using a SettingsDialogComponent displayed by a + * A generic format to keep the settings for a Component. Such settings may be initialized with defaults. + * Usually they can be edited by a user using a SettingsDialogComponent displayed by a * SettingsDialog. 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. @@ -15,21 +15,39 @@ import java.util.Map; * in the user-specific preferences store where JSON may be a useful format to keep them as a {@link String}. *

* - * In order to enable mapping the settings to URL parameters, each setting needs to have a name and a {@link Setting} - * value that in turn can be serialized accordingly. Furthermore, the component to which the settings apply needs to - * provide a String identifier. This way, generic serializers/de-serializers can take over the serialization from/to the - * various formats. + * The following serializers are available: + *

+ * + * 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) * */ public interface Settings extends Setting { + /** + * Path separator for serializers that construct flat keys for the hierachical settings structures (e.g. URL). + */ public static final String PATH_SEPARATOR = "."; /** - * Obtains all settings that have non-default values and therefore are required for the later re-construction - * of the settings object when passed the resulting map. + * Obtains all child settings. */ Map getChildSettings(); } diff --git a/java/com.sap.sse.gwt/src/com/sap/sse/gwt/settings/SettingsToUrlSerializer.java b/java/com.sap.sse.gwt/src/com/sap/sse/gwt/settings/SettingsToUrlSerializer.java index ac3cdfe30eb..839d3b8b67b 100644 --- a/java/com.sap.sse.gwt/src/com/sap/sse/gwt/settings/SettingsToUrlSerializer.java +++ b/java/com.sap.sse.gwt/src/com/sap/sse/gwt/settings/SettingsToUrlSerializer.java @@ -8,6 +8,16 @@ import com.sap.sse.common.Util; import com.sap.sse.common.settings.Settings; import com.sap.sse.common.settings.serializer.SettingsToStringMapSerializer; +/** + * Serializes {@link Settings} objects to the URL by constructing flat keys from the hierarchical object graph. + * + * This type of serialzation has some limitations: + * + * + */ public class SettingsToUrlSerializer { private final SettingsToStringMapSerializer settingsToStringMapSerializer = new SettingsToStringMapSerializer(); diff --git a/java/com.sap.sse.shared.android/src/com/sap/sse/shared/settings/SettingsToJsonSerializer.java b/java/com.sap.sse.shared.android/src/com/sap/sse/shared/settings/SettingsToJsonSerializer.java index 52f78b17b2d..f57df9da4a7 100644 --- a/java/com.sap.sse.shared.android/src/com/sap/sse/shared/settings/SettingsToJsonSerializer.java +++ b/java/com.sap.sse.shared.android/src/com/sap/sse/shared/settings/SettingsToJsonSerializer.java @@ -3,21 +3,12 @@ package com.sap.sse.shared.settings; import org.json.simple.JSONArray; import org.json.simple.JSONObject; -import com.sap.sse.common.settings.EnumSetting; import com.sap.sse.common.settings.Settings; import com.sap.sse.common.settings.serializer.AbstractSettingsToJsonSerializer; /** - * Serializes a {@link Settings} object to a {@link JSONObject}. All setting types are supported as top-level entities. - * Nesting of {@link Settings} is generally supported. For example, a {@link Settings} object can be contains as one - * setting within another {@link Settings} object. However, when nesting {@link EnumSetting} objects within a - * {@link ListSetting} then it is mandatory to put this {@link ListSetting} object into a {@link Settings} object's - * {@link Settings#getNonDefaultSettings()}, such as into a {@link MapSettings} object. The technical reason for this - * limitation is that the {@link Class} object for the enumeration type must be stored with the serialized format in - * order to re-construct the enumeration literals of the correct type. For readability of the produced JSON output, - * this implementation chooses to store the enumeration class's name in a special property that is sibling of the - * enumeration property. A {@link ListSetting} object does not contain named properties and therefore does not allow - * us to add such a property easily. + * Serializes a {@link Settings} object to a {@link JSONObject}. All {@link Settings} subclasses are supported as top-level entities. + * Nesting of {@link Settings} is generally supported. * * @author Axel Uhl (D043530) *