Source for org.omg.PortableInterceptor.ServerRequestInfoOperations

   1: /* ServerRequestInfoOperations.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.INV_POLICY;
  44: import org.omg.CORBA.Policy;
  45: import org.omg.IOP.ServiceContext;
  46: 
  47: /**
  48:  * Provides request information, accessible for the
  49:  * {@link ClientRequestInterceptor}. Some methods of this interface are not
  50:  * valid at all interception points. The following table shows the validity of
  51:  * each method. If it is not valid, BAD_INV_ORDER minor 14 will be thrown.
  52:  *
  53:  * <table border="1">
  54:  * <tr>
  55:  * <th></th>
  56:  * <th>{@link ServerRequestInterceptorOperations#receive_request_service_contexts receive_request_<br>service_contexts}</th>
  57:  * <th>{@link ServerRequestInterceptorOperations#receive_request receive_request}</th>
  58:  * <th>{@link ServerRequestInterceptorOperations#send_reply send_reply}</th>
  59:  * <th>{@link ServerRequestInterceptorOperations#send_exception send_exception}</th>
  60:  * <th>{@link ServerRequestInterceptorOperations#send_other send_other}</th>
  61:  * </tr>
  62:  * <tr>
  63:  * <td colspan="6" align="center" bgcolor="#E0E0FF"><i>Inherited from
  64:  * {@link RequestInfoOperations}:</i></td>
  65:  * </tr>
  66:  * <tr>
  67:  * <th>{@linkplain RequestInfoOperations#arguments arguments}</th>
  68:  * <td  bgcolor="lightgray">no </td>
  69:  * <td  bgcolor="#E0E0E0" title="in and inout only">yes<sub><a href="#1">1</a></sub></td>
  70:  * <td>yes</td>
  71:  * <td  bgcolor="#E0E0E0" title="When reply_status = LOCATION_FORWARD">no<sub><a
  72:  * href="#2">2</a></sub></td>
  73:  * <td  bgcolor="#E0E0E0" title="When reply_status = LOCATION_FORWARD">no<sub><a
  74:  * href="#2">2</a></sub> </td>
  75:  * </tr>
  76:  * <tr>
  77:  * <th>{@linkplain RequestInfoOperations#exceptions exceptions}</th>
  78:  * <td  bgcolor="lightgray">no </td>
  79:  * <td colspan="4" align ="center">yes</td>
  80:  * </tr>
  81:  * <tr>
  82:  * <th>{@linkplain RequestInfoOperations#contexts contexts}</th>
  83:  * <td  bgcolor="lightgray">no </td>
  84:  * <td colspan="4" align ="center">yes</td>
  85:  * </tr>
  86:  * <tr>
  87:  * <th>{@linkplain RequestInfoOperations#operation_context operation_context}</th>
  88:  * <td  bgcolor="lightgray">no </td>
  89:  * <td>yes</td>
  90:  * <td>yes</td>
  91:  * <td  bgcolor="lightgray">no </td>
  92:  * <td  bgcolor="lightgray">no </td>
  93:  * </tr>
  94:  * <tr>
  95:  * <th>{@linkplain RequestInfoOperations#result result}</th>
  96:  * <td  bgcolor="lightgray">no </td>
  97:  * <td  bgcolor="lightgray">no </td>
  98:  * <td>yes</td>
  99:  * <td  bgcolor="lightgray">no </td>
 100:  * <td  bgcolor="lightgray">no </td>
 101:  * </tr>
 102:  * <tr>
 103:  * <th>{@linkplain RequestInfoOperations#reply_status reply_status}</th>
 104:  * <td  bgcolor="lightgray">no </td>
 105:  * <td  bgcolor="lightgray">no </td>
 106:  * <td colspan="3" align="center">yes</td> * </tr>
 107:  * <tr>
 108:  * <th>{@linkplain RequestInfoOperations#forward_reference forward_reference}</th>
 109:  * <td  bgcolor="lightgray" colspan="4" align="center">no</td>
 110:  * <td  bgcolor="#E0E0E0" title="When reply_status = LOCATION_FORWARD">yes<sub><a
 111:  * href="#2">2</a></sub> </td>
 112:  * </tr>
 113:  * <tr>
 114:  * <th>{@linkplain RequestInfoOperations#get_request_service_context get_request_service_context}</th>
 115:  * <td>yes</td>
 116:  * <td  bgcolor="lightgray">no </td>
 117:  * <td colspan="3" align="center">yes</td> * </tr>
 118:  * <tr>
 119:  * <th>{@linkplain RequestInfoOperations#get_reply_service_context get_reply_service_context}</th>
 120:  * <td  bgcolor="lightgray">no </td>
 121:  * <td  bgcolor="lightgray">no </td>
 122:  * <td colspan="3" align="center">yes</td>
 123:  * </tr>
 124:  * <tr>
 125:  * <th>{@linkplain RequestInfoOperations#request_id request_id}</th>
 126:  * <td colspan="5" align ="center">yes</td>
 127:  * </tr>
 128:  * <tr>
 129:  * <th>{@linkplain RequestInfoOperations#operation operation}</th>
 130:  * <td colspan="5" align ="center">yes</td>
 131:  * </tr>
 132:  * <tr>
 133:  * <th>{@linkplain RequestInfoOperations#response_expected response_expected}</th>
 134:  * <td colspan="5" align ="center">yes</td>
 135:  * </tr>
 136:  * <tr>
 137:  * <th>{@linkplain RequestInfoOperations#sync_scope sync_scope}</th>
 138:  * <td colspan="5" align ="center">yes</td>
 139:  * </tr>
 140:  * <tr>
 141:  * <th>{@linkplain RequestInfoOperations#get_slot get_slot}</th>
 142:  * <td colspan="5" align ="center">yes</td>
 143:  * </tr>
 144:  * <tr>
 145:  * <td colspan="6" align="center" bgcolor="#E0E0FF">
 146:  * <i>ServerRequestInfo-specific:</i></td>
 147:  * </tr>
 148:  * <tr>
 149:  * <th>{@linkplain #get_server_policy get_server_policy}</th>
 150:  * <td colspan="5" align ="center">yes</td>
 151:  * </tr>
 152:  * <tr>
 153:  * <th>{@linkplain #add_reply_service_context add_reply_service_context}</th>
 154:  * <td colspan="5" align ="center">yes</td>
 155:  * </tr>
 156:  * <tr>
 157:  * <th>{@linkplain #set_slot set_slot}</th>
 158:  * <td colspan="5" align ="center">yes</td>
 159:  * </tr>
 160:  * <tr>
 161:  * <th>{@linkplain #sending_exception sending_exception}</th>
 162:  * <td  bgcolor="lightgray" colspan="3" align="center">no</td>
 163:  * <td>yes</td>
 164:  * <td  bgcolor="lightgray">no </td>
 165:  * </tr>
 166:  * <tr>
 167:  * <th>{@linkplain #object_id object_id}</th>
 168:  * <td  bgcolor="lightgray">no </td>
 169:  * <td>yes</td>
 170:  * <td>yes</td>
 171:  * <td  bgcolor="#E0E0E0" title="Not always (see note)">yes<sub><a
 172:  * href="#3">3</a></sub></td>
 173:  * <td bgcolor="#E0E0E0"  title="Not always (see note)">yes<sub><a
 174:  * href="#3">3</a></sub> </td>
 175:  * </tr>
 176:  * <tr>
 177:  * <th>{@linkplain #adapter_id adapter_id}</th>
 178:  * <td  bgcolor="lightgray">no </td>
 179:  * <td>yes</td>
 180:  * <td>yes</td>
 181:  * <td  bgcolor="#E0E0E0" title="Not always (see note)">yes<sub><a
 182:  * href="#3">3</a></sub></td>
 183:  * <td  bgcolor="#E0E0E0" title="Not always (see note)">yes<sub><a
 184:  * href="#3">3</a></sub> </td>
 185:  * </tr>
 186:  * <tr>
 187:  * <th>{@linkplain #target_most_derived_interface target_most_derived_interface}</th>
 188:  * <td  bgcolor="lightgray">no </td>
 189:  * <td>yes</td>
 190:  * <td  bgcolor="lightgray" colspan="3" align="center">no</td>
 191:  * </tr>
 192:  * <tr>
 193:  * <th>{@linkplain #target_is_a target_is_a}</th>
 194:  * <td  bgcolor="lightgray">no </td>
 195:  * <td>yes</td>
 196:  * <td  bgcolor="lightgray" colspan="3" align="center">no</td>
 197:  * </tr>
 198:  * <tr>
 199:  * <th></th>
 200:  * <th>{@link ServerRequestInterceptorOperations#receive_request_service_contexts receive_request_<br>service_contexts }</th>
 201:  * <th>{@link ServerRequestInterceptorOperations#receive_request receive_request}</th>
 202:  * <th>{@link ServerRequestInterceptorOperations#send_reply send_reply}</th>
 203:  * <th>{@link ServerRequestInterceptorOperations#send_exception send_exception}</th>
 204:  * <th>{@link ServerRequestInterceptorOperations#send_other send_other}</th>
 205:  * </tr>
 206:  * </table>
 207:  * <ol>
 208:  * <li><a name="1">When ServerRequestInfo is passed to receive_request, there
 209:  * is an entry in the list for every argument. But only the in and inout
 210:  * arguments will be available.</a></li>
 211:  * <li><a name="2">If the reply_status attribute is not LOCATION_FORWARD,
 212:  * accessing this attribute throws BAD_INV_ORDER minor code of 14.</a></li>
 213:  * <li><a name="3">If the servant locator caused a location forward, or thrown
 214:  * an exception, this attribute/operation may not be available (NO_RESOURCES
 215:  * with a standard minor code of 1 will be thrown).</a></li>
 216:  * </ol>
 217:  *
 218:  * @author Audrius Meskauskas, Lithuania (AudriusA@Bioinformatics.org)
 219:  */
 220: public interface ServerRequestInfoOperations
 221:   extends RequestInfoOperations
 222: {
 223:   /**
 224:    * Allows the interceptor to add service contexts to the request. Such added
 225:    * contexts can carry arbitrary data and can be later accessed on the client
 226:    * side by the client request interceptor using
 227:    * {@link RequestInfoOperations#get_reply_service_context}.
 228:    *
 229:    * @param service_context the context to add.
 230:    * @param replace if true, the existing context with the same Id will be
 231:    * replaced. If false, the BAD_INV_ORDER will be thrown in that case.
 232:    *
 233:    * @throws BAD_INV_ORDER minor 15 if the context with the same Id already
 234:    * exists and replace=false.
 235:    */
 236:   void add_reply_service_context(ServiceContext service_context, boolean replace);
 237: 
 238:   /**
 239:    * Get the identifier for the object adapter (POA).
 240:    */
 241:   byte[] adapter_id();
 242: 
 243:   /**
 244:    * Get the object_id describing the target of the operation invocation.
 245:    */
 246:   byte[] object_id();
 247: 
 248:   /**
 249:    * Return the policy of the given type that applies to this operation. This
 250:    * method should only be used with policies, produced by the registered
 251:    * {@link PolicyFactory}.
 252:    *
 253:    * @param type the type of the policy being requested.
 254:    *
 255:    * @return the policy that applies to this operation.
 256:    *
 257:    * @throws INV_POLICY minor 2 if no factory was registered to produce this
 258:    * type of policy or the policy is otherwise invalid.
 259:    */
 260:   Policy get_server_policy(int type)
 261:     throws INV_POLICY;
 262: 
 263:   /**
 264:    * Get the exception to be returned to the client. If the returned Any cannot
 265:    * not support holding of that exception, it holds
 266:    * {@link org.omg.CORBA.UNKNOWN} minor 1 instead.
 267:    *
 268:    * @return an Any, holding exception that has been thrown and will be returned
 269:    * to client.
 270:    */
 271:   Any sending_exception();
 272: 
 273:   /**
 274:    * Allows the interceptor to set a slot in the PortableInterceptor.Current
 275:    * that is in the scope of the request.
 276:    *
 277:    * @param id the Id of the slot.
 278:    * @param data the value of the slot, replacing the previous value.
 279:    *
 280:    * @throws InvalidSlot if the slot with the given Id does not exist.
 281:    *
 282:    * @see RequestInfoOperations#get_slot(int)
 283:    * @see org.omg.PortableInterceptor#Current
 284:    */
 285:   void set_slot(int id, Any data)
 286:     throws InvalidSlot;
 287: 
 288:   /**
 289:    * Checks if the servant is the given repository id.
 290:    *
 291:    * @param id the repository id to compare.
 292:    *
 293:    * @return true if the servant repository id matches the parameter, false
 294:    * otherwise.
 295:    */
 296:   boolean target_is_a(String id);
 297: 
 298:   /**
 299:    * Get the most derived (most specific) repository Id of the servant.
 300:    *
 301:    * @return the repository id of the servant.
 302:    */
 303:   String target_most_derived_interface();
 304: 
 305:   /**
 306:    * Returns the name of the adapter that is handling the current request.
 307:    * The name is returned as a string array, representing full path from
 308:    * the root poa till the current poa, for instance
 309:    * {"RootPOA", "childPOA","grandchildPOA"}.
 310:    */
 311:   public String[] adapter_name();
 312: 
 313:   /**
 314:    * Returns the id of the ORB that is handling the current request. The ORB
 315:    * id can be specified as the property org.omg.CORBA.ORBid when creating
 316:    * the ORB.
 317:    */
 318:   public String orb_id();
 319: 
 320:   /**
 321:    * Returs the id of the server that is handling the current request. The server
 322:    * id is the same for all POAs and ORBs in the current virtual machine and
 323:    * can be set as the property org.omg.CORBA.ServerId when creating one of the
 324:    * ORBs.
 325:    */
 326:   public String server_id();
 327: }