duke@1: /* duke@1: * Copyright 1996-1999 Sun Microsystems, Inc. All Rights Reserved. duke@1: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. duke@1: * duke@1: * This code is free software; you can redistribute it and/or modify it duke@1: * under the terms of the GNU General Public License version 2 only, as duke@1: * published by the Free Software Foundation. Sun designates this duke@1: * particular file as subject to the "Classpath" exception as provided duke@1: * by Sun in the LICENSE file that accompanied this code. duke@1: * duke@1: * This code is distributed in the hope that it will be useful, but WITHOUT duke@1: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or duke@1: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License duke@1: * version 2 for more details (a copy is included in the LICENSE file that duke@1: * accompanied this code). duke@1: * duke@1: * You should have received a copy of the GNU General Public License version duke@1: * 2 along with this work; if not, write to the Free Software Foundation, duke@1: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. duke@1: * duke@1: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, duke@1: * CA 95054 USA or visit www.sun.com if you need additional information or duke@1: * have any questions. duke@1: */ duke@1: duke@1: package org.omg.CORBA; duke@1: duke@1: /** duke@1: * An object containing the information necessary for duke@1: * invoking a method. This class is duke@1: * the cornerstone of the ORB Dynamic duke@1: * Invocation Interface (DII), which allows dynamic creation and duke@1: * invocation of requests. duke@1: * A server cannot tell the difference between a client duke@1: * invocation using a client stub and a request using the DII. duke@1: *
duke@1: * A Request
object consists of:
duke@1: *
NVList
containing arguments for the operation.NamedValue
object, which has three
duke@1: * parts:
duke@1: * Any
object)
duke@1: *
duke@1: * Request
objects may also contain additional information,
duke@1: * depending on how an operation was defined in the original IDL
duke@1: * interface definition. For example, where appropriate, they may contain
duke@1: * a NamedValue
object to hold the return value or exception,
duke@1: * a context, a list of possible exceptions, and a list of
duke@1: * context strings that need to be resolved.
duke@1: *
duke@1: * New Request
objects are created using one of the
duke@1: * create_request
methods in the Object
class.
duke@1: * In other words, a create_request
method is performed on the
duke@1: * object which is to be invoked.
duke@1: *
duke@1: * @see org.omg.CORBA.NamedValue
duke@1: *
duke@1: */
duke@1:
duke@1: public abstract class Request {
duke@1:
duke@1: /**
duke@1: * Retrieves the the target object reference.
duke@1: *
duke@1: * @return the object reference that points to the
duke@1: * object implementation for the method
duke@1: * to be invoked
duke@1: */
duke@1:
duke@1: public abstract org.omg.CORBA.Object target();
duke@1:
duke@1: /**
duke@1: * Retrieves the name of the method to be invoked.
duke@1: *
duke@1: * @return the name of the method to be invoked
duke@1: */
duke@1:
duke@1: public abstract String operation();
duke@1:
duke@1: /**
duke@1: * Retrieves the NVList
object containing the arguments
duke@1: * to the method being invoked. The elements in the list are
duke@1: * NamedValue
objects, with each one describing an argument
duke@1: * to the method.
duke@1: *
duke@1: * @return the NVList
object containing the arguments
duke@1: * for the method
duke@1: *
duke@1: */
duke@1:
duke@1: public abstract NVList arguments();
duke@1:
duke@1: /**
duke@1: * Retrieves the NamedValue
object containing the return
duke@1: * value for the method.
duke@1: *
duke@1: * @return the NamedValue
object containing the result
duke@1: * of the method
duke@1: */
duke@1:
duke@1: public abstract NamedValue result();
duke@1:
duke@1: /**
duke@1: * Retrieves the Environment
object for this request.
duke@1: * It contains the exception that the method being invoked has
duke@1: * thrown (after the invocation returns).
duke@1: *
duke@1: *
duke@1: * @return the Environment
object for this request
duke@1: */
duke@1:
duke@1: public abstract Environment env();
duke@1:
duke@1: /**
duke@1: * Retrieves the ExceptionList
object for this request.
duke@1: * This list contains TypeCode
objects describing the
duke@1: * exceptions that may be thrown by the method being invoked.
duke@1: *
duke@1: * @return the ExceptionList
object describing the exceptions
duke@1: * that may be thrown by the method being invoked
duke@1: */
duke@1:
duke@1: public abstract ExceptionList exceptions();
duke@1:
duke@1: /**
duke@1: * Retrieves the ContextList
object for this request.
duke@1: * This list contains context String
s that need to
duke@1: * be resolved and sent with the invocation.
duke@1: *
duke@1: *
duke@1: * @return the list of context strings whose values
duke@1: * need to be resolved and sent with the
duke@1: * invocation.
duke@1: */
duke@1:
duke@1: public abstract ContextList contexts();
duke@1:
duke@1: /**
duke@1: * Retrieves the Context
object for this request.
duke@1: * This is a list of properties giving information about the
duke@1: * client, the environment, or the circumstances of this request.
duke@1: *
duke@1: * @return the Context
object that is to be used
duke@1: * to resolve any context strings whose
duke@1: * values need to be sent with the invocation
duke@1: */
duke@1:
duke@1: public abstract Context ctx();
duke@1:
duke@1: /**
duke@1: * Sets this request's Context
object to the one given.
duke@1: *
duke@1: * @param c the new Context
object to be used for
duke@1: * resolving context strings
duke@1: */
duke@1:
duke@1: public abstract void ctx(Context c);
duke@1:
duke@1:
duke@1: /**
duke@1: * Creates an input argument and adds it to this Request
duke@1: * object.
duke@1: *
duke@1: * @return an Any
object that contains the
duke@1: * value and typecode for the input argument added
duke@1: */
duke@1:
duke@1: public abstract Any add_in_arg();
duke@1:
duke@1: /**
duke@1: * Creates an input argument with the given name and adds it to
duke@1: * this Request
object.
duke@1: *
duke@1: * @param name the name of the argument being added
duke@1: * @return an Any
object that contains the
duke@1: * value and typecode for the input argument added
duke@1: */
duke@1:
duke@1: public abstract Any add_named_in_arg(String name);
duke@1:
duke@1: /**
duke@1: * Adds an input/output argument to this Request
object.
duke@1: *
duke@1: * @return an Any
object that contains the
duke@1: * value and typecode for the input/output argument added
duke@1: */
duke@1:
duke@1: public abstract Any add_inout_arg();
duke@1:
duke@1: /**
duke@1: * Adds an input/output argument with the given name to this
duke@1: * Request
object.
duke@1: *
duke@1: * @param name the name of the argument being added
duke@1: * @return an Any
object that contains the
duke@1: * value and typecode for the input/output argument added
duke@1: */
duke@1:
duke@1: public abstract Any add_named_inout_arg(String name);
duke@1:
duke@1:
duke@1: /**
duke@1: * Adds an output argument to this Request
object.
duke@1: *
duke@1: * @return an Any
object that contains the
duke@1: * value and typecode for the output argument added
duke@1: */
duke@1:
duke@1: public abstract Any add_out_arg();
duke@1:
duke@1: /**
duke@1: * Adds an output argument with the given name to this
duke@1: * Request
object.
duke@1: *
duke@1: * @param name the name of the argument being added
duke@1: * @return an Any
object that contains the
duke@1: * value and typecode for the output argument added
duke@1: */
duke@1:
duke@1: public abstract Any add_named_out_arg(String name);
duke@1:
duke@1: /**
duke@1: * Sets the typecode for the return
duke@1: * value of the method.
duke@1: *
duke@1: * @param tc the TypeCode
object containing type information
duke@1: * for the return value
duke@1: */
duke@1:
duke@1: public abstract void set_return_type(TypeCode tc);
duke@1:
duke@1: /**
duke@1: * Returns the Any
object that contains the value for the
duke@1: * result of the method.
duke@1: *
duke@1: * @return an Any
object containing the value and
duke@1: * typecode for the return value
duke@1: */
duke@1:
duke@1: public abstract Any return_value();
duke@1:
duke@1: /**
duke@1: * Makes a synchronous invocation using the
duke@1: * information in the Request
object. Exception information is
duke@1: * placed into the Request
object's environment object.
duke@1: */
duke@1:
duke@1: public abstract void invoke();
duke@1:
duke@1: /**
duke@1: * Makes a oneway invocation on the
duke@1: * request. In other words, it does not expect or wait for a
duke@1: * response. Note that this can be used even if the operation was
duke@1: * not declared as oneway in the IDL declaration. No response or
duke@1: * exception information is returned.
duke@1: */
duke@1:
duke@1: public abstract void send_oneway();
duke@1:
duke@1: /**
duke@1: * Makes an asynchronous invocation on
duke@1: * the request. In other words, it does not wait for a response before it
duke@1: * returns to the user. The user can then later use the methods
duke@1: * poll_response
and get_response
to get
duke@1: * the result or exception information for the invocation.
duke@1: */
duke@1:
duke@1: public abstract void send_deferred();
duke@1:
duke@1: /**
duke@1: * Allows the user to determine
duke@1: * whether a response has been received for the invocation triggered
duke@1: * earlier with the send_deferred
method.
duke@1: *
duke@1: * @return true
if the method response has
duke@1: * been received; false
otherwise
duke@1: */
duke@1:
duke@1: public abstract boolean poll_response();
duke@1:
duke@1: /**
duke@1: * Allows the user to access the
duke@1: * response for the invocation triggered earlier with the
duke@1: * send_deferred
method.
duke@1: *
duke@1: * @exception WrongTransaction if the method get_response
was invoked
duke@1: * from a different transaction's scope than the one from which the
duke@1: * request was originally sent. See the OMG Transaction Service specification
duke@1: * for details.
duke@1: */
duke@1:
duke@1: public abstract void get_response() throws WrongTransaction;
duke@1:
duke@1: };