/* Network-Integrated Multimedia Middleware (NMM)
 * http://www.motama.com/nmm.html
 *
 * Copyright (C) 2006-2007
 * Motama GmbH, Saarbruecken, Germany
 * http://www.motama.com
 *
 * This file is part of NMM. 
 * 
 * NMM is free software; you can redistribute it and/or modify it    
 * under the terms of the GNU General Public License as published by 
 * the Free Software Foundation; only version 2 of the License.      
 * 
 * NMM is distributed in the hope that it will be useful, but WITHOUT 
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 
 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public 
 * License for more details.  
 * 
 * You should have received a copy of the GNU General Public License 
 * along with NMM; if not, write to the Free Software Foundation,    
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 */


module NMM {

  /** \class IRegistry
   * Base class for all Registry Interfaces.
   */
  interface IRegistry {

    /** This method requests a Node and returns its INode interface. 
     *
     * If the Node can not be requested
     * an exception is thrown. This method calls the method reserveNode() to reserve the Node
     * and instantiateNode() to create it.
     * 
     * @param reg The RegistryID of the Registry which manages the node.
     * @param node_id The ObjectID of the Node that is requested.
     * @param info The UserInfo of the application that requests the node.
     * @param nd NodeDescription describing the node
     * @return INode interface for requested Node
     * @sa reserveNode()
     * @sa instantiateNode()
     */
    INode* requestNode(in RegistryID reg, in ObjectID node_id, in UserInfo info, inout NodeDescription nd)
      raises (RegistryException);

    /** This method requests a Object and returns its interface. 
     *
     * If the objecte can not be requested an exception is thrown. 
     *
     * @param reg The RegistryID of the Registry which manages the node.
     * @param node_id The ObjectID of the object that is requested.
     * @param info The UserInfo of the application that requests the object.
     * @return Interface for requested object
     */
    Interface* requestObject(in RegistryID reg, in ObjectID node_id, in UserInfo info)
      raises (RegistryException);

    /** This method releases a requested Node. 
     *
     * This method calls the method releasReservation() to
     * to release the reservation and destroyNode() to delete it.
     *
     * @param reg_id The RegistryID of the Registry which manages the node.
     * @param ref The NMMReference of the Node that is released.
     * @param node_id The ObjectID of the Node that is released.
     * @param user_info The UserInfo of the application that requested the node.
     * @sa releaseReservation()
     * @sa destroyNode()
     */
    void  releaseNode(in RegistryID reg_id, in NMMReference ref, in ObjectID node_id, in UserInfo user_info);

    /** This method releases a requested object. 
     *
     * @param reg_id The RegistryID of the Registry which manages the object.
     * @param ref The NMMReference of the object that is released.
     * @param node_id The ObjectID of the object that is released.
     * @param user_info The UserInfo of the application that requested the object.
     */
    void  releaseObject(in RegistryID reg_id, in NMMReference ref, in ObjectID node_id, in UserInfo user_info);

    /** Searches for Nodes with capabilities described in given NodeDescription.
     *
     * This method searches for Nodes with certain capabilities, which are described in the
     * NodeDescription.
     *
     * @param node_desc The NodeDescription with the requirements of a searched node.
     * @return list of Responses 
     */
    list<Response>   initRequest(in NodeDescription node_desc) const;

    /** This method searches for objects with certain capabilities, which are described in the
     * ObjectDescription.
     *
     * @param node_desc The ObjectDescription with the requirements of a searched object.
     * @return list of Responses for request
     */
    list<Response>   initObjectRequest(in ObjectDescription node_desc) const;

    /** Searches for Node matching the given NodeDescription.
     *
     * This method searches for a specific node that matches the given NodeDescription. The NodeDescription
     * is created by an application and stores the information, like formats and interfaces, that must be
     * supported by the node.
     *
     * @param registry_id The RegistryID of the Registry that should be searched.
     * @param node_desc The NodeDescription that must be supported by the nodes
     * @return A list of ObjectID's from nodes that support the requirements in the NodeDescription
     */
    list<ObjectID>     searchNode(in RegistryID registry_id, in NodeDescription node_desc) const;

    /** Reserves node managed by given Registry.
     *
     * This method reserves a node which is managed by a Registry. If the reservation is succesfull,
     * the Registry returns a FactoryTickt that allows the caller to instantiate a Node by a NodeFactory.
     *
     * @param reg_id The RegistryID of the Registry that should be searched.
     * @param node_id The ObjectID of the Node which is used to identify the Node inside the Registry
     * @param info The UserInfo identifies the user that requests the Node. If the node is released this parameter must be specified again, whereby no other user can release the reserved node.
     * @return FactoryTickt that allows the caller to instantiate a Node by a NodeFactory
     */
    FactoryTicket reserveNode(in RegistryID reg_id, in ObjectID node_id, in UserInfo info)
      raises (RegistryException);


    /** Creates an instance of a reserved node.
     *
     * This method creates an instance of a reserved node. If the node can be created its INode interface is
     * returned. Otherwise an exception is thrown.
     *
     * @param reg_id The RegistryID of the Registry that should be searched.
     * @param ticket The FactoryTicket must be send to allow the Registry to instantiate the node
     * @param info The UserInfo identifies the user that requests the Node. If the node is released
     *        this parameter must be specified again, whereby no other user can release the reserved node.
     * @return INode interface for instantiated Node
     * @sa destroyNode
     */
    INode* instantiateNode(in RegistryID reg_id, in FactoryTicket ticket, in UserInfo info)
      raises (RegistryException);


    /** Releases a reserved node.
     *
     * This method releases a reserved node. The node is not destroyed, only th reservation is released.
     * @param reg_id The RegistryID of the Registry that should be searched.
     * @param node_id The ObjectID of the reserved node
     * @param user_info The UserInfo identifies the user that requests the Node. If the node is released
     *        this parameter must be specified again, whereby no other user can release the reserved node.
     * @sa reserveNode
     */
    void releaseReservation(in RegistryID reg_id, in ObjectID node_id, in UserInfo user_info);


    /** This method destroys a created node.
     *
     * @param reg_id The RegistryID of the Registry that should be searched.
     * @param reference The NMMReference of the instantiated node.
     * @param info The UserInfo identifies the user that requests the Node. If the node is released
     *        this parameter must be specified again, whereby no other user can release the reserved node.
     * @sa instantiateNode
     */
    void destroyNode(in RegistryID reg_id, in NMMReference reference, in UserInfo info);


    /** This method returns the maximum instance count for a specific node.
     *
     * @param reg_id The RegistryID of the Registry that should be searched.
     * @param node_id The ObjectID of the node.
     * @return maximum instance count for specified node
     */
    nmm_int32 getMaxInstanceCount(in RegistryID reg_id, in ObjectID node_id)  const;


    /** This method returns the current instance count for a specific node.
     *
     * @param reg_id The RegistryID of the Registry that should be searched.
     * @param node_id The ObjectID of the node.
     * @return current instance count for specified node
     */
    nmm_int32 getInstanceCount(in RegistryID reg_id, in ObjectID node_id)     const;


    /** This method returns the library that must be load for a specific node.
     *
     * @param reg_id The RegistryID of the Registry that should be searched.
     * @param node_id The ObjectID of the node.
     * @return library that must be loaded for specified node
     */
    string getPluginInfo(in RegistryID reg_id, in ObjectID node_id)     const;

    /** This method returns ObjectIDs of all nodes that are available.
     *
     * @param reg_id The RegistryID of the Registry that should be searched.
     * @return ObjectIDs of all nodes that are available
     */
    list<ObjectID> getNodeList(in RegistryID reg_id) const;

    /** This method returns ObjectIDs of all nodes that are currently reserved and not available.
     *
     * @param reg_id The RegistryID of the Registry that should be searched.
     * @return ObjectIDs of all nodes that are currently reserved and not available
     */
    list<ObjectID> getReservedNodeList(in RegistryID reg_id) const;

    /** This method returns a short NodeInfo for all nodes that are managed in a specific registry.
     *
     * @param reg_id The RegistryID of the Registry that should be searched.
     * @return list of NodeInfos of all nodes managed in specified registry
     */
    list<NodeInfo> getNodeInfoList(in RegistryID reg_id) const;

    /** This method returns the complete NodeDescription of a specifc node.
     *
     * @param reg_id The RegistryID of the Registry that should be searched.
     * @param node_id The ObjectID of the node.
     * @return NodeDescription of specified node
     */
    NodeDescription getNodeDescription(in RegistryID reg_id, in ObjectID node_id ) const;

    /** This method returns all NodeDescriptions stored by a Registry.
     *
     * @param reg_id The RegistryID of the Registry that should be searched.
     * @return list of all NodeDescriptions stored by specified registry
     */
    list<NodeDescription> getNodeDescriptionList(in RegistryID reg_id) ;

    /** This method returns the NodeFactoryID of the NodeFactory that can instantiate a specific node.
     *
     * @param reg_id The RegistryID of the Registry that should be searched.
     * @param node_id The ObjectID of the node.
     * @return NodeFactoryID of the NodeFactory that can instantiate specified node
     */
    NodeFactoryID getNodeFactoryID(in RegistryID reg_id, in ObjectID node_id) const ;

    /** This method releases ALL Nodes.
     */
    void resetInternalReservation();

    /** This method releases ALL Nodes reserved by specifc user.
     *
     * @param user_info UserInfo specifying user which Nodes should be released
     */
    void resetSpecificInternalReservation(in UserInfo user_info);


    /** This method enables the access control. 
     *
     * If the access control is enabled, no other application can access the Registry.
     *
     * @param info The UserInfo of the application that tries to enable the access control.
     */
    void initTransaction(in UserInfo info) raises (RegistryException);

    /** This method disables the access control, so other applications can access the Registry again.
     *
     * @param info The UserInfo of the application that tries to disable the access control.
     */
    void closeTransaction(in UserInfo info);


    /** This method returns the RegistryID of this Registry.
     *
     * @return RegistryID of this Registry
     */
    RegistryID getRegistryID() const;

    /** This method returns the RegistryID's of all child-Registries.
     *   
     * @param registry_id Registry to get lis of children 
     * @return list of registry children of given Registry
     */
    list<RegistryID> getChildList(in RegistryID registry_id) const;

    /** Tests if Registry is managed by this Registry or by one of its children.
     *
     * This method returns true, if the Registry with given RegistryID is managed by this
     * Registry or by one the children of the Registry.
     *
     * @param reg_id The RegistryID of the searched Registry.
     * @return true if Registry is manager by this Registry or one of its children, false otherwise
     */
    nmm_bool isSubRegistry(in RegistryID reg_id) const;

    /** Returns RegistryMemento.
     *
     * @return RegistryMemento
     */
    RegistryMemento getMemento();

    /** Sets RegistryMemento.
     *
     * @param rm RegistryMemento to set
     */
    void setMemento(in RegistryMemento rm);
  };


}

