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: *

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 Strings 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: };