Source for org.omg.PortableInterceptor.ServerRequestInfoOperations

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