// **********************************************************************
//
// Copyright (c) 2002
// IONA Technologies, Inc.
// Waltham, MA, USA
//
// All Rights Reserved
//
// **********************************************************************

#ifndef DISPATCH_IDL
#define DISPATCH_IDL

#pragma prefix "ooc.com"

//
// ORBacus extensions
//

module OB
{

/**
 *
 * This interface encaspulates a request.
 *
 * @see DispatchStrategy
 *
 **/

local interface DispatchRequest
{
    /**
     *
     * Execute the request in the current thread context.
     *
     **/
    void invoke();
};

/** An alias for a DispatchStrategyId. */
typedef unsigned long DispatchStrategyId;

/** The <code>SAME_THREAD</code> DispatchStrategyId. */
const DispatchStrategyId SAME_THREAD = 0;

/** The <code>THREAD_PER_REQUEST</code> DispatchStrategyId. */
const DispatchStrategyId THREAD_PER_REQUEST = 1;

/** The <code>THREAD_POOL</code> DispatchStrategyId. */
const DispatchStrategyId THREAD_POOL = 2;

/**
 *
 * This interface represents a dispatch strategy. To dispatch a
 * request the ORB will pass a DispatchRequest. The dispatch strategy
 * should call DispatchRequest::invoke() in the correct thread
 * context.
 *
 * @see DispatchRequest
 * @see DispatchStrategyFactory
 *
 */
local interface DispatchStrategy
{
    /**
     *
     * Determine the id of this DispatchStrategy.  The ids of the
     * built-in DispatchStrategy objects are <code>SAME_THREAD</code>,
     * <code>THREAD_PER_REQUEST</code> and <code>THREAD_POOL</code>.
     * Use DispatchStrategyFactory to create instances of these objects.
     *
     **/
    readonly attribute DispatchStrategyId id;

    /**
     *
     * Determine information specific to this DispatchStrategy.
     *
     **/
    readonly attribute any info;

    /**
     *
     * Called to cause a DispatchRequest to be run.
     *
     * @param r The request to execute.
     *
     **/
    void dispatch(in DispatchRequest r);
};

/** Alias for a thread pool identifier. */
typedef unsigned long ThreadPoolId;

exception InvalidThreadPool
{
};

/**
 *
 * This interface is a factory to create dispatch strategies, and to
 * manage thread pools.
 *
 * @see DispatchStrategy
 *
 **/
local interface DispatchStrategyFactory
{
    /**
     *
     * Create a thread pool containing nthreads.
     *
     * @param nthreads The number of threads the pool in the pool
     *
     **/
    ThreadPoolId create_thread_pool(in long nthreads);

    /**
     *
     * Destroy a thread pool with the given id. If the thread pool is
     * is use by an object adapter any new requests will cause an
     * <code>OBJ_ADAPTER</code> exception.
     *
     * @param id The thread pool id
     *
     * @exception InvalidThreadPool If the thread pool id is valid.
     *
     **/

    void destroy_thread_pool(in ThreadPoolId id)
	raises(InvalidThreadPool);

    /**
     *
     * Create a thread pool dispatch strategy.
     *
     * @param id The thread pool id
     *
     * @return A dispatch strategy
     *
     * @exception InvalidThreadPool If the thread pool id is valid.
     *
     **/
    DispatchStrategy create_thread_pool_strategy(in ThreadPoolId id)
	raises(InvalidThreadPool);

    /**
     *
     * Create a same thread dispatch strategy.
     *
     * @return A dispatch strategy
     *
     **/
    DispatchStrategy create_same_thread_strategy();

    /**
     *
     * Create a same thread per request dispatch strategy.
     *
     * @return A dispatch strategy
     *
     **/
    DispatchStrategy create_thread_per_request_strategy();

    /**
     *
     * Create a default dispatch strategy. The default dispatch
     * strategy is created according to the ooc.orb.oa.conc_model
     * property.
     *
     * @return A dispatch strategy
     *
     **/
    DispatchStrategy create_default_dispatch_strategy();
};

}; // End module OB

#endif
