/*

 * Copyright 2000-2003 Sun Microsystems, Inc.  All Rights Reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun in the LICENSE file that accompanied this code.

 *

 * This code 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

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

/*

 * Differences from original:

 *

 * - do not include orb.idl

 * - include IOP.idl, Messaging.idl and CORBAX.idl

 * - renamed component parameter names to tagged_component (so that they 

 *   do not conflict with the CORBA 3.0 "component" keyword).

 * - javadocs added (synchronized with orbos/00-08-06)

 * 

 * NOTE: After compilation of this IDL file, all Helper and Holder classes

 * that are not needed are removed.

 */

#include "IOP.idl"

#include "Messaging.idl"

#include "CORBAX.idl"

#include "corba.idl"

#pragma prefix "omg.org"

#ifndef CORBA3

#define local

#endif

module Dynamic {

  /**

   * <code>NVList</code> PIDL represented by <code>ParameterList</code> IDL.  

   * This exists in order to keep the Portable Interceptor IDL from becoming 

   * PIDL.

   */

  struct Parameter {

    any argument;

    CORBA::ParameterMode mode;

  };

  /**

   * <code>NVList</code> PIDL represented by <code>ParameterList</code> IDL.  

   * This exists in order to keep the Portable Interceptor IDL from becoming 

   * PIDL.

   */

  typedef sequence<Parameter> ParameterList;

  /**

   * <code>ContextList</code> PIDL represented by <code>ContextList</code> 

   * IDL.  This exists in order to keep the Portable Interceptor IDL from 

   * becoming PIDL.

   */

  typedef CORBA::StringSeq ContextList;

  /**

   * <code>ExceptionList</code> PIDL represented by <code>ExceptionList</code> 

   * IDL.  This exists in order to keep the Portable Interceptor IDL from 

   * becoming PIDL.

   */

  typedef sequence<CORBA::TypeCode> ExceptionList;

  /**

   * <code>Context</code> PIDL represented by <code>RequestContext</code> 

   * IDL.  This exists in order to keep the Portable Interceptor IDL from o

   * becoming PIDL.

   * <p>

   * <code>Context</code> objects are encoded as <code>String[]</code>.  The 

   * <code>Strings</code> occur in pairs.  The first <code>String</code> in 

   * each pair is the context property name and the second <code>String</code>

   * in each pair is the associated value.

   */

  typedef CORBA::StringSeq RequestContext;

};

module PortableInterceptor {

  /**

   * All Portable Interceptors implement Interceptor.

   */

  local interface Interceptor {

    /**

     * Returns the name of the interceptor.

     * <p>

     * Each Interceptor may have a name that may be used administratively 

     * to order the lists of Interceptors. Only one Interceptor of a given 

     * name can be registered with the ORB for each Interceptor type. An 

     * Interceptor may be anonymous, i.e., have an empty string as the name 

     * attribute. Any number of anonymous Interceptors may be registered with 

     * the ORB.

     *

     * @return the name of the interceptor.

     */

    readonly attribute string name;

    // Added in ptc/00-08-06

    /**

     * Provides an opportunity to destroy this interceptor.

     * The destroy method is called during <code>ORB.destroy</code>. When an 

     * application calls <code>ORB.destroy</code>, the ORB:

     * <ol>

     *   <li>waits for all requests in progress to complete</li>

     *   <li>calls the <code>Interceptor.destroy</code> operation for each 

     *       interceptor</li>

     *   <li>completes destruction of the ORB</li>

     * </ol>

     * Method invocations from within <code>Interceptor.destroy</code> on 

     * object references for objects implemented on the ORB being destroyed 

     * result in undefined behavior. However, method invocations on objects 

     * implemented on an ORB other than the one being destroyed are 

     * permitted. (This means that the ORB being destroyed is still capable 

     * of acting as a client, but not as a server.) 

     */

    void destroy();

  };

  /**

   * The <code>ForwardRequest</code> exception is the means by which an 

   * Interceptor can indicate to the ORB that a retry of the request should 

   * occur with the new object given in the exception. This behavior of 

   * causing a retry only occurs if the ORB receives a ForwardRequest from 

   * an interceptor. If <code>ForwardRequest</code> is thrown anywhere else 

   * it is passed through the ORB as is normal for a user exception. 

   * <p>

   * If an Interceptor throws a <code>ForwardRequest</code> exception in 

   * response to a call of an interceptor, no other Interceptors are called 

   * for that interception point. The remaining Interceptors in the Flow Stack 

   * shall have their appropriate ending interception point called: 

   * <code>receive_other</code> on the client, or <code>send_other</code> on 

   * the server. The <code>reply_status</code> in the 

   * <code>receive_other</code> or <code>send_other</code> would be 

   * <code>LOCATION_FORWARD</code>.

   */

  exception ForwardRequest {

    /** 

     * The new object to forward the request to.

     */

    Object forward;

//   Change in ptc/00-08-06

//    boolean permanent;

  };

  /** Reply status, represented as an int */

  typedef short ReplyStatus;

  // Valid reply_status values:

  /**

   * Indicates a successful Reply Status. One possible value for 

   * <code>RequestInfo.reply_status</code>.

   * @see RequestInfo#reply_status

   * @see SYSTEM_EXCEPTION

   * @see USER_EXCEPTION

   * @see LOCATION_FORWARD

   * @see TRANSPORT_RETRY

   */

  const ReplyStatus SUCCESSFUL = 0;

  /**

   * Indicates a SystemException reply status. One possible value for 

   * <code>RequestInfo.reply_status</code>.

   * @see RequestInfo#reply_status

   * @see SUCCESSFUL

   * @see USER_EXCEPTION

   * @see LOCATION_FORWARD

   * @see TRANSPORT_RETRY

   */

  const ReplyStatus SYSTEM_EXCEPTION = 1;

  /**

   * Indicates a UserException reply status. One possible value for 

   * <code>RequestInfo.reply_status</code>.

   * @see RequestInfo#reply_status

   * @see SUCCESSFUL

   * @see SYSTEM_EXCEPTION

   * @see LOCATION_FORWARD

   * @see TRANSPORT_RETRY

   */

  const ReplyStatus USER_EXCEPTION = 2;

  /**

   * Indicates a LocationForward reply status. One possible value for 

   * <code>RequestInfo.reply_status</code>.

   * @see RequestInfo#reply_status

   * @see SUCCESSFUL

   * @see SYSTEM_EXCEPTION

   * @see USER_EXCEPTION

   * @see TRANSPORT_RETRY

   */

  const ReplyStatus LOCATION_FORWARD = 3;

// Changes in ptc/00-08-06

//  const ReplyStatus LOCATION_FORWARD_PERMANENT = 4;

  /**

   * Indicates a Transport Retry reply status. One possible value for 

   * <code>RequestInfo.reply_status</code>.

   * @see RequestInfo#reply_status

   * @see SUCCESSFUL

   * @see SYSTEM_EXCEPTION

   * @see USER_EXCEPTION

   * @see LOCATION_FORWARD

   */

  const ReplyStatus TRANSPORT_RETRY = 4;

  /**

   * XXX

   */

  const ReplyStatus UNKNOWN = 5;

  /** Slot id, represented as an int */

  typedef unsigned long SlotId;

  /**

   * This exception is thrown when <code>get_slot</code> or 

   * <code>set_slot</code> is called on a slot that has not been allocated.

   */

  exception InvalidSlot {};

  /**

   * Portable Interceptors Current (also known as <code>PICurrent</code>) 

   * is merely a slot table, the slots of which are used by each service to 

   * transfer their context data between their context and the request's or 

   * reply's service context. Each service which wishes to use PICurrent 

   * reserves a slot or slots at initialization time and uses those slots 

   * during the processing of requests and replies.

   * <p>

   * Before an invocation is made, PICurrent is obtained via a call to 

   * <code>ORB.resolve_initial_references( "PICurrent" )</code>. From within 

   * the interception points, the data on PICurrent that has moved from the 

   * thread scope to the request scope is available via the 

   * <code>get_slot</code> operation on the <code>RequestInfo</code> object. 

   * A PICurrent can still be obtained via 

   * <code>resolve_initial_references</code>, but that is the Interceptor's 

   * thread scope PICurrent.

   */

  local interface Current : CORBA::Current {

    /**

     * Retrieves the slot data the application set in PICurrent via 

     * <code>get_slot</code>.  The data is in the form of an Any. 

     * <p>

     * If the given slot has not been set, an Any containing a type code 

     * with a <code>TCKind</code> value of <code>tk_null</code> and no value 

     * is returned. 

     *

     * @param id The <code>SlotId</code> of the slot from which the data will 

     *     be returned. 

     * @return The data, in the form of an Any, of the given slot identifier.

     * @exception InvalidSlot thrown if get_slot is called on a slot that 

     *     has not been allocated. 

     * @exception BAD_INV_ORDER thrown if <code>get_slot</code> is called 

     *     from within an ORB initializer 

     */

    any get_slot (in SlotId id) raises (InvalidSlot);

    /**

     * Sets data in a slot. The data is in the form of an Any. If data 

     * already exists in that slot, it is overridden. 

     *

     * @param id The <code>SlotId</code> of the slot to which the data will 

     *     be set. 

     * @param data The data, in the form of an Any, which will be set 

     *     to the identified slot. 

     * @exception InvalidSlot thrown if <code>set_slot</code> is called on 

     *     a slot that has not been allocated.

     * @exception BAD_INV_ORDER thrown if <code>set_slot</code> is called 

     *     from within an ORB initializer. 

     */

    void set_slot (in SlotId id, in any data) raises (InvalidSlot);

  };

  /**

   * Request Information, accessible to Interceptors.

   * <p>

   * Each interception point is given an object through which the 

   * Interceptor can access request information. Client-side and server-side 

   * interception points are concerned with different information, so there 

   * are two information objects: <code>ClientRequestInfo</code> is passed 

   * to the client-side interception points and <code>ServerRequestInfo</code>

   * is passed to the server-side interception points. But there is 

   * information that is common to both, so they both inherit from a common 

   * interface: <code>RequestInfo</code>.

   *

   * @see ClientRequestInfo

   * @see ServerRequestInfo

   */

  local interface RequestInfo {

    /**

     * Returns an id that uniquely identifies an active request/reply 

     * sequence. Once a request/reply sequence is concluded this ID may be 

     * reused. Note that this id is not the same as the GIOP 

     * <code>request_id</code>. If GIOP is the transport mechanism used, 

     * then these IDs may very well be the same, but this is not guaranteed 

     * nor required.

     */

    readonly attribute unsigned long request_id;

    /**

     * Returns the name of the operation being invoked.

     */

    readonly attribute string operation;

    /**

     * Returns an array of <code>Parameter</code> objects, containing the 

     * arguments on the operation being invoked.  If there are no arguments, 

     * this attribute will be a zero length array. 

     * <p>

     * Not all environments provide access to the arguments. With the Java 

     * portable bindings, for example, the arguments are not available. 

     * In these environments, when this attribute is accessed, 

     * <code>NO_RESOURCES</code> will be thrown with a standard minor code 

     * of 1.

     * <p>

     * <i>Note: Arguments are available for DSI/DII calls.</i>

     *

     * @exception NO_RESOURCES thrown if arguments are not available.

     * @see <a href="package-summary.html#unimpl">

     *     <code>PortableInterceptor</code> package comments for 

     *     limitations / unimplemented features</a>

     */

    readonly attribute Dynamic::ParameterList arguments;

    /**

     * Returns an array of <code>TypeCode</code> objects describing the 

     * <code>TypeCode</code>s of the user exceptions that this operation 

     * invocation may throw. If there are no user exceptions, this 

     * will return a zero length array. 

     * <p>

     * Not all environments provide access to the exception list. With 

     * the Java portable bindings, for example, the exception list is 

     * not available. In these environments, when this attribute is 

     * accessed, <code>NO_RESOURCES</code> will be thrown with a 

     * standard minor code of 1.

     * <p>

     * <i>Note: Exceptions are available for DSI/DII calls.</i>

     *

     * @exception NO_RESOURCES thrown if exceptions are not available.

     * @see <a href="package-summary.html#unimpl">

     *     <code>PortableInterceptor</code> package comments for 

     *     limitations / unimplemented features</a>

     */

    readonly attribute Dynamic::ExceptionList exceptions;

    /**

     * Returns an array of <code>String</code> objects describing the 

     * contexts that may be passed on this operation invocation.  If there 

     * are no contexts, this will return a zero length array. 

     * <p>

     * Not all environments provide access to the context list. With the 

     * Java portable bindings, for example, the context list is not 

     * available. In these environments, when this attribute is accessed, 

     * <code>NO_RESOURCES</code> will be thrown with a standard minor code 

     * of 1.

     * <p>

     * <i>Note: Contexts are available for DSI/DII calls.</i>

     *

     * @exception NO_RESOURCES thrown if contexts are not available.

     * @see <a href="package-summary.html#unimpl">

     *     <code>PortableInterceptor</code> package comments for 

     *     limitations / unimplemented features</a>

     */

    readonly attribute Dynamic::ContextList contexts;

    /**

     * Returns an array of <code>String</code> objects containing the 

     * contexts being sent on the request.

     * <p>

     * Not all environments provide access to the context. With the Java 

     * portable bindings, for example, the context is not available. In 

     * these environments, when this attribute is accessed, NO_RESOURCES will 

     * be thrown with standard minor code of 1.

     * <p>

     * <i>Note: <code>operation_context</code> is available for 

     * DSI/DII calls.</i>

     *

     * @exception NO_RESOURCES thrown if operation context is not available.

     * @see <a href="package-summary.html#unimpl">

     *     <code>PortableInterceptor</code> package comments for 

     *     limitations / unimplemented features</a>

     */

    readonly attribute Dynamic::RequestContext operation_context;

    /**

     * Returns an any containing the result of the operation invocation. 

     * If the operation return type is void, this attribute will be an any 

     * containing a type code with a <code>TCKind</code> value of 

     * <code>tk_void</code> and no value. 

     * <p>

     * Not all environments provide access to the result. With the Java 

     * portable bindings, for example, the result is not available. In 

     * these environments, when this attribute is accessed, 

     * <code>NO_RESOURCES</code> will be thrown with a standard minor code of 

     * 1.

     * <p>

     * <i>Note: Result is available for DSI/DII calls.</i>

     *

     * @exception NO_RESOURCES thrown if result is not available.

     * @see <a href="package-summary.html#unimpl">

     *     <code>PortableInterceptor</code> package comments for 

     *     limitations / unimplemented features</a>

     */

    readonly attribute any result;

    /**

     * Indicates whether a response is expected. 

     * <p>

     * On the client, a reply is not returned when 

     * <code>response_expected</code> is false, so <code>receive_reply</code> 

     * cannot be called. <code>receive_other</code> is called unless an 

     * exception occurs, in which case <code>receive_exception</code> is 

     * called. 

     * <p>

     * On the client, within <code>send_poll</code>, this attribute is true.

     */

    readonly attribute boolean response_expected;

    /**

     * Defines how far the request shall progress before control is returned

     * to the client.  This is defined in the Messaging specification, and 

     * is pertinent only when <code>response_expected</code> is false. If 

     * <code>response_expected</code> is true, the value of 

     * <code>sync_scope</code> is undefined. This attribute may have one of 

     * the following values: 

     * <ul>

     *   <li><code>Messaging.SYNC_NONE</code></li>

     *   <li><code>Messaging.SYNC_WITH_TRANSPORT</code></li>

     *   <li><code>Messaging.SYNC_WITH_SERVER</code></li>

     *   <li><code>Messaging.SYNC_WITH_TARGET</code></li>

     * </ul>

     * On the server, for all scopes, a reply will be created from the 

     * return of the target operation call, but the reply will not return 

     * to the client. Although it does not return to the client, it does 

     * occur, so the normal server-side interception points are 

     * followed (i.e., <code>receive_request_service_contexts</code>, 

     * <code>receive_request</code>, <code>send_reply</code> or 

     * <code>send_exception</code>). 

     * <p>

     * For <code>SYNC_WITH_SERVER</code> and <code>SYNC_WITH_TARGET</code>, 

     * the server does send an empty reply back to the client before the 

     * target is invoked. This reply is not intercepted by server-side 

     * Interceptors.

     * 

     * @see <a href="package-summary.html#unimpl">

     *     <code>PortableInterceptor</code> package comments for 

     *     limitations / unimplemented features</a>

     */

    readonly attribute Messaging::SyncScope sync_scope;

    /**

     * Describes the state of the result of the operation invocation. The

     * return value can be one of the following: 

     * <ul>

     *   <li><code>PortableInterceptor.SUCCESSFUL</code></li>

     *   <li><code>PortableInterceptor.SYSTEM_EXCEPTION</code></li>

     *   <li><code>PortableInterceptor.USER_EXCEPTION</code></li>

     *   <li><code>PortableInterceptor.LOCATION_FORWARD</code></li>

     *   <li><code>PortableInterceptor.TRANSPORT_RETRY</code></li>

     * </ul>

     * On the client:

     * <ul>

     *   <li>Within the <code>receive_reply</code> interception point, this 

     *       will only return <code>SUCCESSFUL</code></li>.

     *   <li>Within the <code>receive_exception</code> interception point, 

     *       this will be either <code>SYSTEM_EXCEPTION</code> or 

     *       <code>USER_EXCEPTION</code>.</li>

     *   <li>Within the <code>receive_other</code> interception point, this 

     *       will be any of: <code>SUCCESSFUL</code>, 

     *       <code>LOCATION_FORWARD</code>, or <code>TRANSPORT_RETRY</code>. 

     *       <code>SUCCESSFUL</code> means an asynchronous request returned 

     *       successfully. <code>LOCATION_FORWARD</code> means that a reply 

     *       came back with <code>LOCATION_FORWARD</code> as its status. 

     *       <code>TRANSPORT_RETRY</code> means that the transport 

     *       mechanism indicated a retry - a GIOP reply with a status of 

     *       <code>NEEDS_ADDRESSING_MODE</code>, for instance. </li>

     * </ul>

     * On the server: 

     * <ul>

     *   <li>Within the <code>send_reply</code> interception point, this 

     *       will only be <code>SUCCESSFUL</code>.</li>

     *   <li>Within the <code>send_exception</code> interception point, 

     *       this will be either <code>SYSTEM_EXCEPTION</code> or 

     *       <code>USER_EXCEPTION</code>.</li>

     *   <li>Within the <code>send_other</code> interception point, this 

     *       attribute will be any of: <code>SUCCESSFUL</code>, or 

     *       <code>LOCATION_FORWARD</code>. <code>SUCCESSFUL</code> means 

     *       an asynchronous request returned successfully. 

     *       <code>LOCATION_FORWARD</code> means that a reply came back 

     *       with <code>LOCATION_FORWARD</code> as its status.</li>

     * </ul>

     * 

     * @see SUCCESSFUL

     * @see SYSTEM_EXCEPTION

     * @see USER_EXCEPTION

     * @see LOCATION_FORWARD

     * @see TRANSPORT_RETRY

     */

    readonly attribute ReplyStatus reply_status;

    /** 

     * Contains the object to which the request will be forwarded, if the 

     * <code>reply_status</code> attribute is <code>LOCATION_FORWARD</code>.

     * It is indeterminate whether a forwarded request will actually occur.

     */

    readonly attribute Object forward_reference;

    /**

     * Returns the data from the given slot of the 

     * <code>PortableInterceptor.Current</code> that is in the scope of