Author: gates
Date: Tue Aug 24 16:26:05 2010
New Revision: 988611

URL: http://svn.apache.org/viewvc?rev=988611&view=rev
Log:
PIG-1311 Document audience and stability for remaining interfaces.

Removed:
    hadoop/pig/trunk/src/org/apache/pig/impl/FunctionInstantiator.java
Modified:
    hadoop/pig/trunk/CHANGES.txt
    
hadoop/pig/trunk/src/org/apache/pig/backend/hadoop/executionengine/physicalLayer/PigProgressable.java
    hadoop/pig/trunk/src/org/apache/pig/data/TupleRawComparator.java
    hadoop/pig/trunk/src/org/apache/pig/impl/PigContext.java
    hadoop/pig/trunk/src/org/apache/pig/newplan/OperatorPlan.java
    
hadoop/pig/trunk/src/org/apache/pig/newplan/optimizer/PlanTransformListener.java

Modified: hadoop/pig/trunk/CHANGES.txt
URL: 
http://svn.apache.org/viewvc/hadoop/pig/trunk/CHANGES.txt?rev=988611&r1=988610&r2=988611&view=diff
==============================================================================
--- hadoop/pig/trunk/CHANGES.txt (original)
+++ hadoop/pig/trunk/CHANGES.txt Tue Aug 24 16:26:05 2010
@@ -26,6 +26,8 @@ PIG-1249: Safe-guards against misconfigu
 
 IMPROVEMENTS
 
+PIG-1311:  Document audience and stability for remaining interfaces (gates)
+
 PIG-506: Does pig need a NATIVE keyword? (aniket486 via thejas)
 
 PIG-1510: Add `deepCopy` for LogicalExpressions (swati.j via daijy)

Modified: 
hadoop/pig/trunk/src/org/apache/pig/backend/hadoop/executionengine/physicalLayer/PigProgressable.java
URL: 
http://svn.apache.org/viewvc/hadoop/pig/trunk/src/org/apache/pig/backend/hadoop/executionengine/physicalLayer/PigProgressable.java?rev=988611&r1=988610&r2=988611&view=diff
==============================================================================
--- 
hadoop/pig/trunk/src/org/apache/pig/backend/hadoop/executionengine/physicalLayer/PigProgressable.java
 (original)
+++ 
hadoop/pig/trunk/src/org/apache/pig/backend/hadoop/executionengine/physicalLayer/PigProgressable.java
 Tue Aug 24 16:26:05 2010
@@ -17,11 +17,28 @@
  */
 package org.apache.pig.backend.hadoop.executionengine.physicalLayer;
 
+import org.apache.pig.classification.InterfaceAudience;
+import org.apache.pig.classification.InterfaceStability;
+
+
+/**
+ * Pig's progress indicator.  An implemenation of this interface is passed to
+ * UDFs to allow them to send heartbeats.  By default Hadoop will kill a task
+ * if it does not receive a heartbeat every 600 seconds.  Any operation that
+ * may take more than this should call progress on a regular basis.
+ */
+...@interfaceaudience.public
+...@interfacestability.stable
 public interface PigProgressable {
-    //Use to just inform that you are
-    //alive
+
+    /**
+     * Report progress.
+     */
     public void progress();
     
-    //If you have a status to report
+    /**
+     * Report progress with a message.
+     * @param msg message to send with progress report.
+     */
     public void progress(String msg);
 }

Modified: hadoop/pig/trunk/src/org/apache/pig/data/TupleRawComparator.java
URL: 
http://svn.apache.org/viewvc/hadoop/pig/trunk/src/org/apache/pig/data/TupleRawComparator.java?rev=988611&r1=988610&r2=988611&view=diff
==============================================================================
--- hadoop/pig/trunk/src/org/apache/pig/data/TupleRawComparator.java (original)
+++ hadoop/pig/trunk/src/org/apache/pig/data/TupleRawComparator.java Tue Aug 24 
16:26:05 2010
@@ -20,6 +20,9 @@ package org.apache.pig.data;
 import org.apache.hadoop.conf.Configurable;
 import org.apache.hadoop.io.RawComparator;
 
+import org.apache.pig.classification.InterfaceAudience;
+import org.apache.pig.classification.InterfaceStability;
+
 /**
  * This interface is intended to compare Tuples. The semantics of Tuple 
comparison must take into account null values in
  * different ways. According to SQL semantics nulls are not equal. But for 
other Pig/Latin statements nulls must be
@@ -28,6 +31,8 @@ import org.apache.hadoop.io.RawComparato
  * {...@link #compare(byte[],int,int,byte[],int,int)} method.
  * 
  */
+...@interfaceaudience.public
+...@interfacestability.evolving
 @SuppressWarnings("rawtypes")
 public interface TupleRawComparator extends RawComparator, Configurable {
     /**

Modified: hadoop/pig/trunk/src/org/apache/pig/impl/PigContext.java
URL: 
http://svn.apache.org/viewvc/hadoop/pig/trunk/src/org/apache/pig/impl/PigContext.java?rev=988611&r1=988610&r2=988611&view=diff
==============================================================================
--- hadoop/pig/trunk/src/org/apache/pig/impl/PigContext.java (original)
+++ hadoop/pig/trunk/src/org/apache/pig/impl/PigContext.java Tue Aug 24 
16:26:05 2010
@@ -55,7 +55,7 @@ import org.apache.pig.impl.streaming.Exe
 import org.apache.pig.impl.streaming.StreamingCommand;
 import org.apache.pig.impl.util.JarManager;
 
-public class PigContext implements Serializable, FunctionInstantiator {
+public class PigContext implements Serializable {
     private static final long serialVersionUID = 1L;
     
     private transient final Log log = LogFactory.getLog(getClass());

Modified: hadoop/pig/trunk/src/org/apache/pig/newplan/OperatorPlan.java
URL: 
http://svn.apache.org/viewvc/hadoop/pig/trunk/src/org/apache/pig/newplan/OperatorPlan.java?rev=988611&r1=988610&r2=988611&view=diff
==============================================================================
--- hadoop/pig/trunk/src/org/apache/pig/newplan/OperatorPlan.java (original)
+++ hadoop/pig/trunk/src/org/apache/pig/newplan/OperatorPlan.java Tue Aug 24 
16:26:05 2010
@@ -21,13 +21,22 @@ package org.apache.pig.newplan;
 import java.util.Iterator;
 import java.util.List;
 
+import org.apache.pig.classification.InterfaceAudience;
+import org.apache.pig.classification.InterfaceStability;
 import org.apache.pig.impl.logicalLayer.FrontendException;
 import org.apache.pig.impl.util.Pair;
 
+/**
+ * An interface that defines graph operations on plans.  Plans are modeled as
+ * graphs with restrictions on the types of connections and operations allowed.
+ */
+...@interfaceaudience.private
+...@interfacestability.unstable
 public interface OperatorPlan {
     
     /**
      * Get number of nodes in the plan.
+     * @return number of nodes in the plan
      */
     public int size();
 

Modified: 
hadoop/pig/trunk/src/org/apache/pig/newplan/optimizer/PlanTransformListener.java
URL: 
http://svn.apache.org/viewvc/hadoop/pig/trunk/src/org/apache/pig/newplan/optimizer/PlanTransformListener.java?rev=988611&r1=988610&r2=988611&view=diff
==============================================================================
--- 
hadoop/pig/trunk/src/org/apache/pig/newplan/optimizer/PlanTransformListener.java
 (original)
+++ 
hadoop/pig/trunk/src/org/apache/pig/newplan/optimizer/PlanTransformListener.java
 Tue Aug 24 16:26:05 2010
@@ -18,15 +18,27 @@
 
 package org.apache.pig.newplan.optimizer;
 
+import org.apache.pig.classification.InterfaceAudience;
+import org.apache.pig.classification.InterfaceStability;
 import org.apache.pig.impl.logicalLayer.FrontendException;
 import org.apache.pig.newplan.OperatorPlan;
 
 /**
- * A listener class that patches up plans after they have been transformed.
+ * An interface to describe listeners that are notified when a plan is
+ * modified.  The purpose of these listeners is to make modifications to
+ * annotations on the plan after the plan is modified.  For example, if there
+ * is a plan that has ... -> Join -> Filter -> ... which is 
transformed
+ * by pushing the filter before the join, then the input schema of the filter
+ * will mostly likely change.  A schema listener can be used to make these
+ * changes.
  */
+...@interfaceaudience.private
+...@interfacestability.unstable
 public interface PlanTransformListener {
     /**
-     * the listener that is notified after a plan is transformed
+     * Notification that a plan has been transformed.  The listener is free in
+     * this method to make changes to the annotations on the plan now that it
+     * has been transformed.
      * @param fp  the full plan that has been transformed
      * @param tp  a plan containing only the operators that have been 
transformed
      * @throws FrontendException 


Reply via email to