#ifndef __Entity_Idl__
#define __Entity_Idl__

/*
 * Copyright (C) 2001 CERN - European Organization for Nuclear Research
 * All rights reserved.
 *
 * @author $Author: abranson $ $Date: 2005/04/26 06:47:48 $
 * @version $Revision: 1.24 $
 */

#include <CommonTypes.idl>

#pragma prefix "c2kernel.com"

module entity
{
    /**************************************************************************
    * ManageableEntity is an <i>uniquely identifiable CORBA object</i>.
    *
    * - It is persistent or not. This is relevant when the timelife of it
    *   is very short and/or there is no need for recovery from crash.
    **************************************************************************/
    abstract interface ManageableEntity
    {

        /**
        * <p>System generated unique key of the Entity. It is unique
        * in the context defined by the domain expert which is to
        * define the root NamingContext in the Naming Service
        * (ie. return of orb.resolve_initial_references("NameService") ).
        * <p>In principle it is equivalent with an OID of an object in a
        * OODBMS or with an IOR defined on CORBA.
        **/
        unsigned long getSystemKey();


        /**
        * The description for operation getData.
        *
        * @param xpath A not so dummy argument.
        *             - LifeCycle
        *             - Collection
        *             - History
        *             - Properties
        *             - JobList
        *             - Capabilities
        *
        * @return The result string in xml format.
        *
        * @exception ObjectNotFoundException 'what' was not found.
        **/
        string queryData( in string xpath )
            raises( common::AccessRightsException,
                    common::ObjectNotFoundException,
                    common::PersistencyException );
    };


    /**************************************************************************
    *
    **************************************************************************/
    interface Agent : ManageableEntity
    {
        void initialise( in string  agentProps )
            raises( common::AccessRightsException,
                    common::InvalidDataException,
                    common::PersistencyException );
		void refreshJobList( in unsigned long sysKey, in string stepPath, in string newJobs );
		void addRole( in string roleName )
			raises( common::ObjectNotFoundException,
					common::CannotManageException );
		void removeRole( in string roleName )
			raises( common::ObjectNotFoundException,
					common::CannotManageException );
    };


    /**************************************************************************
    * Item is an ManageableEntity which have LifeCycle(s) and can have a
    * History, Collections and Queries.
    *
    * <p><pre>Here is the summary of the different Item configuration:
    * - It always has one or more LifeCycles.
    * - It is persistent or not. This is relevant when the Item's LifeCycle
    *   is very short and/or there is no need for recovery from crash.
    *   It is very likely that an Item with no persistency cannot use Queries.
    * - Item can have only one History. It is possible to have an Item
    *   without History which means it does not support audit trailing.
    *   An Item with no persistency very likely won't need the History.
    * - Item can have many Collection of the different types (see: {@link CollectionBase}).
    *   In the simple case Item have one Collection for each type but it
    *   also should be able to have many Collections of the same type.
    *   Note that for the later collections have to be named in order to
    *   identify them!
    * - Item can have a list of named Queries (can be empty list).
    *
    * One extreme is to create a non persistent Item which has only
    *   the LifeCycle. This Item can 'only' generate Events in the proper order
    *   and execute special Actions which are implemented by the domain user.
    *   A simple user code could be such an Item!
    *</pre>
    *
    * @author kovax
    * @version 1.0
    **************************************************************************/

    interface Item : ManageableEntity
    {
        /**
        *
        * @param
        *
        * @exception ObjectNotFoundException
        **/
        void initialise( in unsigned long agentId,
        				 in string  itemProps,
                         in string  workflow )
            raises( common::AccessRightsException,
                    common::InvalidDataException,
                    common::PersistencyException );

        /**
        * The Agent reguests one Step in the LifeCycle to perform one Transition.
        * Item delegetes this request to its LifeCycle object.
        *
        * @param agentInfo Complete identification of the Agent. It is used
        *   to check the rigths of the Agent (see:{@link AccessRigthsException})
        *
        * @param lifeCycleID
        *
        * @param stepPath The id of the Step in the LifeCycle tree
        *
        * @param transitionID The id of the Transition
        *
        * @param reguestData Domain specific data required to process the
        *   request (eg. conidtions).
        *
        * @exception AccessRigthsException The Agent has no rigths
        *   to make the request.
        * @exception InvalidTransitionException It is impossible to
        *   perform the Transition.
        * @exception ObjectNotFoundException Step does not exists.
        **/
        void requestAction( in unsigned long       agentID,
                            in string              stepPath,
                            in unsigned long       transitionID,
                            in string    requestData
                          )
            raises( common::AccessRightsException,
                    common::InvalidTransitionException,
                    common::ObjectNotFoundException,
                    common::InvalidDataException,
                    common::PersistencyException,
                    common::ObjectAlreadyExistsException );


        /**
        * Queries the LifeCycle for Steps with different conditions. Returns the
        * xml string containing the Steps matching those conditions.
        *
        * @param agentInfo Complete identification of the Agent. It is used
        * if 'filter' is true.
        *
        * @param stateID The ID of the State (eg. Active)
        *
        * @param filter false: All the Steps; true: Steps for the Agent only (ID ,role)
        *
        * @return The result string in xml format (could be many Steps, or nothing).
        **/
        string queryLifeCycle( in unsigned long       agentId,                              
                               in boolean             filter )
            raises( common::AccessRightsException,
                    common::ObjectNotFoundException,
                    common::PersistencyException );


    }; //end of Item

}; //end of module entity

#endif //__Entity_Idl__