/**
  * File: Properties.idl
  * Content: Definition of the Properties handling operations
  * Author: LuisM Pena
  * Date: 11th April 2001
  * Version: 0.51.00
  * Last change:
  *
  **/

#ifndef PROPERTIES_IDL
#define PROPERTIES_IDL

#include "DomainExceptions.idl"
#include "StateTransfer.idl"

module sensei
{

  module middleware
  {

    module domains
    {

      struct MemberProperties
      {
        GroupMemberId member;
        Properties props;
      };

      typedef sequence <MemberProperties> MemberPropertiesList;

      /***********************************************************************/
      /************************* PROPERTY DISABLED EXCEPTION *****************/
      /***********************************************************************/

      /**
       * Exception thrown when using properties if the user has disabled them
       */
      exception PropertiesDisabledException
      {
      };

      /***********************************************************************/
      /************************* PROPERTIES LISTENER *************************/
      /***********************************************************************/

      /**
       * Interface to be implemented by members using properties
       */
      interface PropertiesListener
      {
        /**
         * Only are received the notifications from the members who update their properties.
         */
        void propertiesUpdated (in Location loc);
      };

      /***********************************************************************/
      /************************* PROPERTIES HANDLER **************************/
      /***********************************************************************/

      interface PropertiesHandler
      {
        /**
         * Enables the use of properties, which is disabled by default.
         * This method must be invoked before the member joins the group, or an exception is raised.
         * Every member in the group must use the same properties
         * policy.
         */
        void enableProperties()
          raises (MemberStateException);

        /**
         * Returns the properties policy
         */
        boolean arePropertiesEnabled();

        /**
         * Sets a PropertiesListener, that will receive the properties update notifications. The user
         * can be set at any moment, and if a nil user is specified, no user will be used.
         */
        void setPropertiesListener(in PropertiesListener listener)
          raises (PropertiesDisabledException);

        /**
         * Returns the properties of all the members with state.
         * Properties are only available once the member has received the state. Otherwise, an
         * MemberStateException is thrown
         */
        MemberPropertiesList getAllProperties ()
          raises (MemberStateException, PropertiesDisabledException);

        /**
         * Returns the property with the given name of all the members with state.
         * Properties are only available once the member has received the state. Otherwise, an
         * MemberStateException is thrown
         */
        MemberPropertiesList getPropertyForAllMembers (in Name nam)
          raises (MemberStateException, PropertiesDisabledException);

        /**
         * Returns the properties of the specified member.
         * Properties are only available once the member has received the state. Otherwise, an
         * MemberStateException is thrown
         */
        Properties getMemberProperties (in Location loc)
          raises (MemberStateException, PropertiesDisabledException);

        /**
         * Returns the property with the given name for the specified member.
         * Properties are only available once the member has received the state. Otherwise, an
         * MemberStateException is thrown
         */
        Value getMemberProperty (in Location loc, in Name n)
          raises (MemberStateException, PropertiesDisabledException);

        /**
         * Returns the properties of the member handled by this PropertyHandler.
         * Properties for a given member are available at any moment, not just after the member receives the state
         */
        Properties getProperties()
          raises (PropertiesDisabledException);

        /**
         * Returns the property with the given name for the member handled by this PropertyHandler.
         * Properties for a given member are available at any moment, not just after the member receives the state
         */
        Value getProperty(in Name n)
          raises (PropertiesDisabledException);

        /**
         * Sets the properties for the member handled by this PropertyHandler.
         * Properties for a given member are available at any moment, not just after the member receives the state.
         * The properties are propagated to the group if the member has state, otherwise the other members will
         * know the changes once the transfer finishes.
         */
        void setProperties (in Properties props)
          raises (MemberStateException, PropertiesDisabledException);

        /**
         * Adds the properties for the member handled by this PropertyHandler. If some property were already
         * existing, its value is overriden.
         * Properties for a given member are available at any moment, not just after the member receives the state.
         * The properties are propagated to the group if the member has state, otherwise the other members will
         * know the changes once the transfer finishes.
         */
        void addProperties (in Properties props)
          raises (MemberStateException, PropertiesDisabledException);

        /**
         * Removes the properties for the member handled by this PropertyHandler. If some property were not
         * existing, it is ignored.
         * Properties for a given member are available at any moment, not just after the member receives the state.
         * The properties are propagated to the group if the member has state, otherwise the other members will
         * know the changes once the transfer finishes.
         */
        void removeProperties (in Properties props)
          raises (MemberStateException, PropertiesDisabledException);
      };

    };
  };
};

#endif