ATLAS-422 JavaDoc NotificationConsumer and NotificationInterface.

notification/src/main/java/org/apache/atlas/kafka/KafkaConsumer.java

@@ -52,7 +52,7 @@ public class KafkaConsumer<T> extends AbstractNotificationConsumer<T> {
     }
 
 
-    // ----- Iterator --------------------------------------------------------
+    // ----- NotificationConsumer --------------------------------------------
 
     @Override
     public boolean hasNext() {

notification/src/main/java/org/apache/atlas/notification/AbstractNotificationConsumer.java

@@ -63,7 +63,7 @@ public abstract class AbstractNotificationConsumer<T> implements NotificationCon
     private final Class<T> type;
 
 
-    // ----- Constructors ------------------------------------------------------
+    // ----- Constructors ----------------------------------------------------
 
     /**
      * Construct an AbstractNotificationConsumer.
@@ -84,8 +84,15 @@ public abstract class AbstractNotificationConsumer<T> implements NotificationCon
      */
     protected abstract String getNext();
 
+    /**
+     * Get the next notification as a string without advancing.
+     *
+     * @return the next notification in string form
+     */
+    protected abstract String peekMessage();
+
 
-    // ----- Iterator ---------------------------------------------------------
+    // ----- NotificationConsumer ---------------------------------------------
 
     @Override
     public T next() {
@@ -97,13 +104,11 @@ public abstract class AbstractNotificationConsumer<T> implements NotificationCon
         return GSON.fromJson(peekMessage(), type);
     }
 
-    protected abstract String peekMessage();
 
     /**
      * Deserializer for ImmutableList used by AbstractNotificationConsumer.GSON.
      */
     public static class ImmutableListDeserializer implements JsonDeserializer<ImmutableList<?>> {
-
         public static final Type LIST_TYPE = new TypeToken<List<?>>() {
         }.getType();
 
@@ -115,7 +120,6 @@ public abstract class AbstractNotificationConsumer<T> implements NotificationCon
         }
     }
 
-
     /**
      * Deserializer for ImmutableMap used by AbstractNotificationConsumer.GSON.
      */
@@ -144,7 +148,6 @@ public abstract class AbstractNotificationConsumer<T> implements NotificationCon
         }
     }
 
-
     /**
      * Serde for Struct used by AbstractNotificationConsumer.GSON.
      */
@@ -162,7 +165,6 @@ public abstract class AbstractNotificationConsumer<T> implements NotificationCon
         }
     }
 
-
     /**
      * Serde for Referenceable used by AbstractNotificationConsumer.GSON.
      */
@@ -182,7 +184,6 @@ public abstract class AbstractNotificationConsumer<T> implements NotificationCon
         }
     }
 
-
     /**
      * Serde for JSONArray used by AbstractNotificationConsumer.GSON.
      */

notification/src/main/java/org/apache/atlas/notification/NotificationConsumer.java

@@ -18,13 +18,29 @@
 package org.apache.atlas.notification;
 
 /**
- * Interface for notification consumer.
- * @param <T> message type
+ * Atlas notification consumer.  This consumer blocks until a notification can be read.
+ *
+ * @param <T>  the class type of notifications returned by this consumer
+ */
+public interface NotificationConsumer<T>{
+    /**
+     * Returns true when the consumer has more notifications.  Blocks until a notification becomes available.
+     *
+     * @return true when the consumer has notifications to be read
      */
-public interface NotificationConsumer<T> {
     boolean hasNext();
 
+    /**
+     * Returns the next notification.
+     *
+     * @return the next notification
+     */
     T next();
 
+    /**
+     * Returns the next notification without advancing.
+     *
+     * @return the next notification
+     */
     T peek();
 }

notification/src/main/java/org/apache/atlas/notification/NotificationInterface.java

@@ -23,20 +23,30 @@ import org.apache.atlas.notification.hook.HookNotification;
 import java.util.List;
 
 /**
- * Notification interface for sending/receiving messages.
+ * Interface to the Atlas notification framework.  Use this interface to create consumers and to send messages of a
+ * given notification type.
+ *
  * 1. Atlas sends entity notifications
  * 2. Hooks send notifications to create/update types/entities. Atlas reads these messages
  */
 public interface NotificationInterface {
 
+    /**
+     * Prefix for Atlas notification related configuration properties.
+     */
     String PROPERTY_PREFIX = "atlas.notification";
 
     /**
-     * Notification type - hooks and entities.
+     * Atlas notification types.
      */
     enum NotificationType {
-        HOOK(HookNotification.HookNotificationMessage.class), ENTITIES(EntityNotification.class);
 
+        HOOK(HookNotification.HookNotificationMessage.class), // notifications from the Atlas integration hook producers
+        ENTITIES(EntityNotification.class);                   // notifications to entity change consumers
+
+        /**
+         * The notification class associated with this type.
+         */
         private final Class classType;
 
         NotificationType(Class classType) {
@@ -59,9 +69,30 @@ public interface NotificationInterface {
      */
     <T> List<NotificationConsumer<T>> createConsumers(NotificationType notificationType, int numConsumers);
 
+    /**
+     * Send the given messages.
+     *
+     * @param type      the message type
+     * @param messages  the messages to send
+     * @param <T>       the message type
+     *
+     * @throws NotificationException if an error occurs while sending
+     */
     <T> void send(NotificationType type, T... messages) throws NotificationException;
 
+    /**
+     * Send the given messages.
+     *
+     * @param type      the message type
+     * @param messages  the list of messages to send
+     * @param <T>       the message type
+     *
+     * @throws NotificationException if an error occurs while sending
+     */
     <T> void send(NotificationType type, List<T> messages) throws NotificationException;
 
+    /**
+     * Shutdown any notification producers and consumers associated with this interface instance.
+     */
     void close();
 }

release-log.txt

@@ -9,6 +9,7 @@ ATLAS-409 Atlas will not import avro tables with schema read from a file (dosset
 ATLAS-379 Create sqoop and falcon metadata addons (venkatnrangan,bvellanki,sowmyaramesh via shwethags)
 
 ALL CHANGES:
+ATLAS-422 JavaDoc NotificationConsumer and NotificationInterface.(tbeerbower via sumasai)
 ATLAS-536 Falcon hook loads incorrect configuration when -Datlas.conf is not given when falcon server startup (ayubkhan via shwethags)
 ATLAS-502 UI: Provide the ability to search for tags (anilsg via shwethags)
 ATLAS-364 UI Code standardization (darshankumar89 via shwethags)