Author: scottbw
Date: Wed Aug 24 13:17:36 2011
New Revision: 1161087
URL: http://svn.apache.org/viewvc?rev=1161087&view=rev
Log:
Added more documentation to the SharedDataHelper facade, also added an
assertion to catch unexpected duplicates in results for getting a single shared
data object.
Modified:
incubator/wookie/trunk/src/org/apache/wookie/helpers/SharedDataHelper.java
Modified:
incubator/wookie/trunk/src/org/apache/wookie/helpers/SharedDataHelper.java
URL:
http://svn.apache.org/viewvc/incubator/wookie/trunk/src/org/apache/wookie/helpers/SharedDataHelper.java?rev=1161087&r1=1161086&r2=1161087&view=diff
==============================================================================
--- incubator/wookie/trunk/src/org/apache/wookie/helpers/SharedDataHelper.java
(original)
+++ incubator/wookie/trunk/src/org/apache/wookie/helpers/SharedDataHelper.java
Wed Aug 24 13:17:36 2011
@@ -26,39 +26,106 @@ import org.apache.wookie.beans.util.Pers
* SharedDataKeys have an external form used by the host application (e.g.
"tab23").
*
* However we also have an internal form which avoids potential collisions,
and which is unique
- * to the combination of the host application, external shared data key, and
the widget URI
+ * to the combination of the host application (API key), external shared data
key, and the widget URI
*/
public class SharedDataHelper {
+
+ /**
+ * Get the external form of the shared data key; i.e. the key provided by
the client and
+ * unique only within the scope of the client API key
+ * @param instance the widget instance
+ * @return the external shared data key for the widget instance
+ * FIXME Not implemented yet. We need somewhere to safely store external
shared data keys
+ */
+ public static String getExternalSharedDataKey(IWidgetInstance instance){
+ return null;
+ }
+ /**
+ * Get the internal form of the shared data key
+ * @param instance the widget instance
+ * @return the internal shared data key for the widget instance
+ */
public static String getInternalSharedDataKey(IWidgetInstance instance){
return instance.getSharedDataKey();
}
- public static String getInternalSharedDataKey(IWidgetInstance instance,
String sharedDataKey){
- String key = sharedDataKey + ":" + instance.getApiKey() + ":" +
instance.getWidget().getGuid();
+ /**
+ * Create an internal shared data key given a widget instance and
external shared data key
+ * @param instance the widget instance
+ * @param externalSharedDataKey the shared data key provided by the
client plugin
+ * @return the internal shared data key for the instance
+ */
+ public static String getInternalSharedDataKey(IWidgetInstance instance,
String externalSharedDataKey){
+ String key = externalSharedDataKey + ":" + instance.getApiKey()
+ ":" + instance.getWidget().getGuid();
return String.valueOf(key.hashCode());
}
- public static String getInternalSharedDataKey(String apiKey, String
widgetUri, String sharedDataKey){
- String key = sharedDataKey + ":" + apiKey + ":" + widgetUri;
+ /**
+ * Create an internal shared data key given an API key, widget URI and
external shared data key
+ * @param apiKey the API key used to request widget instances
+ * @param widgetUri the Widget's external URI-based identifier
+ * @param externalSharedDataKey the shared data key provided by the
client plugin
+ * @return the internal shared data key
+ */
+ public static String getInternalSharedDataKey(String apiKey, String
widgetUri, String externalSharedDataKey){
+ String key = externalSharedDataKey + ":" + apiKey + ":" + widgetUri;
return String.valueOf(key.hashCode());
}
+ /**
+ * Find shared data for a Widget Instance
+ * @param instance the widget instance
+ * @return an array of SharedData objects for the widget instance
+ */
public static ISharedData[] findSharedData(IWidgetInstance instance){
- String sharedDataKey =
SharedDataHelper.getInternalSharedDataKey(instance);
- IPersistenceManager persistenceManager =
PersistenceManagerFactory.getPersistenceManager();
- return (ISharedData[])
persistenceManager.findByValue(ISharedData.class, "sharedDataKey",
sharedDataKey);
+
+ //
+ // Use the internal shared data key of the instance for one index of the
query
+ //
+ String sharedDataKey = SharedDataHelper.getInternalSharedDataKey(instance);
+
+ //
+ // Obtain a persistence manager and return the results of executing a
query of SharedData objects matching the sharedDataKey
+ //
+ IPersistenceManager persistenceManager =
PersistenceManagerFactory.getPersistenceManager();
+ return (ISharedData[]) persistenceManager.findByValue(ISharedData.class,
"sharedDataKey", sharedDataKey);
}
+ /**
+ * Find a specific shared data object for a given Widget Instance and
object key
+ * @param instance the widget instance
+ * @param key the key of the shared data object, i.e. the tuple key not
the shared data key
+ * @return a SharedData object, or null if no matches are found
+ */
public static ISharedData findSharedData(IWidgetInstance instance,
String key){
- String sharedDataKey =
SharedDataHelper.getInternalSharedDataKey(instance);
- IPersistenceManager persistenceManager =
PersistenceManagerFactory.getPersistenceManager();
- HashMap<String, Object> params = new HashMap<String, Object>();
- params.put("sharedDataKey", sharedDataKey);
- params.put("dkey", key);
- ISharedData[] results = (ISharedData[])
persistenceManager.findByValues(ISharedData.class, params);
- if (results.length != 0) return results[0];
- return null;
+
+ //
+ // Use the internal shared data key of the instance for one index of
the query
+ //
+ String sharedDataKey = SharedDataHelper.getInternalSharedDataKey(instance);
+
+ //
+ // Obtain a persistence manager and construct a query of SharedData
objects matching the sharedDataKey and dkey
+ //
+ IPersistenceManager persistenceManager =
PersistenceManagerFactory.getPersistenceManager();
+ HashMap<String, Object> params = new HashMap<String, Object>();
+ params.put("sharedDataKey", sharedDataKey);
+ params.put("dkey", key);
+
+ //
+ // Execute the query and obtain array of results
+ // We assert that there are never duplicates.
+ //
+ ISharedData[] results = (ISharedData[])
persistenceManager.findByValues(ISharedData.class, params);
+ assert(results.length <= 1);
+
+ //
+ // If the result contains a single item, return it, otherwise return null.
+ //
+
+ if (results.length != 0) return results[0];
+ return null;
}
}
