docs/src/site/twiki/Notification-Entity.twiki

---+ Entity Change Notifications

To receive Atlas entity notifications a consumer should be obtained through the notification interface.  Entity change notifications are sent every time a change is made to an entity.  Operations that result in an entity change notification are:
   * <code>ENTITY_CREATE</code> - Create a new entity.
   * <code>ENTITY_UPDATE</code> - Update an attribute of an existing entity.
   * <code>TRAIT_ADD</code> - Add a trait to an entity.
   * <code>TRAIT_DELETE</code> - Delete a trait from an entity.

 <verbatim>
    // Obtain provider through injection…
    Provider<NotificationInterface> provider;

    // Get the notification interface
    NotificationInterface notification = provider.get();

    // Create consumers
    List<NotificationConsumer<EntityNotification>> consumers =
       notification.createConsumers(NotificationInterface.NotificationType.ENTITIES, 1);
</verbatim>


The consumer exposes the Iterator interface that should be used to get the entity notifications as they are posted.  The hasNext() method blocks until a notification is available.

<verbatim>
    while(consumer.hasNext()) {
        EntityNotification notification = consumer.next();

        IReferenceableInstance entity = notification.getEntity();
        …
    }
</verbatim>