Interceptors.idl revision 662:753f4114e6d6
1169689Skan/* 2169689Skan * Copyright (c) 2000, 2015, Oracle and/or its affiliates. All rights reserved. 3169689Skan * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4169689Skan * 5169689Skan * This code is free software; you can redistribute it and/or modify it 6169689Skan * under the terms of the GNU General Public License version 2 only, as 7169689Skan * published by the Free Software Foundation. Oracle designates this 8169689Skan * particular file as subject to the "Classpath" exception as provided 9169689Skan * by Oracle in the LICENSE file that accompanied this code. 10169689Skan * 11169689Skan * This code is distributed in the hope that it will be useful, but WITHOUT 12169689Skan * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13169689Skan * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14169689Skan * version 2 for more details (a copy is included in the LICENSE file that 15169689Skan * accompanied this code). 16169689Skan * 17169689Skan * You should have received a copy of the GNU General Public License version 18169689Skan * 2 along with this work; if not, write to the Free Software Foundation, 19169689Skan * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20169689Skan * 21169689Skan * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22169689Skan * or visit www.oracle.com if you need additional information or have any 23169689Skan * questions. 24169689Skan */ 25169689Skan 26169689Skan/* 27169689Skan * Differences from original: 28169689Skan * 29169689Skan * - do not include orb.idl 30169689Skan * - include IOP.idl, Messaging.idl and CORBAX.idl 31169689Skan * - renamed component parameter names to tagged_component (so that they 32169689Skan * do not conflict with the CORBA 3.0 "component" keyword). 33169689Skan * - javadocs added (synchronized with orbos/00-08-06) 34169689Skan * 35169689Skan * NOTE: After compilation of this IDL file, all Helper and Holder classes 36169689Skan * that are not needed are removed. 37169689Skan */ 38169689Skan#include "IOP.idl" 39169689Skan#include "Messaging.idl" 40169689Skan#include "CORBAX.idl" 41169689Skan#include "corba.idl" 42169689Skan 43169689Skan#pragma prefix "omg.org" 44169689Skan 45169689Skan#ifndef CORBA3 46169689Skan#define local 47169689Skan#endif 48169689Skan 49169689Skanmodule Dynamic { 50169689Skan 51169689Skan /** 52169689Skan * <code>NVList</code> PIDL represented by <code>ParameterList</code> IDL. 53169689Skan * This exists in order to keep the Portable Interceptor IDL from becoming 54169689Skan * PIDL. 55169689Skan */ 56169689Skan struct Parameter { 57169689Skan any argument; 58169689Skan CORBA::ParameterMode mode; 59169689Skan }; 60169689Skan 61169689Skan /** 62169689Skan * <code>NVList</code> PIDL represented by <code>ParameterList</code> IDL. 63169689Skan * This exists in order to keep the Portable Interceptor IDL from becoming 64169689Skan * PIDL. 65169689Skan */ 66169689Skan typedef sequence<Parameter> ParameterList; 67169689Skan 68169689Skan /** 69169689Skan * <code>ContextList</code> PIDL represented by <code>ContextList</code> 70169689Skan * IDL. This exists in order to keep the Portable Interceptor IDL from 71169689Skan * becoming PIDL. 72169689Skan */ 73169689Skan typedef CORBA::StringSeq ContextList; 74169689Skan 75169689Skan /** 76169689Skan * <code>ExceptionList</code> PIDL represented by <code>ExceptionList</code> 77169689Skan * IDL. This exists in order to keep the Portable Interceptor IDL from 78169689Skan * becoming PIDL. 79169689Skan */ 80169689Skan typedef sequence<CORBA::TypeCode> ExceptionList; 81169689Skan 82169689Skan /** 83169689Skan * <code>Context</code> PIDL represented by <code>RequestContext</code> 84169689Skan * IDL. This exists in order to keep the Portable Interceptor IDL from o 85169689Skan * becoming PIDL. 86169689Skan * <p> 87169689Skan * <code>Context</code> objects are encoded as <code>String[]</code>. The 88169689Skan * <code>Strings</code> occur in pairs. The first <code>String</code> in 89169689Skan * each pair is the context property name and the second <code>String</code> 90169689Skan * in each pair is the associated value. 91169689Skan */ 92169689Skan typedef CORBA::StringSeq RequestContext; 93169689Skan}; 94169689Skan 95169689Skanmodule PortableInterceptor { 96169689Skan /** 97169689Skan * All Portable Interceptors implement Interceptor. 98169689Skan */ 99169689Skan local interface Interceptor { 100169689Skan /** 101169689Skan * Returns the name of the interceptor. 102169689Skan * <p> 103169689Skan * Each Interceptor may have a name that may be used administratively 104169689Skan * to order the lists of Interceptors. Only one Interceptor of a given 105169689Skan * name can be registered with the ORB for each Interceptor type. An 106169689Skan * Interceptor may be anonymous, i.e., have an empty string as the name 107169689Skan * attribute. Any number of anonymous Interceptors may be registered with 108169689Skan * the ORB. 109169689Skan * 110169689Skan * @return the name of the interceptor. 111169689Skan */ 112169689Skan readonly attribute string name; 113169689Skan 114169689Skan // Added in ptc/00-08-06 115169689Skan /** 116169689Skan * Provides an opportunity to destroy this interceptor. 117169689Skan * The destroy method is called during <code>ORB.destroy</code>. When an 118169689Skan * application calls <code>ORB.destroy</code>, the ORB: 119169689Skan * <ol> 120169689Skan * <li>waits for all requests in progress to complete</li> 121169689Skan * <li>calls the <code>Interceptor.destroy</code> operation for each 122169689Skan * interceptor</li> 123169689Skan * <li>completes destruction of the ORB</li> 124169689Skan * </ol> 125169689Skan * Method invocations from within <code>Interceptor.destroy</code> on 126169689Skan * object references for objects implemented on the ORB being destroyed 127169689Skan * result in undefined behavior. However, method invocations on objects 128169689Skan * implemented on an ORB other than the one being destroyed are 129169689Skan * permitted. (This means that the ORB being destroyed is still capable 130169689Skan * of acting as a client, but not as a server.) 131169689Skan */ 132169689Skan void destroy(); 133169689Skan }; 134169689Skan 135169689Skan 136169689Skan /** 137169689Skan * The <code>ForwardRequest</code> exception is the means by which an 138169689Skan * Interceptor can indicate to the ORB that a retry of the request should 139169689Skan * occur with the new object given in the exception. This behavior of 140169689Skan * causing a retry only occurs if the ORB receives a ForwardRequest from 141169689Skan * an interceptor. If <code>ForwardRequest</code> is thrown anywhere else 142169689Skan * it is passed through the ORB as is normal for a user exception. 143169689Skan * <p> 144169689Skan * If an Interceptor throws a <code>ForwardRequest</code> exception in 145169689Skan * response to a call of an interceptor, no other Interceptors are called 146169689Skan * for that interception point. The remaining Interceptors in the Flow Stack 147169689Skan * shall have their appropriate ending interception point called: 148169689Skan * <code>receive_other</code> on the client, or <code>send_other</code> on 149169689Skan * the server. The <code>reply_status</code> in the 150169689Skan * <code>receive_other</code> or <code>send_other</code> would be 151169689Skan * <code>LOCATION_FORWARD</code>. 152169689Skan */ 153169689Skan exception ForwardRequest { 154169689Skan /** 155169689Skan * The new object to forward the request to. 156169689Skan */ 157169689Skan Object forward; 158169689Skan// Change in ptc/00-08-06 159169689Skan// boolean permanent; 160169689Skan }; 161169689Skan 162169689Skan /** Reply status, represented as an int */ 163169689Skan typedef short ReplyStatus; 164169689Skan 165169689Skan // Valid reply_status values: 166169689Skan 167169689Skan /** 168169689Skan * Indicates a successful Reply Status. One possible value for 169169689Skan * <code>RequestInfo.reply_status</code>. 170169689Skan * @see RequestInfo#reply_status 171169689Skan * @see SYSTEM_EXCEPTION 172169689Skan * @see USER_EXCEPTION 173169689Skan * @see LOCATION_FORWARD 174169689Skan * @see TRANSPORT_RETRY 175169689Skan */ 176169689Skan const ReplyStatus SUCCESSFUL = 0; 177169689Skan 178169689Skan /** 179169689Skan * Indicates a SystemException reply status. One possible value for 180169689Skan * <code>RequestInfo.reply_status</code>. 181169689Skan * @see RequestInfo#reply_status 182169689Skan * @see SUCCESSFUL 183169689Skan * @see USER_EXCEPTION 184169689Skan * @see LOCATION_FORWARD 185169689Skan * @see TRANSPORT_RETRY 186169689Skan */ 187169689Skan const ReplyStatus SYSTEM_EXCEPTION = 1; 188169689Skan 189169689Skan /** 190169689Skan * Indicates a UserException reply status. One possible value for 191169689Skan * <code>RequestInfo.reply_status</code>. 192169689Skan * @see RequestInfo#reply_status 193169689Skan * @see SUCCESSFUL 194169689Skan * @see SYSTEM_EXCEPTION 195 * @see LOCATION_FORWARD 196 * @see TRANSPORT_RETRY 197 */ 198 const ReplyStatus USER_EXCEPTION = 2; 199 200 /** 201 * Indicates a LocationForward reply status. One possible value for 202 * <code>RequestInfo.reply_status</code>. 203 * @see RequestInfo#reply_status 204 * @see SUCCESSFUL 205 * @see SYSTEM_EXCEPTION 206 * @see USER_EXCEPTION 207 * @see TRANSPORT_RETRY 208 */ 209 const ReplyStatus LOCATION_FORWARD = 3; 210 211// Changes in ptc/00-08-06 212// const ReplyStatus LOCATION_FORWARD_PERMANENT = 4; 213 214 /** 215 * Indicates a Transport Retry reply status. One possible value for 216 * <code>RequestInfo.reply_status</code>. 217 * @see RequestInfo#reply_status 218 * @see SUCCESSFUL 219 * @see SYSTEM_EXCEPTION 220 * @see USER_EXCEPTION 221 * @see LOCATION_FORWARD 222 */ 223 const ReplyStatus TRANSPORT_RETRY = 4; 224 225 /** 226 * XXX 227 */ 228 const ReplyStatus UNKNOWN = 5; 229 230 /** Slot id, represented as an int */ 231 typedef unsigned long SlotId; 232 233 /** 234 * This exception is thrown when <code>get_slot</code> or 235 * <code>set_slot</code> is called on a slot that has not been allocated. 236 */ 237 exception InvalidSlot {}; 238 239 /** 240 * Portable Interceptors Current (also known as <code>PICurrent</code>) 241 * is merely a slot table, the slots of which are used by each service to 242 * transfer their context data between their context and the request's or 243 * reply's service context. Each service which wishes to use PICurrent 244 * reserves a slot or slots at initialization time and uses those slots 245 * during the processing of requests and replies. 246 * <p> 247 * Before an invocation is made, PICurrent is obtained via a call to 248 * <code>ORB.resolve_initial_references( "PICurrent" )</code>. From within 249 * the interception points, the data on PICurrent that has moved from the 250 * thread scope to the request scope is available via the 251 * <code>get_slot</code> operation on the <code>RequestInfo</code> object. 252 * A PICurrent can still be obtained via 253 * <code>resolve_initial_references</code>, but that is the Interceptor's 254 * thread scope PICurrent. 255 */ 256 local interface Current : CORBA::Current { 257 258 /** 259 * Retrieves the slot data the application set in PICurrent via 260 * <code>get_slot</code>. The data is in the form of an Any. 261 * <p> 262 * If the given slot has not been set, an Any containing a type code 263 * with a <code>TCKind</code> value of <code>tk_null</code> and no value 264 * is returned. 265 * 266 * @param id The <code>SlotId</code> of the slot from which the data will 267 * be returned. 268 * @return The data, in the form of an Any, of the given slot identifier. 269 * @exception InvalidSlot thrown if get_slot is called on a slot that 270 * has not been allocated. 271 * @exception BAD_INV_ORDER thrown if <code>get_slot</code> is called 272 * from within an ORB initializer 273 */ 274 any get_slot (in SlotId id) raises (InvalidSlot); 275 276 /** 277 * Sets data in a slot. The data is in the form of an Any. If data 278 * already exists in that slot, it is overridden. 279 * 280 * @param id The <code>SlotId</code> of the slot to which the data will 281 * be set. 282 * @param data The data, in the form of an Any, which will be set 283 * to the identified slot. 284 * @exception InvalidSlot thrown if <code>set_slot</code> is called on 285 * a slot that has not been allocated. 286 * @exception BAD_INV_ORDER thrown if <code>set_slot</code> is called 287 * from within an ORB initializer. 288 */ 289 void set_slot (in SlotId id, in any data) raises (InvalidSlot); 290 }; 291 292 /** 293 * Request Information, accessible to Interceptors. 294 * <p> 295 * Each interception point is given an object through which the 296 * Interceptor can access request information. Client-side and server-side 297 * interception points are concerned with different information, so there 298 * are two information objects: <code>ClientRequestInfo</code> is passed 299 * to the client-side interception points and <code>ServerRequestInfo</code> 300 * is passed to the server-side interception points. But there is 301 * information that is common to both, so they both inherit from a common 302 * interface: <code>RequestInfo</code>. 303 * 304 * @see ClientRequestInfo 305 * @see ServerRequestInfo 306 */ 307 local interface RequestInfo { 308 /** 309 * Returns an id that uniquely identifies an active request/reply 310 * sequence. Once a request/reply sequence is concluded this ID may be 311 * reused. Note that this id is not the same as the GIOP 312 * <code>request_id</code>. If GIOP is the transport mechanism used, 313 * then these IDs may very well be the same, but this is not guaranteed 314 * nor required. 315 */ 316 readonly attribute unsigned long request_id; 317 318 /** 319 * Returns the name of the operation being invoked. 320 */ 321 readonly attribute string operation; 322 323 /** 324 * Returns an array of <code>Parameter</code> objects, containing the 325 * arguments on the operation being invoked. If there are no arguments, 326 * this attribute will be a zero length array. 327 * <p> 328 * Not all environments provide access to the arguments. With the Java 329 * portable bindings, for example, the arguments are not available. 330 * In these environments, when this attribute is accessed, 331 * <code>NO_RESOURCES</code> will be thrown with a standard minor code 332 * of 1. 333 * <p> 334 * <i>Note: Arguments are available for DSI/DII calls.</i> 335 * 336 * @exception NO_RESOURCES thrown if arguments are not available. 337 * @see <a href="package-summary.html#unimpl"> 338 * <code>PortableInterceptor</code> package comments for 339 * limitations / unimplemented features</a> 340 */ 341 readonly attribute Dynamic::ParameterList arguments; 342 343 /** 344 * Returns an array of <code>TypeCode</code> objects describing the 345 * <code>TypeCode</code>s of the user exceptions that this operation 346 * invocation may throw. If there are no user exceptions, this 347 * will return a zero length array. 348 * <p> 349 * Not all environments provide access to the exception list. With 350 * the Java portable bindings, for example, the exception list is 351 * not available. In these environments, when this attribute is 352 * accessed, <code>NO_RESOURCES</code> will be thrown with a 353 * standard minor code of 1. 354 * <p> 355 * <i>Note: Exceptions are available for DSI/DII calls.</i> 356 * 357 * @exception NO_RESOURCES thrown if exceptions are not available. 358 * @see <a href="package-summary.html#unimpl"> 359 * <code>PortableInterceptor</code> package comments for 360 * limitations / unimplemented features</a> 361 */ 362 readonly attribute Dynamic::ExceptionList exceptions; 363 364 /** 365 * Returns an array of <code>String</code> objects describing the 366 * contexts that may be passed on this operation invocation. If there 367 * are no contexts, this will return a zero length array. 368 * <p> 369 * Not all environments provide access to the context list. With the 370 * Java portable bindings, for example, the context list is not 371 * available. In these environments, when this attribute is accessed, 372 * <code>NO_RESOURCES</code> will be thrown with a standard minor code 373 * of 1. 374 * <p> 375 * <i>Note: Contexts are available for DSI/DII calls.</i> 376 * 377 * @exception NO_RESOURCES thrown if contexts are not available. 378 * @see <a href="package-summary.html#unimpl"> 379 * <code>PortableInterceptor</code> package comments for 380 * limitations / unimplemented features</a> 381 */ 382 readonly attribute Dynamic::ContextList contexts; 383 384 /** 385 * Returns an array of <code>String</code> objects containing the 386 * contexts being sent on the request. 387 * <p> 388 * Not all environments provide access to the context. With the Java 389 * portable bindings, for example, the context is not available. In 390 * these environments, when this attribute is accessed, NO_RESOURCES will 391 * be thrown with standard minor code of 1. 392 * <p> 393 * <i>Note: <code>operation_context</code> is available for 394 * DSI/DII calls.</i> 395 * 396 * @exception NO_RESOURCES thrown if operation context is not available. 397 * @see <a href="package-summary.html#unimpl"> 398 * <code>PortableInterceptor</code> package comments for 399 * limitations / unimplemented features</a> 400 */ 401 readonly attribute Dynamic::RequestContext operation_context; 402 403 /** 404 * Returns an any containing the result of the operation invocation. 405 * If the operation return type is void, this attribute will be an any 406 * containing a type code with a <code>TCKind</code> value of 407 * <code>tk_void</code> and no value. 408 * <p> 409 * Not all environments provide access to the result. With the Java 410 * portable bindings, for example, the result is not available. In 411 * these environments, when this attribute is accessed, 412 * <code>NO_RESOURCES</code> will be thrown with a standard minor code of 413 * 1. 414 * <p> 415 * <i>Note: Result is available for DSI/DII calls.</i> 416 * 417 * @exception NO_RESOURCES thrown if result is not available. 418 * @see <a href="package-summary.html#unimpl"> 419 * <code>PortableInterceptor</code> package comments for 420 * limitations / unimplemented features</a> 421 */ 422 readonly attribute any result; 423 424 /** 425 * Indicates whether a response is expected. 426 * <p> 427 * On the client, a reply is not returned when 428 * <code>response_expected</code> is false, so <code>receive_reply</code> 429 * cannot be called. <code>receive_other</code> is called unless an 430 * exception occurs, in which case <code>receive_exception</code> is 431 * called. 432 * <p> 433 * On the client, within <code>send_poll</code>, this attribute is true. 434 */ 435 readonly attribute boolean response_expected; 436 437 /** 438 * Defines how far the request shall progress before control is returned 439 * to the client. This is defined in the Messaging specification, and 440 * is pertinent only when <code>response_expected</code> is false. If 441 * <code>response_expected</code> is true, the value of 442 * <code>sync_scope</code> is undefined. This attribute may have one of 443 * the following values: 444 * <ul> 445 * <li><code>Messaging.SYNC_NONE</code></li> 446 * <li><code>Messaging.SYNC_WITH_TRANSPORT</code></li> 447 * <li><code>Messaging.SYNC_WITH_SERVER</code></li> 448 * <li><code>Messaging.SYNC_WITH_TARGET</code></li> 449 * </ul> 450 * On the server, for all scopes, a reply will be created from the 451 * return of the target operation call, but the reply will not return 452 * to the client. Although it does not return to the client, it does 453 * occur, so the normal server-side interception points are 454 * followed (i.e., <code>receive_request_service_contexts</code>, 455 * <code>receive_request</code>, <code>send_reply</code> or 456 * <code>send_exception</code>). 457 * <p> 458 * For <code>SYNC_WITH_SERVER</code> and <code>SYNC_WITH_TARGET</code>, 459 * the server does send an empty reply back to the client before the 460 * target is invoked. This reply is not intercepted by server-side 461 * Interceptors. 462 * 463 * @see <a href="package-summary.html#unimpl"> 464 * <code>PortableInterceptor</code> package comments for 465 * limitations / unimplemented features</a> 466 */ 467 readonly attribute Messaging::SyncScope sync_scope; 468 469 /** 470 * Describes the state of the result of the operation invocation. The 471 * return value can be one of the following: 472 * <ul> 473 * <li><code>PortableInterceptor.SUCCESSFUL</code></li> 474 * <li><code>PortableInterceptor.SYSTEM_EXCEPTION</code></li> 475 * <li><code>PortableInterceptor.USER_EXCEPTION</code></li> 476 * <li><code>PortableInterceptor.LOCATION_FORWARD</code></li> 477 * <li><code>PortableInterceptor.TRANSPORT_RETRY</code></li> 478 * </ul> 479 * On the client: 480 * <ul> 481 * <li>Within the <code>receive_reply</code> interception point, this 482 * will only return <code>SUCCESSFUL</code>.</li> 483 * <li>Within the <code>receive_exception</code> interception point, 484 * this will be either <code>SYSTEM_EXCEPTION</code> or 485 * <code>USER_EXCEPTION</code>.</li> 486 * <li>Within the <code>receive_other</code> interception point, this 487 * will be any of: <code>SUCCESSFUL</code>, 488 * <code>LOCATION_FORWARD</code>, or <code>TRANSPORT_RETRY</code>. 489 * <code>SUCCESSFUL</code> means an asynchronous request returned 490 * successfully. <code>LOCATION_FORWARD</code> means that a reply 491 * came back with <code>LOCATION_FORWARD</code> as its status. 492 * <code>TRANSPORT_RETRY</code> means that the transport 493 * mechanism indicated a retry - a GIOP reply with a status of 494 * <code>NEEDS_ADDRESSING_MODE</code>, for instance. </li> 495 * </ul> 496 * On the server: 497 * <ul> 498 * <li>Within the <code>send_reply</code> interception point, this 499 * will only be <code>SUCCESSFUL</code>.</li> 500 * <li>Within the <code>send_exception</code> interception point, 501 * this will be either <code>SYSTEM_EXCEPTION</code> or 502 * <code>USER_EXCEPTION</code>.</li> 503 * <li>Within the <code>send_other</code> interception point, this 504 * attribute will be any of: <code>SUCCESSFUL</code>, or 505 * <code>LOCATION_FORWARD</code>. <code>SUCCESSFUL</code> means 506 * an asynchronous request returned successfully. 507 * <code>LOCATION_FORWARD</code> means that a reply came back 508 * with <code>LOCATION_FORWARD</code> as its status.</li> 509 * </ul> 510 * 511 * @see SUCCESSFUL 512 * @see SYSTEM_EXCEPTION 513 * @see USER_EXCEPTION 514 * @see LOCATION_FORWARD 515 * @see TRANSPORT_RETRY 516 */ 517 readonly attribute ReplyStatus reply_status; 518 519 /** 520 * Contains the object to which the request will be forwarded, if the 521 * <code>reply_status</code> attribute is <code>LOCATION_FORWARD</code>. 522 * It is indeterminate whether a forwarded request will actually occur. 523 */ 524 readonly attribute Object forward_reference; 525 526 /** 527 * Returns the data from the given slot of the 528 * <code>PortableInterceptor.Current</code> that is in the scope of 529 * the request. 530 * <p> 531 * If the given slot has not been set, then an any containing a 532 * type code with a <code>TCKind</code> value of <code>tk_null</code> is 533 * returned. 534 * 535 * @param id The <code>SlotId</code> of the slot which is to be 536 * returned. 537 * @return The slot data, in the form of an any, obtained with the 538 * given identifier. 539 * @exception InvalidSlot thrown if the ID does not define an 540 * allocated slot. 541 * @see Current 542 */ 543 any get_slot (in SlotId id) raises (InvalidSlot); 544 545 /** 546 * Returns a copy of the service context with the given ID that 547 * is associated with the request. 548 * 549 * @param id The <code>IOP.ServiceId</code> of the service context 550 * which is to be returned. 551 * @return The <code>IOP.ServiceContext</code> obtained with the 552 * given identifier. 553 * @exception BAD_PARAM thrown with a standard minor code of 26, if the 554 * request's service context does not contain an entry for that ID. 555 */ 556 IOP::ServiceContext get_request_service_context 557 (in IOP::ServiceId id); 558 559 /** 560 * Returns a copy of the service context with the given ID that 561 * is associated with the reply. 562 * 563 * @param id The <code>IOP.ServiceId</code> of the service context 564 * which is to be returned. 565 * @return The <code>IOP.ServiceContext</code> obtained with the given 566 * identifier. 567 * @exception BAD_PARAM thrown with a standard minor code of 26 if the 568 * request's service context does not contain an entry for that ID. 569 */ 570 IOP::ServiceContext get_reply_service_context 571 (in IOP::ServiceId id); 572 }; 573 574 /** 575 * Request Information, accessible to client-side request interceptors. 576 * <p> 577 * Some attributes and operations on <code>ClientRequestInfo</code> are 578 * not valid at all interception points. The following table shows the 579 * validity of each attribute or operation. If it is not valid, attempting 580 * to access it will result in a <code>BAD_INV_ORDER</code> being thrown 581 * with a standard minor code of 14. 582 * 583 * <table border=1 summary="Shows the validity of each attribute or operation"> 584 * <thead> 585 * <tr> 586 * <th> </th> 587 * <th id="send_req">send_request</th> 588 * <th id="send_poll">send_poll</th> 589 * <th id="rec_reply">receive_reply</th> 590 * <th id="rec_ex">receive_exception</th> 591 * <th id="rec_oth">receive_other</th> 592 * </tr> 593 * </thead> 594 * <tbody> 595 * 596 * <tr> 597 * <td id="ri" colspan=6><i>Inherited from RequestInfo:</i></td> 598 * </tr> 599 * 600 * <tr><th id="req_id"><p align="left">request_id</p></th> 601 * <td headers="ri req_id send_req">yes</td> 602 * <td headers="ri req_id send_poll">yes</td> 603 * <td headers="ri req_id rec_reply">yes</td> 604 * <td headers="ri req_id rec_ex">yes</td> 605 * <td headers="ri req_id rec_oth">yes</td></tr> 606 * 607 * <tr><th id="op"><p align="left">operation</p></th> 608 * <td headers="ri op send_req">yes</td> 609 * <td headers="ri op send_poll">yes</td> 610 * <td headers="ri op rec_reply">yes</td> 611 * <td headers="ri op rec_ex">yes</td> 612 * <td headers="ri op rec_oth">yes</td></tr> 613 * 614 * <tr><th id="arg"><p align="left">arguments</p></th> 615 * <td headers="ri arg send_req">yes<sub>1</sub></td> 616 * <td headers="ri arg send_poll">no </td> 617 * <td headers="ri arg rec_reply">yes</td> 618 * <td headers="ri arg rec_ex">no </td> 619 * <td headers="ri arg rec_oth">no </td></tr> 620 * 621 * <tr><th id="exc"><p align="left">exceptions</p></th> 622 * <td headers="ri exc send_req">yes</td> 623 * <td headers="ri exc send_poll">no </td> 624 * <td headers="ri exc rec_reply">yes</td> 625 * <td headers="ri exc rec_ex">yes</td> 626 * <td headers="ri exc rec_oth">yes</td></tr> 627 * 628 * <tr><th id="con"><p align="left">contexts</p></th> 629 * <td headers="ri con send_req">yes</td> 630 * <td headers="ri con send_poll">no </td> 631 * <td headers="ri con rec_reply">yes</td> 632 * <td headers="ri con rec_ex">yes</td> 633 * <td headers="ri con rec_oth">yes</td></tr> 634 * 635 * <tr><th id="op_con"><p align="left">operation_context</p></th> 636 * <td headers="ri op_con send_req">yes</td> 637 * <td headers="ri op_con send_poll">no </td> 638 * <td headers="ri op_con rec_reply">yes</td> 639 * <td headers="ri op_con rec_ex">yes</td> 640 * <td headers="ri op_con rec_oth">yes</td> 641 * </tr> 642 * 643 * <tr><th id="result"><p align="left">result</p></th> 644 * <td headers="ri result send_req">no </td> 645 * <td headers="ri result send_poll">no </td> 646 * <td headers="ri result rec_reply">yes</td> 647 * <td headers="ri result rec_ex">no </td> 648 * <td headers="ri result rec_oth">no </td> 649 * </tr> 650 * 651 * <tr><th id="res_exp"><p align="left">response_expected</p></th> 652 * <td headers="ri res_exp send_req">yes</td> 653 * <td headers="ri res_exp send_poll">yes</td> 654 * <td headers="ri res_exp rec_reply">yes</td> 655 * <td headers="ri res_exp rec_ex">yes</td> 656 * <td headers="ri res_exp rec_oth">yes</td></tr> 657 * 658 * <tr><th id="sync_sco"><p align="left">sync_scope</p></th> 659 * <td headers="ri sync_sco send_req">yes</td> 660 * <td headers="ri sync_sco send_poll">no </td> 661 * <td headers="ri sync_sco rec_reply">yes</td> 662 * <td headers="ri sync_sco rec_ex">yes</td> 663 * <td headers="ri sync_sco rec_oth">yes</td> 664 * </tr> 665 * 666 * <tr><th id="rep_stat"><p align="left">reply_status</p></th> 667 * <td headers="ri rep_stat send_req">no </td> 668 * <td headers="ri rep_stat send_poll">no </td> 669 * <td headers="ri rep_stat rec_reply">yes</td> 670 * <td headers="ri rep_stat rec_ex">yes</td> 671 * <td headers="ri rep_stat rec_oth">yes</td></tr> 672 * 673 * <tr><th id="for_ref"><p align="left">forward_reference</p></th> 674 * <td headers="ri for_ref send_req">no </td> 675 * <td headers="ri for_ref send_poll">no </td> 676 * <td headers="ri for_ref rec_reply">no </td> 677 * <td headers="ri for_ref rec_ex">no </td> 678 * <td headers="ri for_ref rec_oth">yes<sub>2</sub> 679 * </td></tr> 680 * 681 * <tr><th id="get_slot"><p align="left">get_slot</p></th> 682 * <td headers="ri get_slot send_req">yes</td> 683 * <td headers="ri get_slot send_poll">yes</td> 684 * <td headers="ri get_slot rec_reply">yes</td> 685 * <td headers="ri get_slot rec_ex">yes</td> 686 * <td headers="ri get_slot rec_oth">yes</td></tr> 687 * 688 * <tr><th id="grsc"><p align="left">get_request_service_context</p></th> 689 * <td headers="ri grsc send_req">yes</td> 690 * <td headers="ri grsc send_poll">no </td> 691 * <td headers="ri grsc rec_reply">yes</td> 692 * <td headers="ri grsc rec_ex">yes</td> 693 * <td headers="ri grsc rec_oth">yes</td></tr> 694 * 695 * <tr><th id="gpsc"><p align="left">get_reply_service_context</p></th> 696 * <td headers="ri gpsc send_req">no </td> 697 * <td headers="ri gpsc send_poll">no </td> 698 * <td headers="ri gpsc rec_reply">yes</td> 699 * <td headers="ri gpsc rec_ex">yes</td> 700 * <td headers="ri gpsc rec_oth">yes</td> 701 * </tr> 702 * 703 * <tr> 704 * <td id="cri" colspan=6><i>ClientRequestInfo-specific:</i></td> 705 * </tr> 706 * 707 * <tr><th id="target"><p align="left">target</p></th> 708 * <td headers="cri target send_req">yes</td> 709 * <td headers="cri target send_poll">yes</td> 710 * <td headers="cri target rec_reply">yes</td> 711 * <td headers="cri target rec_ex">yes</td> 712 * <td headers="cri target rec_oth">yes</td></tr> 713 * 714 * <tr><th id="eftarget"><p align="left">effective_target</p></th> 715 * <td headers="cri eftarget send_req">yes</td> 716 * <td headers="cri eftarget send_poll">yes</td> 717 * <td headers="cri eftarget rec_reply">yes</td> 718 * <td headers="cri eftarget rec_ex">yes</td> 719 * <td headers="cri eftarget rec_oth">yes</td> 720 * </tr> 721 * 722 * <tr><th id="efprof"><p align="left">effective_profile</p></th> 723 * <td headers="cri efprof send_req">yes</td> 724 * <td headers="cri efprof send_poll">yes</td> 725 * <td headers="cri efprof rec_reply">yes</td> 726 * <td headers="cri efprof rec_ex">yes</td> 727 * <td headers="cri efprof rec_oth">yes</td></tr> 728 * 729 * <tr><th id="rxp"><p align="left">received_exception</p></th> 730 * <td headers="cri rxp send_req">no </td> 731 * <td headers="cri rxp send_poll">no </td> 732 * <td headers="cri rxp rec_reply">no </td> 733 * <td headers="cri rxp rec_ex">yes</td> 734 * <td headers="cri rxp rec_oth">no </td></tr> 735 * 736 * <tr><th id="rei"><p align="left">received_exception_id</p></th> 737 * <td headers="cri rei send_req">no </td> 738 * <td headers="cri rei send_poll">no </td> 739 * <td headers="cri rei rec_reply">no </td> 740 * <td headers="cri rei rec_ex">yes</td> 741 * <td headers="cri rei rec_oth">no </td></tr> 742 * 743 * <tr><th id="gec"><p align="left">get_effective_component</p></th> 744 * <td headers="cri gec send_req">yes</td> 745 * <td headers="cri gec send_poll">no </td> 746 * <td headers="cri gec rec_reply">yes</td> 747 * <td headers="cri gec rec_ex">yes</td> 748 * <td headers="cri gec rec_oth">yes</td></tr> 749 * 750 * <tr><th id="gecs"><p align="left">get_effective_components</p></th> 751 * <td headers="cri gecs send_req">yes</td> 752 * <td headers="cri gecs send_poll">no </td> 753 * <td headers="cri gecs rec_reply">yes</td> 754 * <td headers="cri gecs rec_ex">yes</td> 755 * <td headers="cri gecs rec_oth">yes</td></tr> 756 * 757 * <tr><th id="grpcy"><p align="left">get_request_policy</p></th> 758 * <td headers="cri grpcy send_req">yes</td> 759 * <td headers="cri grpcy send_poll">no </td> 760 * <td headers="cri grpcy rec_reply">yes</td> 761 * <td headers="cri grpcy rec_ex">yes</td> 762 * <td headers="cri grpcy rec_oth">yes</td></tr> 763 * 764 * <tr><th id="arsc"><p align="left">add_request_service_context</p></th> 765 * <td headers="cri arsc send_req">yes</td> 766 * <td headers="cri arsc send_poll">no </td> 767 * <td headers="cri arsc rec_reply">no </td> 768 * <td headers="cri arsc rec_ex">no </td> 769 * <td headers="cri arsc rec_oth">no </td></tr> 770 * 771 * </tbody> 772 * </table> 773 * 774 * <ol> 775 * <li>When <code>ClientRequestInfo</code> is passed to 776 * <code>send_request</code>, there is an entry in the list for every 777 * argument, whether in, inout, or out. But only the in and inout 778 * arguments will be available.</li> 779 * <li>If the <code>reply_status</code> atribute is not 780 * <code>LOCATION_FORWARD</code>, accessing this attribute will 781 * throw <code>BAD_INV_ORDER</code> with a standard minor code of 782 * 14.</li> 783 * </ol> 784 * 785 * @see ClientRequestInterceptor 786 */ 787 local interface ClientRequestInfo : RequestInfo { 788 789 /** 790 * Returns the object which the client called to perform the 791 * operation. 792 * 793 * @see #effective_target 794 */ 795 readonly attribute Object target; 796 797 /** 798 * Returns the actual object on which the operation will be invoked. 799 * If the <code>reply_status</code> is <code>LOCATION_FORWARD</code>, 800 * then on subsequent requests, <code>effective_target</code> will 801 * contain the forwarded IOR while target will remain unchanged. 802 * 803 * @see #target 804 */ 805 readonly attribute Object effective_target; 806 807 /** 808 * Returns the profile that will be used to send the request. If a 809 * location forward has occurred for this operation's object and 810 * that object's profile changed accordingly, then this profile will 811 * be that located profile. 812 */ 813 readonly attribute IOP::TaggedProfile effective_profile; 814 815 /** 816 * Returns an any which contains the exception to be returned to 817 * the client. 818 * <p> 819 * If the exception is a user exception which cannot be inserted 820 * into an any (e.g., it is unknown or the bindings don t provide 821 * the <code>TypeCode</code>), then this attribute will be an any 822 * containing the system exception <code>UNKNOWN</code> with a 823 * standard minor code of 1. However, the repository id of 824 * the exception is available in the <code>received_exception_id</code> 825 * attribute. 826 * 827 * @see #received_exception_id 828 */ 829 readonly attribute any received_exception; 830 831 /** 832 * Returns the repository id of the exception to be returned to 833 * the client. 834 * 835 * @see #received_exception 836 * @see <a href="package-summary.html#unimpl"> 837 * <code>PortableInterceptor</code> package comments for 838 * limitations / unimplemented features</a> 839 */ 840 readonly attribute CORBA::RepositoryId received_exception_id; 841 842 /** 843 * Returns the <code>IOP.TaggedComponent</code> with the given ID from 844 * the profile selected for this request. 845 * <p> 846 * If there is more than one component for a given component ID, it 847 * is undefined which component this operation returns. If there is 848 * more than one component for a given component ID, 849 * <code>get_effective_components</code> should be called instead. 850 * 851 * @param id The component id of the component which 852 * is to be returned. 853 * @return The <code>IOP.TaggedComponent</code> obtained with the 854 * given identifier. 855 * @exception BAD_PARAM thrown, with a standard minor code of 28, if 856 * no component exists for the given component ID. 857 * @see #get_effective_components 858 */ 859 IOP::TaggedComponent get_effective_component 860 (in IOP::ComponentId id); 861 862 /** 863 * Returns an array of all tagged components with the given ID from the 864 * profile selected for this request. 865 * 866 * @param id The component id of the components which are to be returned. 867 * @return An array of <code>TaggedComponent</code> objects, each of 868 * which contains the given identifier. 869 * @exception BAD_PARAM thrown, with a standard minor code of 28, if 870 * no component exists for the given component ID. 871 * @see #get_effective_component 872 */ 873 IOP::TaggedComponentSeq get_effective_components 874 (in IOP::ComponentId id); 875 876 /** 877 * Returns the given policy in effect for this operation. 878 * 879 * @exception INV_POLICY thrown, with a standard minor code of 1, if the 880 * policy type is not valid either because the specified type is 881 * not supported by this ORB or because a policy object of that type 882 * is not associated with this Object 883 * @param type The policy type which specifies the policy to be 884 * returned. 885 * @return The <code>CORBA.Policy</code> obtained with the given type. 886 * @see <a href="package-summary.html#unimpl"> 887 * <code>PortableInterceptor</code> package comments for 888 * limitations / unimplemented features</a> 889 */ 890 CORBA::Policy get_request_policy 891 (in CORBA::PolicyType type); 892 893 /** 894 * Allows Interceptors to add service contexts to the request. 895 * <p> 896 * There is no declaration of the order of the service contexts. 897 * They may or may not appear in the order that they are added. 898 * 899 * @param service_context The <code>IOP.ServiceContext</code> to be 900 * added to the request. 901 * @param replace Indicates the behavior of this operation when a 902 * service context already exists with the given ID. If false, 903 * then <code>BAD_INV_ORDER</code> with a standard minor code of 15 904 * is thrown. If true, then the existing service context is 905 * replaced by the new one. 906 */ 907 void add_request_service_context ( 908 in IOP::ServiceContext service_context, 909 in boolean replace); 910 }; 911 912 // Should be type string 913 typedef string ServerId ; 914 915 // This should actually be the CORBA::ORBid type once that is available 916 typedef string ORBId ; 917 918 /** The name of an object adapter. This is unique only within 919 * the scope of the ORB that created the object adapter. 920 */ 921 typedef org::omg::CORBA::StringSeq AdapterName ; 922 923 /** Type of an object id. This provides the identity of a particular 924 * object that was created by an object adapter. 925 */ 926 typedef org::omg::CORBA::OctetSeq ObjectId ; 927 928 /** 929 * Request Information, accessible to server-side request interceptors. 930 * <p> 931 * Some attributes and operations on <code>ServerRequestInfo</code> are not 932 * valid at all interception points. The following table shows the validity 933 * of each attribute or operation. If it is not valid, attempting to access 934 * it will result in a <code>BAD_INV_ORDER</code> being thrown with a 935 * standard minor code of 14. 936 * 937 * 938 * <table border=1 summary="Shows the validity of each attribute or operation"> 939 * <thead> 940 * <tr> 941 * <th> </th> 942 * <th id="rec_req_ser_con" valign="bottom">receive_request_<br>service_contexts</th> 943 * <th id="rec_req" valign="bottom">receive_request</th> 944 * <th id="send_rep" valign="bottom">send_reply</th> 945 * <th id="send_exc" valign="bottom">send_exception</th> 946 * <th id="send_oth" valign="bottom">send_other</th> 947 * </tr> 948 * </thead> 949 * <tbody> 950 * 951 * 952 * <tr> 953 * <td id="ri" colspan=6><i>Inherited from RequestInfo:</i></td> 954 * </tr> 955 * 956 * <tr><th id="req_id"><p align="left">request_id</p></th> 957 * <td headers="ri req_id rec_req_ser_con">yes</td> 958 * <td headers="ri req_id rec_req">yes</td> 959 * <td headers="ri req_id send_rep">yes</td> 960 * <td headers="ri req_id send_exc">yes</td> 961 * <td headers="ri req_id send_oth">yes</td></tr> 962 * 963 * <tr><th id="op"><p align="left">operation</p></th> 964 * <td headers="ri op rec_req_ser_con">yes</td> 965 * <td headers="ri op rec_req">yes</td> 966 * <td headers="ri op send_rep">yes</td> 967 * <td headers="ri op send_exc">yes</td> 968 * <td headers="ri op send_oth">yes</td></tr> 969 * 970 * <tr><th id="args"><p align="left">arguments</p></th> 971 * <td headers="ri args rec_req_ser_con">no </td> 972 * <td headers="ri args rec_req">yes<sub>1</sub></td> 973 * <td headers="ri args send_rep">yes</td> 974 * <td headers="ri args send_exc">no<sub>2</sub></td> 975 * <td headers="ri args send_oth">no<sub>2</sub> 976 * </td></tr> 977 * 978 * <tr><th id="exps"><p align="left">exceptions</p></th> 979 * <td headers="ri exps rec_req_ser_con">no </td> 980 * <td headers="ri exps rec_req">yes</td> 981 * <td headers="ri exps send_rep">yes</td> 982 * <td headers="ri exps send_exc">yes</td> 983 * <td headers="ri exps send_oth">yes</td></tr> 984 * 985 * <tr><th id="contexts"><p align="left">contexts</p></th> 986 * <td headers="ri contexts rec_req_ser_con">no </td> 987 * <td headers="ri contexts rec_req">yes</td> 988 * <td headers="ri contexts send_rep">yes</td> 989 * <td headers="ri contexts send_exc">yes</td> 990 * <td headers="ri contexts send_oth">yes</td></tr> 991 * 992 * <tr><th id="op_con"><p align="left">operation_context</p></th> 993 * <td headers="ri op_con rec_req_ser_con">no </td> 994 * <td headers="ri op_con rec_req">yes</td> 995 * <td headers="ri op_con send_rep">yes</td> 996 * <td headers="ri op_con send_exc">no </td> 997 * <td headers="ri op_con send_oth">no </td> 998 * </tr> 999 * 1000 * <tr><th id="result"><p align="left">result</p></th> 1001 * <td headers="ri result rec_req_ser_con">no </td> 1002 * <td headers="ri result rec_req">no </td> 1003 * <td headers="ri result send_rep">yes</td> 1004 * <td headers="ri result send_exc">no </td> 1005 * <td headers="ri result send_oth">no </td> 1006 * </tr> 1007 * 1008 * <tr><th id="res_ex"><p align="left">response_expected</p></th> 1009 * <td headers="ri res_ex rec_req_ser_con">yes</td> 1010 * <td headers="ri res_ex rec_req">yes</td> 1011 * <td headers="ri res_ex send_rep">yes</td> 1012 * <td headers="ri res_ex send_exc">yes</td> 1013 * <td headers="ri res_ex send_oth">yes</td></tr> 1014 * 1015 * <tr><th id="syn_scp"><p align="left">sync_scope</p></th> 1016 * <td headers="ri syn_scp rec_req_ser_con">yes</td> 1017 * <td headers="ri syn_scp rec_req">yes</td> 1018 * <td headers="ri syn_scp send_rep">yes</td> 1019 * <td headers="ri syn_scp send_exc">yes</td> 1020 * <td headers="ri syn_scp send_oth">yes</td></tr> 1021 * 1022 * <tr><td><b>request_id</b></td> 1023 * <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td></tr> 1024 * 1025 * <tr><td><b>operation</b></td> 1026 * <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td></tr> 1027 * 1028 * <tr><td><b>arguments</b></td> 1029 * <td>no </td> <td>yes<sub>1</sub></td> 1030 * <td>yes</td> <td>no<sub>2</sub></td> 1031 * <td>no<sub>2</sub> 1032 * </td></tr> 1033 * 1034 * <tr><td><b>exceptions</b></td> 1035 * <td>no </td> <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td></tr> 1036 * 1037 * <tr><td><b>contexts</b></td> 1038 * <td>no </td> <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td></tr> 1039 * 1040 * <tr><td><b>operation_context</b></td> 1041 * <td>no </td> <td>yes</td> <td>yes</td> <td>no </td> <td>no </td></tr> 1042 * 1043 * <tr><td><b>result</b></td> 1044 * <td>no </td> <td>no </td> <td>yes</td> <td>no </td> <td>no </td></tr> 1045 * 1046 * <tr><td><b>response_expected</b></td> 1047 * <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td></tr> 1048 * 1049 * <tr><td><b>sync_scope</b></td> 1050 * <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td></tr> 1051 * 1052 * <tr><td><b>reply_status</b></td> 1053 * <td>no </td> <td>no </td> <td>yes</td> <td>yes</td> <td>yes</td></tr> 1054 * 1055 * <tr><td><b>forward_reference</b></td> 1056 * <td>no </td> <td>no </td> <td>no </td> <td>no </td> <td>yes<sub>2</sub> 1057 * </td></tr> 1058 * 1059 * <tr><td><b>get_slot</b></td> 1060 * <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td></tr> 1061 * 1062 * <tr><td><b>get_request_service_context</b></td> 1063 * <td>yes</td> <td>no </td> <td>yes</td> <td>yes</td> <td>yes</td></tr> 1064 * 1065 * <tr><td><b>get_reply_service_context</b></td> 1066 * <td>no </td> <td>no </td> <td>yes</td> <td>yes</td> <td>yes</td></tr> 1067 * 1068 * <tr> 1069 * <td colspan=6><i>ServerRequestInfo-specific:</i></td> 1070 * </tr> 1071 * 1072 * <tr><td><b>sending_exception</b></td> 1073 * <td>no </td> <td>no </td> <td>no </td> <td>yes</td> <td>no </td></tr> 1074 * 1075 * <tr><td><b>object_id</b></td> 1076 * <td>no </td> <td>yes</td> <td>yes</td> <td>yes<sub>3</sub></td> 1077 * <td>yes<sub>3</sub> 1078 * </td></tr> 1079 * 1080 * <tr><td><b>adapter_id</b></td> 1081 * <td>no </td> <td>yes</td> <td>yes</td> <td>yes<sub>3</sub></td> 1082 * <td>yes<sub>3</sub> 1083 * </td></tr> 1084 * 1085 * <tr><td><b>server_id</b></td> 1086 * <td>no </td> <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td></tr> 1087 * 1088 * <tr><td><b>orb_id</b></td> 1089 * <td>no </td> <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td></tr> 1090 * 1091 * <tr><td><b>adapter_name</b></td> 1092 * <td>no </td> <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td></tr> 1093 * 1094 * <tr><td><b>target_most_derived_interface</b></td> 1095 * <td>no </td> <td>yes</td> <td>no<sub>4</sub></td> 1096 * <td>no<sub>4</sub></td> 1097 * <td>no<sub>4</sub> 1098 * </td></tr> 1099 * 1100 * <tr><td><b>get_server_policy</b></td> 1101 * <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td></tr> 1102 * 1103 * <tr><td><b>set_slot</b></td> 1104 * <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td></tr> 1105 * 1106 * <tr><td><b>target_is_a</b></td> 1107 * <td>no </td> <td>yes</td> <td>no<sub>4</sub></td> 1108 * <td>no<sub>4</sub></td> 1109 * <td>no<sub>4</sub> 1110 * </td></tr> 1111 * 1112 * <tr><td><b>add_reply_service_context</b></td> 1113 * <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td></tr> 1114 * </tbody> 1115 * </table> 1116 * 1117 * <ol> 1118 * <li>When <code>ServerRequestInfo</code> is passed to 1119 * <code>receive_request</code>, there is an entry in the list for 1120 * every argument, whether in, inout, or out. But only the in and 1121 * inout arguments will be available.</li> 1122 * <li>If the <code>reply_status</code> attribute is not 1123 * <code>LOCATION_FORWARD</code>, accessing this attribute will throw 1124 * <code>BAD_INV_ORDER</code> with a standard minor code of 14.</li> 1125 * <li>If the servant locator caused a location forward, or thrown an 1126 * exception, this attribute/operation may not be available in this 1127 * interception point. <code>NO_RESOURCES</code> with a standard minor 1128 * code of 1 will be thrown if it is not available.</li> 1129 * <li>The operation is not available in this interception point because 1130 * the necessary information requires access to the target object's 1131 * servant, which may no longer be available to the ORB. For example, 1132 * if the object's adapter is a POA that uses a 1133 * <code>ServantLocator</code>, then the ORB invokes the interception 1134 * point after it calls <code>ServantLocator.postinvoke()</code>.</li> 1135 * </ol> 1136 * 1137 * @see ServerRequestInterceptor 1138 */ 1139 local interface ServerRequestInfo : RequestInfo { 1140 1141 /** 1142 * Returns an any which contains the exception to be returned to 1143 * the client. 1144 * <p> 1145 * If the exception is a user exception which cannot be inserted into 1146 * an any (e.g., it is unknown or the bindings don't provide the 1147 * <code>TypeCode</code>), then this attribute will be an any 1148 * containing the system exception <code>UNKNOWN</code> with a 1149 * standard minor code of 1. 1150 * 1151 * @see <a href="package-summary.html#unimpl"> 1152 * <code>PortableInterceptor</code> package comments for 1153 * limitations / unimplemented features</a> 1154 */ 1155 readonly attribute any sending_exception; 1156 1157 /** 1158 * Returns the opaque <code>object_id</code> describing the target of 1159 * the operation invocation. 1160 */ 1161 readonly attribute ObjectId object_id; 1162 1163 /** 1164 * Returns the opaque identifier for the object adapter. 1165 */ 1166 readonly attribute CORBA::OctetSeq adapter_id; 1167 1168 /** 1169 * Returns the server ID that was specified on ORB::init using the -ORBServerId 1170 * argument. 1171 */ 1172 readonly attribute ServerId server_id ; 1173 1174 /** 1175 * Returns the ID that was used to create the ORB. 1176 */ 1177 readonly attribute ORBId orb_id ; 1178 1179 /** 1180 * Returns the sequence of strings that identifies the object 1181 * adapter instance that is handling this request. 1182 */ 1183 readonly attribute AdapterName adapter_name ; 1184 1185 /** 1186 * Returns the repository id for the most derived interface of the 1187 * servant. 1188 */ 1189 readonly attribute CORBA::RepositoryId 1190 target_most_derived_interface; 1191 1192 /** 1193 * Returns the policy in effect for this operation for the given 1194 * policy type. The returned <code>CORBA.Policy</code> object shall 1195 * only be a policy whose type was registered via 1196 * <code>register_policy_factory</code>. 1197 * 1198 * @param type The <code>CORBA.PolicyType</code> which specifies the 1199 * policy to be returned. 1200 * @return The <code>CORBA.Policy</code> obtained with the given 1201 * policy type. 1202 * @exception INV_POLICY thrown, with a standard minor code of 2, if 1203 * a policy for the given type was not registered via 1204 * <code>register_policy_factory</code>. 1205 * @see ORBInitInfo#register_policy_factory 1206 */ 1207 CORBA::Policy get_server_policy 1208 (in CORBA::PolicyType type); 1209 1210 /** 1211 * Allows an Interceptor to set a slot in the 1212 * <code>PortableInterceptor.Current</code> that is in the scope of 1213 * the request. If data already exists in that slot, it will be 1214 * overwritten. 1215 * 1216 * @param id The id of the slot. 1217 * @param data The data, in the form of an any, to store in that slot. 1218 * @exception InvalidSlot thrown if the ID does not define an allocated 1219 * slot. 1220 * @see Current 1221 */ 1222 void set_slot (in SlotId id, in any data) raises (InvalidSlot); 1223 1224 /** 1225 * Returns true if the servant is the given repository id, 1226 * false if it is not. 1227 * 1228 * @param id The caller wants to know if the servant is this 1229 * repository id. 1230 * @return Is the servant the given RepositoryId? 1231 */ 1232 boolean target_is_a (in CORBA::RepositoryId id); 1233 1234 /** 1235 * Allows Interceptors to add service contexts to the request. 1236 * <p> 1237 * There is no declaration of the order of the service contexts. 1238 * They may or may not appear in the order that they are added. 1239 * 1240 * @param service_context The <code>IOP.ServiceContext</code> to add to 1241 * the reply. 1242 * @param replace Indicates the behavior of this operation when a 1243 * service context already exists with the given ID. If false, 1244 * then <code>BAD_INV_ORDER</code> with a standard minor code of 15 1245 * is thrown. If true, then the existing service context is 1246 * replaced by the new one. 1247 * @exception BAD_INV_ORDER thrown, with a standard minor code of 15, if 1248 * replace is false and a service context already exists with the 1249 * given ID. 1250 */ 1251 void add_reply_service_context ( 1252 in IOP::ServiceContext service_context, 1253 in boolean replace); 1254 }; 1255 1256 /** 1257 * Client-side request interceptor. 1258 * <p> 1259 * A request Interceptor is designed to intercept the flow of a 1260 * request/reply sequence through the ORB at specific points so that 1261 * services can query the request information and manipulate the service 1262 * contexts which are propagated between clients and servers. The primary 1263 * use of request Interceptors is to enable ORB services to transfer 1264 * context information between clients and servers. There are two types 1265 * of request Interceptors: client-side and server-side. 1266 * <p> 1267 * To write a client-side Interceptor, implement the 1268 * <code>ClientRequestInterceptor</code> interface. 1269 * 1270 * @see ClientRequestInfo 1271 */ 1272 local interface ClientRequestInterceptor : Interceptor { 1273 /** 1274 * Allows an Interceptor to query request information and modify the 1275 * service context before the request is sent to the server. 1276 * <p> 1277 * This interception point may throw a system exception. If it does, 1278 * no other Interceptors' <code>send_request</code> operations are called. 1279 * Those Interceptors on the Flow Stack are popped and their 1280 * <code>receive_exception</code> interception points are called. This 1281 * interception point may also throw a <code>ForwardRequest</code> 1282 * exception. If an Interceptor throws this exception, no other 1283 * Interceptors' <code>send_request</code> operations are 1284 * called. Those Interceptors on the Flow Stack are popped and their 1285 * <code>receive_other</code> interception points are called. 1286 * <p> 1287 * Compliant Interceptors shall properly follow completion_status 1288 * semantics if they throw a system exception from this interception 1289 * point. The <code>completion_status</code> shall be 1290 * <code>COMPLETED_NO</code>. 1291 * 1292 * @param ri Information about the current request being intercepted. 1293 * @exception ForwardRequest If thrown, indicates to the ORB that a 1294 * retry of the request should occur with the new object given in 1295 * the exception. 1296 */ 1297 void send_request (in ClientRequestInfo ri) raises (ForwardRequest); 1298 1299 /** 1300 * Allows an Interceptor to query information during a Time-Independent 1301 * Invocation (TII) polling get reply sequence. 1302 * <p> 1303 * With TII, an application may poll for a response to a request sent 1304 * previously by the polling client or some other client. This poll is 1305 * reported to Interceptors through the <code>send_poll</code> 1306 * interception point and the response is returned through the 1307 * <code>receive_reply</code> or <code>receive_exception</code> 1308 * interception points. If the response is not available before the 1309 * poll time-out expires, the system exception <code>TIMEOUT</code> is 1310 * thrown and <code>receive_exception</code> is called with this 1311 * exception. 1312 * <p> 1313 * This interception point may throw a system exception. If it does, 1314 * no other Interceptors' <code>send_poll</code> operations are 1315 * called. Those Interceptors on the Flow Stack are popped and their 1316 * <code>receive_exception</code> interception points are called. 1317 * <p> 1318 * Compliant Interceptors shall properly follow 1319 * <code>completion_status</code> semantics if they throw a system 1320 * exception from this interception point. The completion_status shall be 1321 * <code>COMPLETED_NO</code>. 1322 * 1323 * @param ri Information about the current request being intercepted. 1324 * @exception TIMEOUT thrown if the response is not available before 1325 * the poll time-out expires 1326 */ 1327 void send_poll (in ClientRequestInfo ri); 1328 1329 /** 1330 * Allows an Interceptor to query the information on a reply after it 1331 * is returned from the server and before control is returned to the 1332 * client. 1333 * <p> 1334 * This interception point may throw a system exception. If it does, 1335 * no other Interceptors' <code>receive_reply</code> operations are 1336 * called. The remaining Interceptors in the Flow Stack shall have 1337 * their <code>receive_exception</code> interception point called. 1338 * <p> 1339 * Compliant Interceptors shall properly follow 1340 * <code>completion_status</code> semantics if they throw a system 1341 * exception from this interception point. The 1342 * <code>completion_status</code> shall be <code>COMPLETED_YES</code>. 1343 * 1344 * @param ri Information about the current request being intercepted. 1345 */ 1346 void receive_reply (in ClientRequestInfo ri); 1347 1348 /** 1349 * Indicates to the interceptor that an exception occurred. Allows 1350 * an Interceptor to query the exception's information before it is 1351 * thrown to the client. 1352 * <p> 1353 * This interception point may throw a system exception. This has the 1354 * effect of changing the exception which successive Interceptors 1355 * popped from the Flow Stack receive on their calls to 1356 * <code>receive_exception</code>. The exception thrown to the client 1357 * will be the last exception thrown by an Interceptor, or the original 1358 * exception if no Interceptor changes the exception. 1359 * <p> 1360 * This interception point may also throw a <code>ForwardRequest</code> 1361 * exception. If an Interceptor throws this exception, no other 1362 * Interceptors' <code>receive_exception</code> operations are called. 1363 * The remaining Interceptors in the Flow Stack are popped and have their 1364 * <code>receive_other</code> interception point called. 1365 * <p> 1366 * If the <code>completion_status</code> of the exception is not 1367 * <code>COMPLETED_NO</code>, then it is inappropriate for this 1368 * interception point to throw a <code>ForwardRequest</code> exception. 1369 * The request s at-most-once semantics would be lost. 1370 * <p> 1371 * Compliant Interceptors shall properly follow 1372 * <code>completion_status</code> semantics if they throw a system 1373 * exception from this interception point. If the original exception is 1374 * a system exception, the <code>completion_status</code> of the new 1375 * exception shall be the same as on the original. If the original 1376 * exception is a user exception, then the <code>completion_status</code> 1377 * of the new exception shall be <code>COMPLETED_YES</code>. 1378 * <p> 1379 * Under some conditions, depending on what policies are in effect, an 1380 * exception (such as <code>COMM_FAILURE</code>) may result in a retry 1381 * of the request. While this retry is a new request with respect to 1382 * Interceptors, there is one point of correlation between the original 1383 * request and the retry: because control has not returned to the 1384 * client, the <code>PortableInterceptor.Current</code> for both the 1385 * original request and the retrying request is the same. 1386 * 1387 * @param ri Information about the current request being intercepted. 1388 * @exception ForwardRequest If thrown, indicates to the ORB that a 1389 * retry of the request should occur with the new object given in 1390 * the exception. 1391 */ 1392 void receive_exception (in ClientRequestInfo ri) raises (ForwardRequest); 1393 1394 /** 1395 * Allows an Interceptor to query the information available when a 1396 * request results in something other than a normal reply or an 1397 * exception. For example, a request could result in a retry 1398 * (e.g., a GIOP Reply with a <code>LOCATION_FORWARD</code> status was 1399 * received); or on asynchronous calls, the reply does not immediately 1400 * follow the request, but control shall return to the client and an 1401 * ending interception point shall be called. 1402 * <p> 1403 * For retries, depending on the policies in effect, a new request may or 1404 * may not follow when a retry has been indicated. If a new request does 1405 * follow, while this request is a new request, with respect to 1406 * Interceptors, there is one point of correlation between the original 1407 * request and the retry: because control has not returned to the client, 1408 * the request scoped <code>PortableInterceptor.Current</code> for both 1409 * the original request and the retrying request is the same. 1410 * <p> 1411 * This interception point may throw a system exception. If it does, no 1412 * other Interceptors' <code>receive_other</code> operations are called. 1413 * The remaining Interceptors in the Flow Stack are popped and have 1414 * their <code>receive_exception</code> interception point called. 1415 * <p> 1416 * This interception point may also throw a <code>ForwardRequest</code> 1417 * exception. If an Interceptor throws this exception, successive 1418 * Interceptors' <code>receive_other</code> operations are called with 1419 * the new information provided by the <code>ForwardRequest</code> 1420 * exception. 1421 * <p> 1422 * Compliant Interceptors shall properly follow 1423 * <code>completion_status</code> semantics if they throw a system 1424 * exception from this interception point. The 1425 * <code>completion_status</code> shall be <code>COMPLETED_NO</code>. 1426 * If the target invocation had completed, this interception point 1427 * would not be called. 1428 * 1429 * @param ri Information about the current request being intercepted. 1430 * @exception ForwardRequest If thrown, indicates to the ORB that a 1431 * retry of the request should occur with the new object given in 1432 * the exception. 1433 */ 1434 void receive_other (in ClientRequestInfo ri) raises (ForwardRequest); 1435 }; 1436 1437 /** 1438 * Server-side request interceptor. 1439 * <p> 1440 * A request Interceptor is designed to intercept the flow of a 1441 * request/reply sequence through the ORB at specific points so that 1442 * services can query the request information and manipulate the service 1443 * contexts which are propagated between clients and servers. The primary 1444 * use of request Interceptors is to enable ORB services to transfer 1445 * context information between clients and servers. There are two types 1446 * of request Interceptors: client-side and server-side. 1447 * <p> 1448 * To write a server-side Interceptor, implement the 1449 * ServerRequestInterceptor interface. 1450 * 1451 * @see ServerRequestInfo 1452 */ 1453 local interface ServerRequestInterceptor : Interceptor { 1454 /** 1455 * Allows the interceptor to process service context information. 1456 * <p> 1457 * At this interception point, Interceptors must get their service 1458 * context information from the incoming request transfer it to 1459 * <code>PortableInterceptor.Current</code>'s slots. 1460 * <p> 1461 * This interception point is called before the servant manager is called. 1462 * Operation parameters are not yet available at this point. This 1463 * interception point may or may not execute in the same thread as 1464 * the target invocation. 1465 * <p> 1466 * This interception point may throw a system exception. If it does, 1467 * no other Interceptors' <code>receive_request_service_contexts</code> 1468 * operations are called. Those Interceptors on the Flow Stack are 1469 * popped and their <code>send_exception</code> interception points are 1470 * called. 1471 * <p> 1472 * This interception point may also throw a <code>ForwardRequest</code> 1473 * exception. If an Interceptor throws this exception, no other 1474 * Interceptors' <code>receive_request_service_contexts</code> operations 1475 * are called. Those Interceptors on the Flow Stack are popped and 1476 * their <code>send_other</code> interception points are called. 1477 * <p> 1478 * Compliant Interceptors shall properly follow 1479 * <code>completion_status</code> semantics if they throw a system 1480 * exception from this interception point. The 1481 * <code>completion_status</code> shall be COMPLETED_NO. 1482 * 1483 * @param ri Information about the current request being intercepted. 1484 * @exception ForwardRequest If thrown, indicates to the ORB that a 1485 * retry of the request should occur with the new object given in 1486 * the exception. 1487 */ 1488 void receive_request_service_contexts (in ServerRequestInfo ri) 1489 raises (ForwardRequest); 1490 1491 /** 1492 * Allows an Interceptor to query request information after all the 1493 * information, including operation parameters, are available. This 1494 * interception point shall execute in the same thread as the target 1495 * invocation. 1496 * <p> 1497 * In the DSI model, since the parameters are first available when 1498 * the user code calls <code>arguments</code>, <code>receive_request</code> 1499 * is called from within <code>arguments</code>. It is possible that 1500 * <code>arguments</code> is not called in the DSI model. The target 1501 * may call <code>set_exception</code> before calling 1502 * <code>arguments</code>. The ORB shall guarantee that 1503 * <code>receive_request</code> is called once, either through 1504 * <code>arguments</code> or through <code>set_exception</code>. If it 1505 * is called through <code>set_exception</code>, requesting the 1506 * arguments will result in <code>NO_RESOURCES</code> being thrown with 1507 * a standard minor code of 1. 1508 * <p> 1509 * This interception point may throw a system exception. If it does, no 1510 * other Interceptors' <code>receive_request</code> operations are 1511 * called. Those Interceptors on the Flow Stack are popped and their 1512 * <code>send_exception</code> interception points are called. 1513 * <p> 1514 * This interception point may also throw a <code>ForwardRequest</code> 1515 * exception. If an Interceptor throws this exception, no other 1516 * Interceptors' <code>receive_request</code> operations are called. 1517 * Those Interceptors on the Flow Stack are popped and their 1518 * <code>send_other</code> interception points are called. 1519 * <p> 1520 * Compliant Interceptors shall properly follow 1521 * <code>completion_status</code> semantics if they throw a system 1522 * exception from this interception point. The 1523 * <code>completion_status</code> shall be <code>COMPLETED_NO</code>. 1524 * 1525 * @param ri Information about the current request being intercepted. 1526 * @exception ForwardRequest If thrown, indicates to the ORB that a 1527 * retry of the request should occur with the new object given in 1528 * the exception. 1529 */ 1530 void receive_request (in ServerRequestInfo ri) raises (ForwardRequest); 1531 1532 /** 1533 * Allows an Interceptor to query reply information and modify the 1534 * reply service context after the target operation has been invoked 1535 * and before the reply is returned to the client. This interception 1536 * point shall execute in the same thread as the target invocation. 1537 * <p> 1538 * This interception point may throw a system exception. If it does, 1539 * no other Interceptors' <code>send_reply</code> operations are called. 1540 * The remaining Interceptors in the Flow Stack shall have their 1541 * <code>send_exception</code> interception point called. 1542 * <p> 1543 * Compliant Interceptors shall properly follow 1544 * <code>completion_status</code> semantics if they throw a 1545 * system exception from this interception point. The 1546 * <code>completion_status</code> shall be <code>COMPLETED_YES</code>. 1547 * 1548 * @param ri Information about the current request being intercepted. 1549 */ 1550 void send_reply (in ServerRequestInfo ri); 1551 1552 /** 1553 * Allows an Interceptor to query the exception information and modify 1554 * the reply service context before the exception is thrown to the client. 1555 * When an exception occurs, this interception point is called. This 1556 * interception point shall execute in the same thread as the target 1557 * invocation. 1558 * <p> 1559 * This interception point may throw a system exception. This has the 1560 * effect of changing the exception which successive Interceptors 1561 * popped from the Flow Stack receive on their calls to 1562 * <code>send_exception</code>. The exception thrown to the client will 1563 * be the last exception thrown by an Interceptor, or the original 1564 * exception if no Interceptor changes the exception. 1565 * <p> 1566 * This interception point may also throw a <code>ForwardRequest</code> 1567 * exception. If an Interceptor throws this exception, no other 1568 * Interceptors' <code>send_exception</code> operations are called. The 1569 * remaining Interceptors in the Flow Stack shall have their 1570 * <code>send_other</code> interception points called. 1571 * <p> 1572 * If the <code>completion_status</code> of the exception is not 1573 * <code>COMPLETED_NO</code>, then it is inappropriate for this 1574 * interception point to throw a <code>ForwardRequest</code> exception. 1575 * The request's at-most-once semantics would be lost. 1576 * <p> 1577 * Compliant Interceptors shall properly follow 1578 * <code>completion_status</code> semantics if they throw a system 1579 * exception from this interception point. If the original exception 1580 * is a system exception, the <code>completion_status</code> of the new 1581 * exception shall be the same as on the original. If the original 1582 * exception is a user exception, then the <code>completion_status</code> 1583 * of the new exception shall be <code>COMPLETED_YES</code>. 1584 * 1585 * @param ri Information about the current request being intercepted. 1586 * @exception ForwardRequest If thrown, indicates to the ORB that a 1587 * retry of the request should occur with the new object given in 1588 * the exception. 1589 */ 1590 void send_exception (in ServerRequestInfo ri) raises (ForwardRequest); 1591 1592 /** 1593 * Allows an Interceptor to query the information available when a 1594 * request results in something other than a normal reply or an 1595 * exception. For example, a request could result in a retry 1596 * (e.g., a GIOP Reply with a <code>LOCATION_FORWARD</code> status was 1597 * received). This interception point shall execute in the same thread 1598 * as the target invocation. 1599 * <p> 1600 * This interception point may throw a system exception. If it does, 1601 * no other Interceptors' <code>send_other</code> operations are called. 1602 * The remaining Interceptors in the Flow Stack shall have their 1603 * <code>send_exception</code> interception points called. 1604 * <p> 1605 * This interception point may also throw a <code>ForwardRequest</code> 1606 * exception. If an Interceptor throws this exception, successive 1607 * Interceptors' <code>send_other</code> operations are called with 1608 * the new information provided by the <code>ForwardRequest</code> 1609 * exception. 1610 * <p> 1611 * Compliant Interceptors shall properly follow 1612 * <code>completion_status</code> semantics if they throw a system 1613 * exception from this interception point. The 1614 * <code>completion_status</code> shall be <code>COMPLETED_NO</code>. 1615 * 1616 * @param ri Information about the current request being intercepted. 1617 * @exception ForwardRequest If thrown, indicates to the ORB that a 1618 * retry of the request should occur with the new object given in 1619 * the exception. 1620 */ 1621 void send_other (in ServerRequestInfo ri) raises (ForwardRequest); 1622 }; 1623 1624 /** The object reference factory. This provides the capability of 1625 * creating an object reference. 1626 */ 1627 abstract valuetype ObjectReferenceFactory { 1628 /** make_object creates a CORBA object reference according 1629 * to the data in this template, with the given repository ID and 1630 * object ID. 1631 */ 1632 Object make_object( in string repositoryId, in ObjectId object_id ) ; 1633 } ; 1634 1635 /** The object reference template. An instance of this must 1636 * exist for each object adapter created in an ORB. The server_id, 1637 * orb_id, and adapter_name attributes uniquely identify this template 1638 * within the scope of an IMR. Note that adapter_id is similarly unique 1639 * within the same scope, but it is opaque, and less useful in many 1640 * cases. 1641 */ 1642 abstract valuetype ObjectReferenceTemplate : ObjectReferenceFactory { 1643 1644 readonly attribute ServerId server_id ; 1645 1646 readonly attribute ORBId orb_id ; 1647 1648 readonly attribute AdapterName adapter_name ; 1649 } ; 1650 1651 /** Sequence of object reference templates is used for reporting state 1652 * changes that do not occur on the adapter manager. 1653 */ 1654 typedef sequence<ObjectReferenceTemplate> ObjectReferenceTemplateSeq ; 1655 1656 /** Adapter manager identifier. Every object adapter has an adapter manager, 1657 * indicated in this API only through the ID. A group of object adapter 1658 * instances may share the same adapter manager, in which case state transitions 1659 * reported for the adapter manager are observed by all object adapters with the 1660 * same adapter manager ID. 1661 */ 1662 typedef long AdapterManagerId ; 1663 1664 /** Type of object adapter state. State changes are reported either to 1665 * the object adapter or to the adapter manager. 1666 */ 1667 typedef short AdapterState ; 1668 1669 /** Object adapter state that holds requests temporarily until the 1670 * state is changed. 1671 */ 1672 const AdapterState HOLDING = 0 ; 1673 1674 /** Object adapter state that indicates normal request processing. 1675 */ 1676 const AdapterState ACTIVE = 1 ; 1677 1678 /** Object adapter state that causes all requests to be discarded. 1679 */ 1680 const AdapterState DISCARDING = 2 ; 1681 1682 /** Object adapter state that causes all requests to be discarded. 1683 * This state indicates that the adapter is shutting down. 1684 */ 1685 const AdapterState INACTIVE = 3 ; 1686 1687 /** Object adapter state indicating that the adapter has been destroyed. 1688 */ 1689 const AdapterState NON_EXISTENT = 4 ; 1690 1691 /** 1692 * Provides the server-side ORB service with access to the applicable 1693 * policies during IOR construction and the ability to add components. 1694 * The ORB passes an instance of its implementation of this interface as 1695 * a parameter to <code>IORInterceptor.establish_components</code>. 1696 * 1697 * @see IORInterceptor 1698 */ 1699 local interface IORInfo { 1700 1701 /** 1702 * Allows an ORB service implementation to determine what server side 1703 * policy of a particular type is in effect for an IOR being 1704 * constructed. When the IOR being constructed is for an object 1705 * implemented using a POA, all Policy objects passed to the 1706 * <code>PortableServer.POA.create_POA</code> call that created that 1707 * POA are accessable via <code>get_effective_policy</code>. 1708 * <p> 1709 * If a policy for the given type is not known to the ORB, then this 1710 * operation will throw <code>INV_POLICY</code> with a standard minor 1711 * code of 2. 1712 * 1713 * @param type an int specifying the type of policy to return. 1714 * @return The effective <code>CORBA.Policy</code> object of the 1715 * requested type. If the given policy type is known, but no policy 1716 * of that type is in effect, then this operation will return a 1717 * nil object reference. 1718 */ 1719 CORBA::Policy get_effective_policy 1720 (in CORBA::PolicyType type); 1721 1722 /** 1723 * A portable ORB service implementation calls 1724 * <code>add_ior_component</code> from its implementation of 1725 * <code>establish_components</code> to add a tagged component to the 1726 * set which will be included when constructing IORs. The components in 1727 * this set will be included in all profiles. 1728 * <p> 1729 * Any number of components may exist with the same component ID. 1730 * 1731 * @param tagged_component The IOP.TaggedComponent to add. 1732 */ 1733 void add_ior_component 1734 (in IOP::TaggedComponent tagged_component); 1735 1736 /** 1737 * A portable ORB service implementation calls 1738 * <code>add_ior_component_to_profile</code> from its implementation of 1739 * <code>establish_components</code> to add a tagged component to the 1740 * set which will be included when constructing IORs. The components in 1741 * this set will be included in the specified profile. 1742 * <p> 1743 * Any number of components may exist with the same component ID. 1744 * 1745 * @param tagged_component The <code>IOP.TaggedComponent</code> to add. 1746 * @param profile_id The profile id of the profile to 1747 * which this component will be added. 1748 * @exception BAD_PARAM thrown, with a standard minor code of 29, if the 1749 * given profile ID does not define a known profile or it is 1750 * impossible to add components to that profile. 1751 */ 1752 void add_ior_component_to_profile ( 1753 in IOP::TaggedComponent tagged_component, 1754 in IOP::ProfileId profile_id); 1755 1756 /** Return the adapter manager id of the object adapter 1757 * that was just created and is running IOR interceptors. 1758 */ 1759 readonly attribute AdapterManagerId manager_id ; 1760 1761 /** Return the adapter state of the object adapter 1762 * that was just created and is running IOR interceptors. 1763 */ 1764 readonly attribute AdapterState state ; 1765 1766 /** Return the object reference template of the object adapter 1767 * that was just created and is running IOR interceptors. 1768 */ 1769 readonly attribute ObjectReferenceTemplate adapter_template ; 1770 1771 /** On read, returns the current factory that will be used to create 1772 * object references for the object adapter that was just created 1773 * and is running IOR interceptors. By default, this factory is the same 1774 * as the value of the adapter_template attribute. The current_factory 1775 * may also be set to another object reference template inside an 1776 * IORInterceptor_3_0. 1777 */ 1778 attribute ObjectReferenceFactory current_factory ; 1779 }; 1780 1781 /** 1782 * Interceptor used to establish tagged components in the profiles within 1783 * an IOR. 1784 * <p> 1785 * In some cases, a portable ORB service implementation may need to add 1786 * information describing the server's or object's ORB service related 1787 * capabilities to object references in order to enable the ORB service 1788 * implementation in the client to function properly. 1789 * <p> 1790 * This is supported through the <code>IORInterceptor</code> and 1791 * <code>IORInfo</code> interfaces. 1792 * 1793 * @see IORInfo 1794 */ 1795 local interface IORInterceptor : Interceptor { 1796 /** 1797 * A server side ORB calls the <code>establish_components</code> 1798 * operation on all registered <code>IORInterceptor</code> instances 1799 * when it is assembling the list of components that will be included 1800 * in the profile or profiles of an object reference. This operation 1801 * is not necessarily called for each individual object reference. 1802 * In the case of the POA, this operation is called each time POA::create_POA 1803 * is called. In any case, <code>establish_components</code> is 1804 * guaranteed to be called at least once for each distinct set of 1805 * server policies. 1806 * <p> 1807 * An implementation of <code>establish_components</code> must not 1808 * throw exceptions. If it does, the ORB shall ignore the exception 1809 * and proceed to call the next IOR Interceptor's 1810 * <code>establish_components</code> operation. 1811 * 1812 * @param info The <code>IORInfo</code> instance used by the ORB 1813 * service to query applicable policies and add components to be 1814 * included in the generated IORs. 1815 */ 1816 void establish_components (in IORInfo info); 1817 }; 1818 1819 local interface IORInterceptor_3_0 : IORInterceptor { 1820 /** The components_established method is invoked on all registered 1821 * IORInterceptor_3_0 instances after establish_components 1822 * has been invoked on all registered IORInterceptor instances. 1823 * The adapter_template is available in info during this call. 1824 * The current_factory may be get or set in info during this call. 1825 * <p> 1826 * Any exception thrown from this method is handled by the Object 1827 * Adapter that called this interceptor. In the case of the POA, 1828 * an exception results in a OBJ_ADAPTER exception with an OMG 1829 * standard minor code of 6. 1830 * @param info The IORInfo for the object adapter being created. 1831 */ 1832 void components_established( in IORInfo info ) ; 1833 1834 /** Called whenever the state of an adapter manager changes. 1835 * For the POA, that is the POAManager. If the state change 1836 * is reported through <code>adapter_manager_state_changed</code>, 1837 * it is not reported through <code>adapter_state_changed</code>. 1838 * @param id the adapter manager id of the adapter manager that 1839 * changed state 1840 * @param state the new state of the adapter manager 1841 */ 1842 void adapter_manager_state_changed( in AdapterManagerId id, 1843 in AdapterState state ) ; 1844 1845 /** Called whenever the state of an object adapter changes, and 1846 * the state change is not caused by an adapter manager. Such 1847 * changes are reported to all registered <code>IORInterceptor_3_0</code> 1848 * instances. 1849 * @param templates the sequence of <code>ObjectReferenceTemplate</code> instances 1850 * on which this state change occurred. 1851 * @param state the new <code>AdapterState</code> shared by all of the templates. 1852 */ 1853 void adapter_state_changed( in ObjectReferenceTemplateSeq templates, 1854 in AdapterState state ) ; 1855 }; 1856 1857 /** 1858 * Enables policy types to be constructed using 1859 * <code>CORBA.ORB.create_policy</code>. 1860 * <p> 1861 * A portable ORB service implementation registers an instance of the 1862 * <code>PolicyFactory</code> interface during ORB initialization in order 1863 * to enable its policy types to be constructed using 1864 * <code>CORBA.ORB.create_policy</code>. The POA is required to preserve 1865 * any policy which is registered with <code>ORBInitInfo</code> in this 1866 * manner. 1867 * 1868 * @see ORBInitInfo#register_policy_factory 1869 */ 1870 local interface PolicyFactory 1871 { 1872 /** 1873 * Returns an instance of the appropriate interface derived from 1874 * <code>CORBA.Policy</code> whose value corresponds to the 1875 * specified any. 1876 * <p> 1877 * The ORB calls <code>create_policy</code> on a registered 1878 * <code>PolicyFactory</code> instance when 1879 * <code>CORBA.ORB.create_policy</code> is called for the 1880 * <code>PolicyType</code> under which the <code>PolicyFactory</code> has 1881 * been registered. The <code>create_policy</code> operation then 1882 * returns an instance of the appropriate interface derived from 1883 * <code>CORBA.Policy</code> whose value corresponds to the specified 1884 * any. If it cannot, it shall throw an exception as described for 1885 * <code>CORBA.ORB.create_policy</code>. 1886 * 1887 * @param type An int specifying the type of policy being created. 1888 * @param value An any containing data with which to construct the 1889 * <code>CORBA.Policy</code>. 1890 * @return A <code>CORBA.Policy</code> object of the specified type and 1891 * value. 1892 */ 1893 CORBA::Policy create_policy 1894 (in CORBA::PolicyType type, in any value) 1895 raises (CORBA::PolicyError); 1896 }; 1897 1898 /** 1899 * Passed to each <code>ORBInitializer</code>, allowing it to 1900 * to register interceptors and perform other duties while the ORB is 1901 * initializing. 1902 * <p> 1903 * The <code>ORBInitInfo</code> object is only valid during 1904 * <code>ORB.init</code>. If a service keeps a reference to its 1905 * <code>ORBInitInfo</code> object and tries to use it after 1906 * <code>ORB.init</code> returns, the object no longer exists and an 1907 * <code>OBJECT_NOT_EXIST</code> exception shall be thrown. 1908 * 1909 * @see ORBInitializer 1910 */ 1911 local interface ORBInitInfo { 1912 1913 /** Object id, represented as a String */ 1914 typedef string ObjectId; 1915 1916 /** 1917 * Only one Interceptor of a given name can be registered with the 1918 * ORB for each Interceptor type. If an attempt is made to register a 1919 * second Interceptor with the same name, DuplicateName is thrown. 1920 * <p> 1921 * An Interceptor may be anonymous, i.e., have an empty string as the 1922 * name attribute. Any number of anonymous Interceptors may be 1923 * registered with the ORB so, if the Interceptor being registered 1924 * is anonymous, the registration operation will not throw 1925 * <code>DuplicateName</code>. 1926 */ 1927 exception DuplicateName { 1928 /** 1929 * The name for which there was already an interceptor registered. 1930 */ 1931 string name; 1932 }; 1933 1934 /** 1935 * This exception is thrown by 1936 * <code>register_initial_reference</code> and 1937 * <code>resolve_initial_references</code>. 1938 * <code>register_initial_reference</code> throws <code>InvalidName</code> 1939 * if: 1940 * <ul> 1941 * <li>this operation is called with an empty string id; or</li> 1942 * <li>this operation is called with an id that is already registered, 1943 * including the default names defined by OMG.</li> 1944 * </ul> 1945 * <code>resolve_initial_references</code> throws 1946 * <code>InvalidName</code> if the name to be resolved is invalid. 1947 */ 1948 exception InvalidName {}; 1949 1950 /** 1951 * Returns the arguments passed to <code>ORB.init</code>. They may or 1952 * may not contain the ORB's arguments. 1953 */ 1954 readonly attribute CORBA::StringSeq arguments; 1955 1956 /** 1957 * Returns the ID of the ORB being initialized. 1958 */ 1959 readonly attribute string orb_id; 1960 1961 /** 1962 * Returns the <code>IOP.CodecFactory</code>. The 1963 * <code>CodecFactory</code> is normally obtained via a call to 1964 * <code>ORB.resolve_initial_references( "CodecFactory" )</code>, but 1965 * since the ORB is not yet available and Interceptors, particularly when 1966 * processing service contexts, will require a <code>Codec</code>, a 1967 * means of obtaining a <code>Codec</code> is necessary during ORB 1968 * initialization. 1969 */ 1970 readonly attribute IOP::CodecFactory codec_factory; 1971 1972 /** 1973 * Identical to <code>ORB.register_initial_reference</code>. This same 1974 * functionality exists here because the ORB, not yet fully initialized, 1975 * is not yet available but initial references may need to be 1976 * registered as part of Interceptor registration. The only difference 1977 * is that the version of this operation on the ORB uses PIDL 1978 * (<code>CORBA.ORB.ObjectId</code>) and 1979 * (<code>CORBA.ORB.InvalidName</code>) whereas the version in this 1980 * interface uses IDL defined in this interface; the semantics are 1981 * identical. 1982 */ 1983 void register_initial_reference (in ObjectId id, in Object obj) 1984 raises (InvalidName); 1985 1986 // This was incorrectly returning void in orbos/99-12-02, correction 1987 // from errata in orbos/00-01-01 1988 /** 1989 * Identical to <code>ORB.resolve_initial_references</code>. This same 1990 * functionality exists here because the ORB, not yet fully initialized, 1991 * is not yet available but initial references may be required from the 1992 * ORB as part of Interceptor registration. The only difference is that 1993 * the version of this operation on the ORB uses PIDL 1994 * (<code>CORBA::ORB::ObjectId</code> and 1995 * <code>CORBA::ORB::InvalidName</code>) whereas the version in this 1996 * interface uses IDL defined in this interface; the semantics 1997 * are identical. 1998 * <p> 1999 * This operation is only valid during post_init. 2000 */ 2001 Object resolve_initial_references (in ObjectId id) raises (InvalidName); 2002 2003 /** 2004 * Used to add a client-side request Interceptor to the list of 2005 * client-side request Interceptors. 2006 * 2007 * @param interceptor The <code>ClientRequestInterceptor</code> to be 2008 * added. 2009 * @exception DuplicateName thrown if a client-side request Interceptor 2010 * has already been registered with this Interceptor's name. 2011 */ 2012 void add_client_request_interceptor 2013 (in ClientRequestInterceptor interceptor) 2014 raises (DuplicateName); 2015 2016 /** 2017 * Used to add a server-side request Interceptor to the list of 2018 * server-side request Interceptors. 2019 * 2020 * @param interceptor The ServerRequestInterceptor to be added. 2021 * @exception DuplicateName thrown if a server-side request Interceptor 2022 * has already been registered with this Interceptor's name 2023 */ 2024 void add_server_request_interceptor ( 2025 in ServerRequestInterceptor interceptor) 2026 raises (DuplicateName); 2027 2028 /** 2029 * Used to add an IOR Interceptor to the list of IOR Interceptors. 2030 * 2031 * @param interceptor The IORInterceptor to be added. 2032 * @exception DuplicateName thrown if an IOR Interceptor has already 2033 * been registered with this Interceptor's name. 2034 */ 2035 void add_ior_interceptor (in IORInterceptor interceptor) 2036 raises (DuplicateName); 2037 2038 /** 2039 * Called to allocate a slot on <code>PortableInterceptor.Current</code>. 2040 * <p> 2041 * Note that while slot id's can be allocated within an ORB initializer, 2042 * the slots themselves cannot be initialized. 2043 * 2044 * @return The index to the slot which has been allocated. 2045 * @exception BAD_INV_ORDER thrown, with a standard minor code of 14, if 2046 * <code>set_slot</code> or <code>get_slot</code> is called on the 2047 * <code>PICurrent</code> within an ORB initializer. 2048 * @see Current 2049 */ 2050 SlotId allocate_slot_id (); 2051 2052 /** 2053 * Registers a <code>PolicyFactory</code> for the given 2054 * <code>PolicyType</code>. 2055 * 2056 * @param type The policy type that the given <code>PolicyFactory</code> 2057 * serves. 2058 * @param policy_factory The factory for the given policy type. 2059 * @exception BAD_INV_ORDER thrown, with a standard minor code of 16, if 2060 * a <code>PolicyFactory</code> already exists for the given 2061 * <code>PolicyType</code>. 2062 */ 2063 void register_policy_factory ( 2064 in CORBA::PolicyType type, 2065 in PolicyFactory policy_factory); 2066 }; 2067 2068 /** 2069 * Facilitates interceptor registration and ORB initialization. 2070 * <p> 2071 * Interceptors are intended to be a means by which ORB services gain 2072 * access to ORB processing, effectively becoming part of the ORB. 2073 * Since Interceptors are part of the ORB, when <code>ORB.init</code> 2074 * returns an ORB, the Interceptors shall have been registered. 2075 * Interceptors cannot be registered on an ORB after it has been 2076 * returned by a call to <code>ORB.init</code>. 2077 * <p> 2078 * An Interceptor is registered by registering an associated 2079 * <code>ORBInitializer</code> object which implements the 2080 * <code>ORBInitializer</code> interface. When an ORB is initializing, 2081 * it shall call each registered <code>ORBInitializer</code>, passing it 2082 * an <code>ORBInitInfo</code> object which is used to register its 2083 * Interceptor. 2084 * <p> 2085 * <b>Registering ORB Initializers in Java</b> 2086 * <p> 2087 * ORBInitializers are registered via Java ORB properties. 2088 * <p> 2089 * The property names are of the form: 2090 * <blockquote><code> 2091 * org.omg.PortableInterceptor.ORBInitializerClass.<Service> 2092 * </code></blockquote> 2093 * where <code><Service></code> is the string name of a class 2094 * which implements 2095 * <blockquote><code> 2096 * org.omg.PortableInterceptor.ORBInitializer 2097 * </code></blockquote> 2098 * To avoid name collisions, the reverse DNS name convention should be 2099 * used. For example, if company X has three initializers, it could define 2100 * the following properties: 2101 * <ul> 2102 * <li><code> 2103 * org.omg.PortableInterceptor.ORBInitializerClass.com.x.Init1 2104 * </code></li> 2105 * <li><code> 2106 * org.omg.PortableInterceptor.ORBInitializerClass.com.x.Init2 2107 * </code></li> 2108 * <li><code> 2109 * org.omg.PortableInterceptor.ORBInitializerClass.com.x.Init3 2110 * </code></li> 2111 * </ul> 2112 * During ORB.init, these ORB properties which begin with 2113 * <code>org.omg.PortableInterceptor.ORBInitializerClass</code> shall be 2114 * collected, the <code><Service></code> portion of each property 2115 * shall be extracted, an object shall be instantiated with the 2116 * <code><Service></code> string as its class name, and the 2117 * <code>pre_init</code> and <code>post_init</code> methods shall be 2118 * called on that object. If there are any exceptions, the ORB shall 2119 * ignore them and proceed. 2120 * <p> 2121 * <b><i>Example</i></b> 2122 * <p> 2123 * A client-side logging service written by company X, for example, may 2124 * have the following ORBInitializer implementation: 2125 * <pre><code> 2126 * package com.x.logging; 2127 * 2128 * import org.omg.PortableInterceptor.Interceptor; 2129 * import org.omg.PortableInterceptor.ORBInitializer; 2130 * import org.omg.PortableInterceptor.ORBInitInfo; 2131 * 2132 * public class LoggingService implements ORBInitializer { 2133 * void pre_init( ORBInitInfo info ) { 2134 * // Instantiate the Logging Service s Interceptor. 2135 * Interceptor interceptor = new LoggingInterceptor(); 2136 * 2137 * // Register the Logging Service s Interceptor. 2138 * info.add_client_request_interceptor( interceptor ); 2139 * } 2140 * 2141 * void post_init( ORBInitInfo info ) { 2142 * // This service does not need two init points. 2143 * } 2144 * } 2145 * </code></pre> 2146 * To run a program called <code>MyApp</code> using this logging 2147 * service, the user could type: 2148 * <blockquote><code> 2149 * java 2150 *-Dorg.omg.PortableInterceptor.ORBInitializerClass.com.x.Logging.LoggingService 2151 * MyApp 2152 * </code></blockquote> 2153 * <p> 2154 * <b>Notes about Registering Interceptors</b> 2155 * <p> 2156 * Request Interceptors are registered on a per-ORB basis. 2157 * <p> 2158 * To achieve virtual per-object Interceptors, query the policies on the 2159 * target from within the interception points to determine whether they 2160 * should do any work. 2161 * <p> 2162 * To achieve virtual per-POA Interceptors, instantiate each POA with a 2163 * different ORB. While Interceptors may be ordered administratively, 2164 * there is no concept of order with respect to the registration of 2165 * Interceptors. Request Interceptors are concerned with service contexts. 2166 * Service contexts have no order, so there is no purpose for request 2167 * Interceptors to have an order. IOR Interceptors are concerned with 2168 * tagged components. Tagged components also have no order, so there 2169 * is no purpose for IOR Interceptors to have an order. 2170 * <p> 2171 * Registration code should avoid using the ORB (i.e., calling 2172 * <code>ORB.init</code> with the provided <code>orb_id</code>). Since 2173 * registration occurs during ORB initialization, results of invocations 2174 * on this ORB while it is in this state are undefined. 2175 * 2176 * @see ORBInitInfo 2177 */ 2178 local interface ORBInitializer { 2179 2180 /** 2181 * Called during ORB initialization. If it is expected that initial 2182 * services registered by an interceptor will be used by other 2183 * interceptors, then those initial services shall be registered at 2184 * this point via calls to 2185 * <code>ORBInitInfo.register_initial_reference</code>. 2186 * 2187 * @param info provides initialization attributes and operations by 2188 * which Interceptors can be registered. 2189 */ 2190 void pre_init (in ORBInitInfo info); 2191 2192 /** 2193 * Called during ORB initialization. If a service must resolve initial 2194 * references as part of its initialization, it can assume that all 2195 * initial references will be available at this point. 2196 * <p> 2197 * Calling the <code>post_init</code> operations is not the final 2198 * task of ORB initialization. The final task, following the 2199 * <code>post_init</code> calls, is attaching the lists of registered 2200 * interceptors to the ORB. Therefore, the ORB does not contain the 2201 * interceptors during calls to <code>post_init</code>. If an 2202 * ORB-mediated call is made from within <code>post_init</code>, no 2203 * request interceptors will be invoked on that call. 2204 * Likewise, if an operation is performed which causes an IOR to be 2205 * created, no IOR interceptors will be invoked. 2206 * 2207 * @param info provides initialization attributes and 2208 * operations by which Interceptors can be registered. 2209 */ 2210 void post_init (in ORBInitInfo info); 2211 }; 2212}; 2213