incubator-wookie-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From scot...@apache.org
Subject svn commit: r1161087 - /incubator/wookie/trunk/src/org/apache/wookie/helpers/SharedDataHelper.java
Date Wed, 24 Aug 2011 13:17:36 GMT
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;
 	}	
 
 }



Mime
View raw message