Add javadoc

spark/src/main/java/org/apache/zeppelin/spark/ZeppelinContext.java

@@ -481,7 +481,7 @@ public class ZeppelinContext extends HashMap<String, Object> {
 
 
   /**
-   * Get angular object. Look up local registry first and then global registry
+   * Get angular object. Look up notebook scope first and then global scope
    * @param name variable name
    * @return value
    */
@@ -495,7 +495,7 @@ public class ZeppelinContext extends HashMap<String, Object> {
   }
 
   /**
-   * Get angular object. Look up global registry
+   * Get angular object. Look up global scope
    * @param name variable name
    * @return value
    */
@@ -510,7 +510,7 @@ public class ZeppelinContext extends HashMap<String, Object> {
   }
 
   /**
-   * Create angular variable in local registry and bind with front end Angular display system.
+   * Create angular variable in notebook scope and bind with front end Angular display system.
    * If variable exists, it'll be overwritten.
    * @param name name of the variable
    * @param o value
@@ -520,7 +520,7 @@ public class ZeppelinContext extends HashMap<String, Object> {
   }
 
   /**
-   * Create angular variable in global registry and bind with front end Angular display system.
+   * Create angular variable in global scope and bind with front end Angular display system.
    * If variable exists, it'll be overwritten.
    * @param name name of the variable
    * @param o value
@@ -530,7 +530,7 @@ public class ZeppelinContext extends HashMap<String, Object> {
   }
 
   /**
-   * Create angular variable in local registry and bind with front end Angular display system.
+   * Create angular variable in local scope and bind with front end Angular display system.
    * If variable exists, value will be overwritten and watcher will be added.
    * @param name name of variable
    * @param o value
@@ -541,7 +541,7 @@ public class ZeppelinContext extends HashMap<String, Object> {
   }
 
   /**
-   * Create angular variable in global registry and bind with front end Angular display system.
+   * Create angular variable in global scope and bind with front end Angular display system.
    * If variable exists, value will be overwritten and watcher will be added.
    * @param name name of variable
    * @param o value
@@ -552,7 +552,7 @@ public class ZeppelinContext extends HashMap<String, Object> {
   }
 
   /**
-   * Add watcher into angular variable (local registry)
+   * Add watcher into angular variable (local scope)
    * @param name name of the variable
    * @param watcher watcher
    */
@@ -561,7 +561,7 @@ public class ZeppelinContext extends HashMap<String, Object> {
   }
 
   /**
-   * Add watcher into angular variable (global registry)
+   * Add watcher into angular variable (global scope)
    * @param name name of the variable
    * @param watcher watcher
    */
@@ -645,7 +645,7 @@ public class ZeppelinContext extends HashMap<String, Object> {
   }
 
   /**
-   * Create angular variable in local registry and bind with front end Angular display system.
+   * Create angular variable in notebook scope and bind with front end Angular display system.
    * If variable exists, it'll be overwritten.
    * @param name name of the variable
    * @param o value
@@ -661,7 +661,8 @@ public class ZeppelinContext extends HashMap<String, Object> {
   }
 
   /**
-   * Create angular variable in local registry and bind with front end Angular display system.
+   * Create angular variable in notebook scope and bind with front end Angular display
+   * system.
    * If variable exists, value will be overwritten and watcher will be added.
    * @param name name of variable
    * @param o value

zeppelin-interpreter/src/main/java/org/apache/zeppelin/display/AngularObject.java

@@ -26,7 +26,9 @@ import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
 /**
- *
+ * AngularObject provides binding between back-end (interpreter) and front-end
+ * User provided object will automatically synchronized with front-end side.
+ * i.e. update from back-end will be sent to front-end, update from front-end will sent-to backend
  *
  * @param <T>
  */
@@ -40,6 +42,16 @@ public class AngularObject<T> {
   
   private String noteId;   // noteId belonging to. null for global scope 
   private String paragraphId; // paragraphId belongs to. null for notebook scope
+
+  /**
+   * To create new AngularObject, use AngularObjectRegistry.add()
+   *
+   * @param name name of object
+   * @param o reference to user provided object to sent to front-end
+   * @param noteId noteId belongs to. can be null
+   * @param paragraphId paragraphId belongs to. can be null
+   * @param listener event listener
+   */
   protected AngularObject(String name, T o, String noteId, String paragraphId,
       AngularObjectListener listener) {
     this.name = name;
@@ -49,26 +61,50 @@ public class AngularObject<T> {
     object = o;
   }
 
+  /**
+   * Get name of this object
+   * @return name
+   */
   public String getName() {
     return name;
   }
-  
+
+  /**
+   * Set noteId
+   * @param noteId noteId belongs to. can be null
+   */
   public void setNoteId(String noteId) {
     this.noteId = noteId;
   }
-  
+
+  /**
+   * Get noteId
+   * @return noteId
+   */
   public String getNoteId() {
     return noteId;
   }
 
+  /**
+   * get ParagraphId
+   * @return paragraphId
+   */
   public String getParagraphId() {
     return paragraphId;
   }
 
+  /**
+   * Set paragraphId
+   * @param paragraphId paragraphId. can be null
+   */
   public void setParagraphId(String paragraphId) {
     this.paragraphId = paragraphId;
   }
 
+  /**
+   * Check if it is global scope object
+   * @return true it is global scope
+   */
   public boolean isGlobal() {
     return noteId == null;
   }
@@ -88,20 +124,38 @@ public class AngularObject<T> {
     return false;
   }
 
+  /**
+   * Get value
+   * @return
+   */
   public Object get() {
     return object;
   }
 
+  /**
+   * fire updated() event for listener
+   * Note that it does not invoke watcher.watch()
+   */
   public void emit(){
     if (listener != null) {
       listener.updated(this);
     }
   }
-  
+
+  /**
+   * Set value
+   * @param o reference to new user provided object
+   */
   public void set(T o) {
     set(o, true);
   }
 
+  /**
+   * Set value
+   * @param o reference to new user provided object
+   * @param emit false on skip firing event for listener. note that it does not skip invoke
+   *             watcher.watch() in any case
+   */
   public void set(T o, boolean emit) {
     final T before = object;
     final T after = o;
@@ -131,26 +185,47 @@ public class AngularObject<T> {
     }
   }
 
+  /**
+   * Set event listener for this object
+   * @param listener
+   */
   public void setListener(AngularObjectListener listener) {
     this.listener = listener;
   }
 
+  /**
+   * Get event listener of this object
+   * @return event listener
+   */
   public AngularObjectListener getListener() {
     return listener;
   }
 
+  /**
+   * Add a watcher for this object.
+   * Multiple watcher can be registered.
+   *
+   * @param watcher watcher to add
+   */
   public void addWatcher(AngularObjectWatcher watcher) {
     synchronized (watchers) {
       watchers.add(watcher);
     }
   }
 
+  /**
+   * Remove a watcher from this object
+   * @param watcher watcher to remove
+   */
   public void removeWatcher(AngularObjectWatcher watcher) {
     synchronized (watchers) {
       watchers.remove(watcher);
     }
   }
 
+  /**
+   * Remove all watchers from this object
+   */
   public void clearAllWatchers() {
     synchronized (watchers) {
       watchers.clear();

zeppelin-interpreter/src/main/java/org/apache/zeppelin/display/AngularObjectRegistry.java

@@ -26,9 +26,10 @@ import java.util.Map;
 /**
  * AngularObjectRegistry keeps all the object that binded to Angular Display System.
  * AngularObjectRegistry is created per interpreter group.
- * It keeps two different set of AngularObjects :
- *  - globalRegistry: Shared to all notebook that uses the same interpreter group
- *  - localRegistry: AngularObject is valid only inside of a single notebook
+ * It provides three different scope of AngularObjects :
+ *  - Paragraphscope : AngularObject is valid in specific paragraph
+ *  - Notebook scope: AngularObject is valid in a single notebook
+ *  - Global scope : Shared to all notebook that uses the same interpreter group
  */
 public class AngularObjectRegistry {
   Map<String, Map<String, AngularObject>> registry = 
@@ -60,10 +61,16 @@ public class AngularObjectRegistry {
 
   /**
    * Add object into registry
-   * @param name
-   * @param o
-   * @param noteId noteId belonging to. null for global object.
-   * @return
+   *
+   * Paragraph scope when noteId and paragraphId both not null
+   * Notebook scope when paragraphId is null
+   * Global scope when noteId and paragraphId both null
+   *
+   * @param name Name of object
+   * @param o Reference to the object
+   * @param noteId noteId belonging to. null for global scope
+   * @param paragraphId paragraphId belongs to. null for notebook scope
+   * @return AngularObject that added
    */
   public AngularObject add(String name, Object o, String noteId, String paragraphId) {
     return add(name, o, noteId, paragraphId, true);
@@ -91,7 +98,21 @@ public class AngularObjectRegistry {
       return registry.get(key);
     }
   }
- 
+
+  /**
+   * Add object into registry
+   *
+   * Paragraph scope when noteId and paragraphId both not null
+   * Notebook scope when paragraphId is null
+   * Global scope when noteId and paragraphId both null
+   *
+   * @param name Name of object
+   * @param o Reference to the object
+   * @param noteId noteId belonging to. null for global scope
+   * @param paragraphId paragraphId belongs to. null for notebook scope
+   * @param emit skip firing onAdd event on false
+   * @return AngularObject that added
+   */
   public AngularObject add(String name, Object o, String noteId, String paragraphId,
                            boolean emit) {
     AngularObject ao = createNewAngularObject(name, o, noteId, paragraphId);
@@ -116,10 +137,27 @@ public class AngularObjectRegistry {
     return angularObjectListener;
   }
 
+  /**
+   * Remove a object from registry
+   *
+   * @param name Name of object to remove
+   * @param noteId noteId belongs to. null for global scope
+   * @param paragraphId paragraphId belongs to. null for notebook scope
+   * @return removed object. null if object is not found in registry
+   */
   public AngularObject remove(String name, String noteId, String paragraphId) {
     return remove(name, noteId, paragraphId, true);
   }
 
+  /**
+   * Remove a object from registry
+   *
+   * @param name Name of object to remove
+   * @param noteId noteId belongs to. null for global scope
+   * @param paragraphId paragraphId belongs to. null for notebook scope
+   * @param emit skip fireing onRemove event on false
+   * @return removed object. null if object is not found in registry
+   */
   public AngularObject remove(String name, String noteId, String paragraphId, boolean emit) {
     synchronized (registry) {
       Map<String, AngularObject> r = getRegistryForKey(noteId, paragraphId);
@@ -131,6 +169,16 @@ public class AngularObjectRegistry {
     }
   }
 
+  /**
+   * Remove all angular object in the scope.
+   *
+   * Remove all paragraph scope angular object when noteId and paragraphId both not null
+   * Remove all notebook scope angular object when paragraphId is null
+   * Remove all global scope angular objects when noteId and paragraphId both null
+   *
+   * @param noteId noteId
+   * @param paragraphId paragraphId
+   */
   public void removeAll(String noteId, String paragraphId) {
     synchronized (registry) {
       List<AngularObject> all = getAll(noteId, paragraphId);
@@ -140,6 +188,13 @@ public class AngularObjectRegistry {
     }
   }
 
+  /**
+   * Get a object from registry
+   * @param name name of object
+   * @param noteId noteId that belongs to
+   * @param paragraphId paragraphId that belongs to
+   * @return angularobject. null when not found
+   */
   public AngularObject get(String name, String noteId, String paragraphId) {
     synchronized (registry) {
       Map<String, AngularObject> r = getRegistryForKey(noteId, paragraphId);
@@ -147,6 +202,12 @@ public class AngularObjectRegistry {
     }
   }
 
+  /**
+   * Get all object in the scope
+   * @param noteId noteId that belongs to
+   * @param paragraphId paragraphId that belongs to
+   * @return all angularobject in the scope
+   */
   public List<AngularObject> getAll(String noteId, String paragraphId) {
     List<AngularObject> all = new LinkedList<AngularObject>();
     synchronized (registry) {
@@ -159,7 +220,10 @@ public class AngularObjectRegistry {
   }
   
   /**
-   * Get all object with global merged
+   * Get all angular object related to specific note.
+   * That includes all global scope objects, notebook scope objects and paragraph scope objects
+   * belongs to the noteId.
+   *
    * @param noteId
    * @return
    */

zeppelin-interpreter/src/main/java/org/apache/zeppelin/interpreter/remote/RemoteAngularObject.java

@@ -21,7 +21,7 @@ import org.apache.zeppelin.display.AngularObject;
 import org.apache.zeppelin.display.AngularObjectListener;
 
 /**
- *
+ * Proxy for AngularObject that exists in remote interpreter process
  */
 public class RemoteAngularObject extends AngularObject {
 

zeppelin-interpreter/src/main/java/org/apache/zeppelin/interpreter/remote/RemoteAngularObjectRegistry.java

@@ -33,7 +33,7 @@ import org.slf4j.LoggerFactory;
 import com.google.gson.Gson;
 
 /**
- *
+ * Proxy for AngularObjectRegistry that exists in remote interpreter process
  */
 public class RemoteAngularObjectRegistry extends AngularObjectRegistry {
   Logger logger = LoggerFactory.getLogger(RemoteAngularObjectRegistry.class);