Source for org.omg.PortableInterceptor.ClientRequestInfoOperations

   1: /* ClientRequestInfoOperations.java --
   2:    Copyright (C) 2005, 2006 Free Software Foundation, Inc.
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10: 
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: 
  39: package org.omg.PortableInterceptor;
  40: 
  41: import org.omg.CORBA.Any;
  42: import org.omg.CORBA.BAD_INV_ORDER;
  43: import org.omg.CORBA.BAD_PARAM;
  44: import org.omg.CORBA.INV_POLICY;
  45: import org.omg.CORBA.Policy;
  46: import org.omg.IOP.ServiceContext;
  47: import org.omg.IOP.TaggedComponent;
  48: import org.omg.IOP.TaggedProfile;
  49: 
  50: /**
  51:  * Provides request information, accessible for the
  52:  * {@linkplain ClientRequestInterceptor}. Some methods of this interface are
  53:  * not valid at all interception points. The following table shows the validity
  54:  * of each method. If it is not valid, BAD_INV_ORDER minor 14 will be thrown.
  55:  *
  56:  * <table border="1">
  57:  * <tr>
  58:  * <th></th>
  59:  * <th>{@linkplain ClientRequestInterceptorOperations#send_request send_request}</th>
  60:  * <th>{@linkplain ClientRequestInterceptorOperations#send_poll send_poll}</th>
  61:  * <th>{@linkplain ClientRequestInterceptorOperations#receive_reply receive_reply}</th>
  62:  * <th>{@linkplain ClientRequestInterceptorOperations#receive_exception receive_exception}</th>
  63:  * <th>{@linkplain ClientRequestInterceptorOperations#receive_other receive_other}</th>
  64:  * </tr>
  65:  * <tr>
  66:  * <td colspan="6" align="center" bgcolor="#E0E0FF"><i>Inherited from
  67:  * {@linkplain RequestInfoOperations}:</i></td>
  68:  * </tr>
  69:  * <tr>
  70:  * <th>{@linkplain RequestInfoOperations#arguments arguments}</th>
  71:  * <td bgcolor="#E0E0E0" title="in and inout only">yes <sub><a href="#1">1</a></sub></td>
  72:  * <td bgcolor="lightgray">no </td>
  73:  * <td>yes</td>
  74:  * <td bgcolor="lightgray">no </td>
  75:  * <td bgcolor="lightgray">no </td>
  76:  * </tr>
  77:  * <tr>
  78:  * <th>{@linkplain RequestInfoOperations#exceptions exceptions}</th>
  79:  * <td>yes</td>
  80:  * <td bgcolor="lightgray">no </td>
  81:  * <td colspan="3" align ="center">yes</td>
  82:  * </tr>
  83:  * <tr>
  84:  * <th>{@linkplain RequestInfoOperations#contexts contexts}</th>
  85:  * <td>yes</td>
  86:  * <td bgcolor="lightgray">no </td>
  87:  * <td colspan="3" align ="center">yes</td>
  88:  * </tr>
  89:  * <tr>
  90:  * <th>{@linkplain RequestInfoOperations#operation_context operation_context}</th>
  91:  * <td>yes</td>
  92:  * <td bgcolor="lightgray">no </td>
  93:  * <td colspan="3" align ="center">yes</td>
  94:  * </tr>
  95:  * </tr>
  96:  * <tr>
  97:  * <th>{@linkplain RequestInfoOperations#result result}</th>
  98:  * <td bgcolor="lightgray">no </td>
  99:  * <td bgcolor="lightgray">no </td>
 100:  * <td>yes</td>
 101:  * <td bgcolor="lightgray">no </td>
 102:  * <td bgcolor="lightgray">no </td>
 103:  * </tr>
 104:  * <tr>
 105:  * <th>{@linkplain RequestInfoOperations#sync_scope sync_scope}</th>
 106:  * <td>yes</td>
 107:  * <td bgcolor="lightgray">no </td>
 108:  * <td colspan="3" align ="center">yes</td>
 109:  * </tr>
 110:  * </tr>
 111:  * <tr>
 112:  * <th>{@linkplain RequestInfoOperations#reply_status reply_status}</th>
 113:  * <td bgcolor="lightgray">no </td>
 114:  * <td bgcolor="lightgray">no </td>
 115:  * <td colspan="3" align ="center">yes</td>
 116:  * </tr>
 117:  * <tr>
 118:  * <th>{@linkplain RequestInfoOperations#forward_reference forward_reference}</th>
 119:  * <td>no</td>
 120:  * <td  bgcolor="lightgray" colspan="3" align="center">no</td>
 121:      * <td bgcolor="#E0E0E0" title="When reply_status = LOCATION_FORWARD">yes <sub><a
 122:  * href="#2">2</a></sub> </td>
 123:  * </tr>
 124:  * <tr>
 125:  * <th>{@linkplain RequestInfoOperations#get_request_service_context get_request_service_context}</th>
 126:  * <td>yes</td>
 127:  * <td bgcolor="lightgray">no </td>
 128:  * <td colspan="3" align ="center">yes</td>
 129:  * </tr>
 130:  * <tr>
 131:  * <th>{@linkplain RequestInfoOperations#get_reply_service_context get_reply_service_context}</th>
 132:  * <td bgcolor="lightgray">no </td>
 133:  * <td bgcolor="lightgray">no </td>
 134:  * <td colspan="3" align ="center">yes</td>
 135:  * </tr>
 136:  * </tr>
 137:  * <tr>
 138:  * <th>{@linkplain RequestInfoOperations#request_id request_id}</th>
 139:  * <td colspan="5" align ="center">yes</td>
 140:  * </tr>
 141:  * <tr>
 142:  * <th>{@linkplain RequestInfoOperations#operation operation}</th>
 143:  * <td colspan="5" align ="center">yes</td>
 144:  * </tr>
 145:  * <tr>
 146:  * <th>{@linkplain RequestInfoOperations#response_expected response_expected}</th>
 147:  * <td colspan="5" align ="center">yes</td>
 148:  * </tr>
 149:  * <tr>
 150:  * <th>{@linkplain RequestInfoOperations#get_slot get_slot}</th>
 151:  * <td colspan="5" align ="center">yes</td>
 152:  * </tr>
 153:  * <tr>
 154:  * <td colspan="6" align="center" bgcolor="#E0E0FF"><i>ClientRequestInfo-specific:</i></td>
 155:  * </tr>
 156:  * <tr>
 157:  * <th>{@linkplain #target target}</th>
 158:  * <td colspan="5" align ="center">yes</td>
 159:  * </tr>
 160:  * <tr>
 161:  * <th>{@linkplain #effective_target effective_target}</th>
 162:  * <td colspan="5" align ="center">yes</td>
 163:  * </tr>
 164:  * <tr>
 165:  * <th>{@linkplain #effective_profile effective_profile}</th>
 166:  * <td colspan="5" align ="center">yes</td>
 167:  * </tr>
 168:  * <tr>
 169:  * <th>{@linkplain #received_exception received_exception}</th>
 170:  * <td  bgcolor="lightgray" colspan="3" align="center">no</td>
 171:  * <td>yes</td>
 172:  * <td bgcolor="lightgray">no </td>
 173:  * </tr>
 174:  * <tr>
 175:  * <th>{@linkplain #received_exception_id received_exception_id}</th>
 176:  * <td  bgcolor="lightgray" colspan="3" align="center">no</td>
 177:  * <td>yes</td>
 178:  * <td bgcolor="lightgray">no </td>
 179:  * </tr>
 180:  * <tr>
 181:  * <th>{@linkplain #get_effective_component get_effective_component}</th>
 182:  * <td>yes</td>
 183:  * <td bgcolor="lightgray">no </td>
 184:  * <td colspan="3" align ="center">yes</td>
 185:  * </tr>
 186:  * <tr>
 187:  * <th>{@linkplain #get_effective_components get_effective_components}</th>
 188:  * <td>yes</td>
 189:  * <td bgcolor="lightgray">no </td>
 190:  * <td colspan="3" align ="center">yes</td>
 191:  * </tr>
 192:  * <tr>
 193:  * <th>{@linkplain #get_request_policy get_request_policy}</th>
 194:  * <td>yes</td>
 195:  * <td bgcolor="lightgray">no </td>
 196:  * <td colspan="3" align ="center">yes</td>
 197:  * </tr>
 198:  * <tr>
 199:      * <th>{@linkplain #add_request_service_context add_request_service_context}</th>
 200:  * <td>yes</td>
 201:  * <td  bgcolor="lightgray" colspan="4" align="center">no</td>
 202:  * </tr>
 203:  * <tr>
 204:  * <th></th>
 205:  * <th>{@linkplain ClientRequestInterceptorOperations#send_request send_request}</th>
 206:  * <th>{@linkplain ClientRequestInterceptorOperations#send_poll send_poll}</th>
 207:  * <th>{@linkplain ClientRequestInterceptorOperations#receive_reply receive_reply}</th>
 208:  * <th>{@linkplain ClientRequestInterceptorOperations#receive_exception receive_exception}</th>
 209:  * <th>{@linkplain ClientRequestInterceptorOperations#receive_other receive_other}</th>
 210:  * </tr>
 211:  * </table>
 212:  * <ol>
 213:  * <li><a name="1">When ClientRequestInfo is passed to send_request, there is
 214:  * an entry in the list for every argument, but only the in and inout arguments
 215:  * will be available.</a></li>
 216:  * <li><a name="2">If the reply_status atribute is not LOCATION_FORWARD,
 217:  * accessing this attribute will throw BAD_INV_ORDER with a standard minor code
 218:  * of 14.</a></li>
 219:  * </ol>
 220:  *
 221:  * @author Audrius Meskauskas, Lithuania (AudriusA@Bioinformatics.org)
 222:  */
 223: public interface ClientRequestInfoOperations extends RequestInfoOperations
 224: {
 225:   /**
 226:        * Returns the object on that the client has invoked the the operation. If the
 227:    * request was forwarded, it will not be the same object that actually
 228:    * processed the request.
 229:    *
 230:    * @return the initial client invocation target.
 231:    *
 232:    * @see #effective_target()
 233:    */
 234:   org.omg.CORBA.Object target();
 235: 
 236:   /**
 237:        * Returns the object on that the operation will be invoked after handling the
 238:    * possible forwarding.
 239:    *
 240:    * @return the final invocation target.
 241:    *
 242:    * @see #target()
 243:    */
 244:   org.omg.CORBA.Object effective_target();
 245: 
 246:   /**
 247:    * Returns the tagged profile (IOR) of the invocation target. If the request
 248:        * was forwarded, the method returns the new location, shown by the forwarding
 249:    * message.
 250:    *
 251:    * @return the invocation IOR.
 252:    */
 253:   TaggedProfile effective_profile();
 254: 
 255:   /**
 256:    * Returns the given component of the invocation target profile. If the
 257:    * profile contains multiple components with the same Id, it is not defined,
 258:    * which one will be returned.
 259:    *
 260:    * @param id the component id.
 261:    *
 262:    * @return the profile component with the given Id.
 263:    *
 264:        * @throws BAD_PARAM minor 28 in there are no any components with the given Id
 265:    * in the profile.
 266:    */
 267:   TaggedComponent get_effective_component(int id) throws BAD_PARAM;
 268: 
 269:   /**
 270:    * Returns the given components of the invocation target profile. This method
 271:    * is uses when the profile may contain multiple components with the same Id.
 272:    *
 273:    * @param id the component id.
 274:    *
 275:    * @return the array of all profile components with the given Id.
 276:    *
 277:        * @throws BAD_PARAM minor 28 in there are no any components with the given Id
 278:    * in the profile.
 279:    */
 280:   TaggedComponent[] get_effective_components(int id) throws BAD_PARAM;
 281: 
 282:   /**
 283:    * This should return the policy of the given type that applies to this
 284:    * operation, but it is not implemented up till JDK 1.5 inclusive.
 285:    *
 286:    * @param type the type of the policy being requested.
 287:    *
 288:    * @return should return the policy that applies to this operation.
 289:    */
 290:   Policy get_request_policy(int type) throws INV_POLICY;
 291: 
 292:   /**
 293:    * Returns the repository id of the remote exception that was thrown on the
 294:    * server side.
 295:    *
 296:    * @return the exception repository id.
 297:    *
 298:    * @see #received_exception()
 299:    */
 300:   String received_exception_id();
 301: 
 302:   /**
 303:    * Returns the remote exception that was thrown on the server side.
 304:    *
 305:    * @return the Any, holding this exception.
 306:    *
 307:    * @see #received_exception_id()
 308:    */
 309:   Any received_exception();
 310: 
 311:   /**
 312:    * Allows the interceptor to add the service contexts to the request. Such
 313:    * added contexts can carry arbitrary data and can be later accessed on the
 314:    * server side by the server request interceptor, using
 315:    * {@link RequestInfoOperations#get_request_service_context}.
 316:    *
 317:    * @param service_context the context to add.
 318:    * @param replace if true, the existing context with the same Id will be
 319:    * replaced. If false, the BAD_INV_ORDER will be thrown in that case.
 320:    *
 321:    * @throws BAD_INV_ORDER minor 15 if the context with the same Id already
 322:    * exists and replace=false.
 323:    */
 324:   void add_request_service_context(ServiceContext service_context,
 325:     boolean replace
 326:   );
 327: }