Source for org.omg.CORBA.Request

   1: /* Request.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.CORBA;
  40: 
  41: 
  42: /**
  43:  * An object, containing the information, needed to invoke the method of
  44:  * the local or remote CORBA object. The Request is used in
  45:  * Dynamic Invocation Interface (DII) which allows dynamic creation of
  46:  * requests.
  47:  *
  48:  * @author Audrius Meskauskas (AudriusA@Bioinformatics.org)
  49:  */
  50: public abstract class Request
  51: {
  52:   /**
  53:    * Add the named input parameter that passes value to
  54:    * the method being invoked. This is similar to the "passing by value"
  55:    * conception.
  56:    *
  57:    * The created parameter is returned allowing to set the value.
  58:    *
  59:    * @return the created parameter.
  60:    */
  61:   public abstract Any add_in_arg();
  62: 
  63:   /**
  64:    * Add the input/output parameter that passes value both to and from
  65:    * the method being invoked. This is similar to the "passing by reference"
  66:    * conception.
  67:    *
  68:    * The created parameter is returned allowing to set the value.
  69:    *
  70:    * @return the created parameter.
  71:    */
  72:   public abstract Any add_inout_arg();
  73: 
  74:   /**
  75:    * Add the named input parameter that passes value to
  76:    * the method being invoked. This is similar to the "passing by value"
  77:    * conception.
  78:    *
  79:    * The created parameter is returned allowing to set the value.
  80:    *
  81:    * @param name the parameter name.
  82:    *
  83:    * @return the created parameter.
  84:    */
  85:   public abstract Any add_named_in_arg(String name);
  86: 
  87:   /**
  88:    * Add the named input/output parameter that passes value both to and from
  89:    * the method being invoked. This is similar to the "passing by reference"
  90:    * conception.
  91:    *
  92:    * The created parameter is returned allowing to set the value.
  93:    *
  94:    * @param name the parameter name.
  95:    *
  96:    * @return the created parameter.
  97:    */
  98:   public abstract Any add_named_inout_arg(String name);
  99: 
 100:   /**
 101:    * Add the named output parameter that passes value from
 102:    * the method being invoked. Differently from the java
 103:    * language, the CORBA IDL method can return multiple values.
 104:    *
 105:    * The created parameter is returned allowing to set the value.
 106:    *
 107:    * @param name the parameter name.
 108:    *
 109:    * @return the created parameter.
 110:    */
 111:   public abstract Any add_named_out_arg(String name);
 112: 
 113:   /**
 114:    * Add the output parameter that passes value from
 115:    * the method being invoked. Differently from the java
 116:    * language, the CORBA IDL method can return multiple values.
 117:    *
 118:    * The created parameter is returned allowing to set the value.
 119:    *
 120:    * @return the created parameter.
 121:    */
 122:   public abstract Any add_out_arg();
 123: 
 124:   /**
 125:    * Return the list of all previously added parameters.
 126:    *
 127:    * @return the list of parameters.
 128:    */
 129:   public abstract NVList arguments();
 130: 
 131:   /**
 132:    * Get the context list object for this request.
 133:    *
 134:    * @return a list of strings that must be resolved and sent with the
 135:    * invocation.
 136:    */
 137:   public abstract ContextList contexts();
 138: 
 139:   /**
 140:    * Get the context, previously set using {@link #ctx(Context)}.
 141:    * The context contains the details about this request.
 142:    */
 143:   public abstract Context ctx();
 144: 
 145:   /**
 146:    * Set the context that shuld be later returned by {@link #ctx()}.
 147:    * This context contains the details about this request.
 148:    *
 149:    * @param a_context a context to set.
 150:    */
 151:   public abstract void ctx(Context a_context);
 152: 
 153:   /**
 154:    * Returns the container, eclosing an exception that the invoked method
 155:    * has thrown.
 156:    *
 157:    * @return the Environment object, containng the exception.
 158:    */
 159:   public abstract Environment env();
 160: 
 161:   /**
 162:    * List the exceptions that may be thrown by the CORBA object method being
 163:    * invoked.
 164:    *
 165:    * @return the list of exceptions.
 166:    */
 167:   public abstract ExceptionList exceptions();
 168: 
 169:   /**
 170:    * Allow to access the response that has been previously sent using
 171:    * {@link #send_deferred()}.
 172:    *
 173:    * @throws WrongTransaction if the transaction scope mismatches.
 174:    */
 175:   public abstract void get_response()
 176:                              throws WrongTransaction;
 177: 
 178:   /**
 179:    * Submit the request, suspending the current thread until the
 180:    * answer is received.
 181:    */
 182:   public abstract void invoke();
 183: 
 184:   /**
 185:    * Get the name of the method being invoked.
 186:    *
 187:    * @return the name of the method being invoked.
 188:    */
 189:   public abstract String operation();
 190: 
 191:   /**
 192:    * Check if the response is received to the request that was
 193:    * previously send using {@link #send_deferred()}.
 194:    *
 195:    * @return true if the response has been already received, false otherwise.
 196:    */
 197:   public abstract boolean poll_response();
 198: 
 199:   /**
 200:    * Get the value, returned by the method, together with its name.
 201:    *
 202:    * @return the value, returned by the method.
 203:    */
 204:   public abstract NamedValue result();
 205: 
 206:   /**
 207:    * Get the value, returned by the method.
 208:    *
 209:    * @return the value, returned by the method.
 210:    */
 211:   public abstract Any return_value();
 212: 
 213:   /**
 214:    * Send a request without suspending the current thread.
 215:    *
 216:    * Allow later check of the request status by {@link #poll_response()} and
 217:    * retrieving the results by {@link #get_response()}.
 218:    */
 219:   public abstract void send_deferred();
 220: 
 221:   /**
 222:    * Send a request and forget about it, not waiting for a response.
 223:    * This can be done also for methods that normally are expected
 224:    * to return some values.
 225:    */
 226:   public abstract void send_oneway();
 227: 
 228:   /**
 229:    * Set the return type.
 230:    *
 231:    * @param returns the type of the value, returned in response to this
 232:    * request.
 233:    */
 234:   public abstract void set_return_type(TypeCode returns);
 235: 
 236:   /**
 237:    * Return the CORBA object on that the method would be invoked.
 238:    *
 239:    * @return the invocation target.
 240:    */
 241:   public abstract org.omg.CORBA.Object target();
 242: }