/**
 * Generic interface for ProvidingRegistry. The main purpose of provider
 * registry is to provide ability to register (or publish) items stored in
 * the distributed registry.
 * Appropriate ConsumerRegistries that shares data with this registry will
 * be notified of the items published by the ProvidingRegistry.
 *
 * @author Andrew Sazonov
 * @version 1.0
 * @param <K> type of keys used to identify registry items
 * @param <V> type of values stored in the registry
 * @see ConsumingRegistry
 */

public interface ProvidingRegistry<K extends Serializable, V extends Serializable>
{
  /**
   * Registers item stored under given key
   *
   * @param aItemKey key of the item to be registered
   * @param aItem the item to be registered
   */
  public void registerItem(K aItemKey, V aItem);

  /**
   * Performs un-registration of the item under given key. Item will
   * be removed from the distributed registry
   *
   * @param aItemKey item to unregister
   */
  public void unRegisterItem(K aItemKey);

  /**
   * Forces registry to issue notification for all registered items.
   * Potentially, this method can be called on some scheduled basis
   * to provider "heart-beat" of registry (so client registries will be
   * re-notified about content published via registry).
   */
  public void notifyAllRegistrations();
}

/**
 * Extension to {@link ProvidingRegistry} that allows to obtain content
 * of items that was published by particular {@link ProvidingRegistry}.
 *
 * @author Andrew Sazonov
 * @version 1.0
 * @param <K> type of keys used to identify registry items
 * @param <V> type of values stored in the registry
 * @see ProvidingRegistry
 */

public interface DiscoverableProvidingRegistry<K extends Serializable, V extends Serializable>
        extends ProvidingRegistry<K, V>
{
  /**
   * List of items that were published by this provider registry
   *
   * @return items
   */
  public List<Map.Entry<K, V>> getOwnItems();
}

/**
* Generic interface for ConsumingRegistry. <code>ConsumingRegistry</code>
* is used to obtain information about items stored in distributed registry.
* Since there can be several ProvidingRegistries that publish different
* items under the same key, the <code>ConsumingRegistry</code> allows to
* obtain the set of items published by them under the particular key.
* <p/>
* In addition to obtaining information on current state of distributed
* registry, the <code>ConsumingRegistry</code> may also indicate that some
* items in the registry are invalid (therefore, if there are several
* <code>ConsumingRegistries</code>, they may handle such a
* notification).
*
* @author Andrew Sazonov
* @version 1.0
* @param <K> type of keys used to identify registry items
* @param <V> type of values stored in the registry
* @see ProvidingRegistry
*/


public interface ConsumingRegistry<K extends Serializable, V extends Serializable>
{
 /**
  * Indicates whether there were any changes in distributed registry occurred
  * due to synchronization since the last call of the <code>getItems()</code>
  * for given key.
  *
  * @param aItemKey key for items
  * @return true if the set of data items stored under the given key was
  *         changed since the last call of {@link #getItems}
  * @see #getItems
  */
 public boolean isDirty(K aItemKey);

 /**
  * Returns the set of items stored in the distributed registry under given
  * key.
  *
  * @param aItemKey key of items
  * @return set of items stored under given key
  */

 public Set<V> getItems(K aItemKey);

 /**
  * Returns list of available keys currently stored in registry (ones
  * which are actually stored in particular instance of consuming registry
  * or all published ones)
  *
  * @param aForceRefresh indicates whether request for available items
  * should be issued to distributed
  * registry before returning set of key
  * @return a set of available keys
  */
 public Set<K> getKeys(boolean aForceRefresh);

 /**
  * Provides ability to mark specific item  stored in the distributed
  * registry as invalid one.
  * It there are several <code>ConsumingRegistries<code> in the same
  * distributed registry, they can be notified of and be handled
  * properly. It's assumed that this call will not affect
  * ProvidingRegistries somehow.
  *
  * @param aItemKey key of the item
  * @param aItem the item which should be marked invalid
  */
 public void markItemInvalid(K aItemKey, V aItem);

 /**
  * Initiates requesting of items for given key by sending appropriate
  * notifications to ProvidingRegistries
  *
  * @param aItemKey if null, will request items for all available keys
  */
  public void requestItems(K aItemKey);

  /**
   * Removes listener from list of registered RegistryEventProcessors which
   * performs further processing of obtained external notifications
   *
   * @param aListener processor to be removed
   */
  public void removeRegistryEventProcessor(RegistryEventProcessor<K, V> aListener);

  /**
   * Adds listener to list of registered RegistryEventProcessors which
   * performs the  further processing of obtained external notifications
   *
   * @param aListener processor to be added
   */
  public void addRegistryEventProcessor(RegistryEventProcessor<K, V> aListener);

  /**
   * Closes this registry instance and performs all necessary cleanup. As
   * soon as registry is  closed, no actions may be performed within  it, so
   * calling this methods actually ends registry instance lifecycle.
   */
  public void close();

  /**
   * Indicated whether registry it in closed state
   *
   * @return <code>true</code> if registry instance is closed, false otherwise
   * @see #close()
   */
  public boolean isClosed();
}