duke@1: /* ohair@158: * Copyright (c) 1996, 2004, Oracle and/or its affiliates. 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 ohair@158: * published by the Free Software Foundation. Oracle designates this duke@1: * particular file as subject to the "Classpath" exception as provided ohair@158: * by Oracle 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: * ohair@158: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA ohair@158: * or visit www.oracle.com if you need additional information or have any ohair@158: * questions. duke@1: */ duke@1: duke@1: package org.omg.CORBA; duke@1: duke@1: /** duke@1: * An object that captures the explicit state of a request duke@1: * for the Dynamic Skeleton Interface (DSI). This class, the duke@1: * cornerstone of the DSI, is analogous to the Request duke@1: * object in the DII. duke@1: *

duke@1: * The ORB is responsible for creating this embodiment of a request, duke@1: * and delivering it to a Dynamic Implementation Routine (DIR). duke@1: * A dynamic servant (a DIR) is created by implementing the duke@1: * DynamicImplementation class, duke@1: * which has a single invoke method. This method accepts a duke@1: * ServerRequest object. duke@1: * duke@1: * The abstract class ServerRequest defines duke@1: * methods for accessing the duke@1: * method name, the arguments and the context of the request, as duke@1: * well as methods for setting the result of the request either as a duke@1: * return value or an exception.

duke@1: * duke@1: * A subtlety with accessing the arguments of the request is that the duke@1: * DIR needs to provide type information about the duke@1: * expected arguments, since there is no compiled information about duke@1: * these. This information is provided through an NVList, duke@1: * which is a list of NamedValue objects. duke@1: * Each NamedValue object duke@1: * contains an Any object, which in turn duke@1: * has a TypeCode object representing the type duke@1: * of the argument.

duke@1: * duke@1: * Similarly, type information needs to be provided for the response, duke@1: * for either the expected result or for an exception, so the methods duke@1: * result and except take an Any duke@1: * object as a parameter.

duke@1: * duke@1: * @see org.omg.CORBA.DynamicImplementation duke@1: * @see org.omg.CORBA.NVList duke@1: * @see org.omg.CORBA.NamedValue duke@1: * duke@1: */ duke@1: duke@1: public abstract class ServerRequest { duke@1: duke@1: /** duke@1: * Retrieves the name of the operation being duke@1: * invoked. According to OMG IDL's rules, these names must be unique duke@1: * among all operations supported by this object's "most-derived" duke@1: * interface. Note that the operation names for getting and setting duke@1: * attributes are _get_<attribute_name> duke@1: * and _set_<attribute_name>, duke@1: * respectively. duke@1: * duke@1: * @return the name of the operation to be invoked duke@1: * @deprecated use operation() duke@1: */ duke@1: @Deprecated duke@1: public String op_name() duke@1: { duke@1: return operation(); duke@1: } duke@1: duke@1: duke@1: /** duke@1: * Throws an org.omg.CORBA.NO_IMPLEMENT exception. duke@1: *

duke@1: * Retrieves the name of the operation being duke@1: * invoked. According to OMG IDL's rules, these names must be unique duke@1: * among all operations supported by this object's "most-derived" duke@1: * interface. Note that the operation names for getting and setting duke@1: * attributes are _get_<attribute_name> duke@1: * and _set_<attribute_name>, duke@1: * respectively. duke@1: * duke@1: * @return the name of the operation to be invoked duke@1: * @see CORBA duke@1: * package comments for unimplemented features duke@1: */ duke@1: public String operation() duke@1: { duke@1: throw new org.omg.CORBA.NO_IMPLEMENT(); duke@1: } duke@1: duke@1: duke@1: /** duke@1: * Specifies method parameter types and retrieves "in" and "inout" duke@1: * argument values. duke@1: *

duke@1: * Note that this method is deprecated; use the method duke@1: * arguments in its place. duke@1: *

duke@1: * Unless it calls the method set_exception, duke@1: * the DIR must call this method exactly once, even if the duke@1: * method signature contains no parameters. Once the method duke@1: * arguments or set_exception duke@1: * has been called, calling arguments on the same duke@1: * ServerRequest object duke@1: * will result in a BAD_INV_ORDER system exception. duke@1: * The DIR must pass in to the method arguments duke@1: * an NVList initialized with TypeCodes and Flags duke@1: * describing the parameter types for the operation, in the order in which duke@1: * they appear in the IDL specification (left to right). A duke@1: * potentially-different NVList will be returned from duke@1: * arguments, with the duke@1: * "in" and "inout" argument values supplied. If it does not call duke@1: * the method set_exception, duke@1: * the DIR must supply the returned NVList with return duke@1: * values for any "out" arguments before returning, and may also change duke@1: * the return values for any "inout" arguments. duke@1: * duke@1: * @param params the arguments of the method, in the duke@1: * form of an NVList object duke@1: * @deprecated use the method arguments duke@1: */ duke@1: @Deprecated duke@1: public void params(NVList params) duke@1: { duke@1: arguments(params); duke@1: } duke@1: duke@1: /** duke@1: * Specifies method parameter types and retrieves "in" and "inout" duke@1: * argument values. duke@1: * Unless it calls the method set_exception, duke@1: * the DIR must call this method exactly once, even if the duke@1: * method signature contains no parameters. Once the method duke@1: * arguments or set_exception duke@1: * has been called, calling arguments on the same duke@1: * ServerRequest object duke@1: * will result in a BAD_INV_ORDER system exception. duke@1: * The DIR must pass in to the method arguments duke@1: * an NVList initialized with TypeCodes and Flags duke@1: * describing the parameter types for the operation, in the order in which duke@1: * they appear in the IDL specification (left to right). A duke@1: * potentially-different NVList will be returned from duke@1: * arguments, with the duke@1: * "in" and "inout" argument values supplied. If it does not call duke@1: * the method set_exception, duke@1: * the DIR must supply the returned NVList with return duke@1: * values for any "out" arguments before returning, and it may also change duke@1: * the return values for any "inout" arguments. duke@1: * duke@1: * @param args the arguments of the method, in the duke@1: * form of an NVList duke@1: * @see CORBA duke@1: * package comments for unimplemented features duke@1: */ duke@1: public void arguments(org.omg.CORBA.NVList args) { duke@1: throw new org.omg.CORBA.NO_IMPLEMENT(); duke@1: } duke@1: duke@1: duke@1: duke@1: /** duke@1: * Specifies any return value for the call. duke@1: *

duke@1: * Note that this method is deprecated; use the method duke@1: * set_result in its place. duke@1: *

duke@1: * Unless the method duke@1: * set_exception is called, if the invoked method duke@1: * has a non-void result type, the method set_result duke@1: * must be called exactly once before the DIR returns. duke@1: * If the operation has a void result type, the method duke@1: * set_result may optionally be duke@1: * called once with an Any object whose type is duke@1: * tk_void. Calling the method set_result before duke@1: * the method arguments has been called or after duke@1: * the method set_result or set_exception has been duke@1: * called will result in a BAD_INV_ORDER exception. Calling the method duke@1: * set_result without having previously called duke@1: * the method ctx when the IDL operation contains a duke@1: * context expression, or when the NVList passed to arguments did not duke@1: * describe all parameters passed by the client, may result in a MARSHAL duke@1: * system exception. duke@1: * duke@1: * @param any an Any object containing the return value to be set duke@1: * @deprecated use the method set_result duke@1: */ duke@1: @Deprecated duke@1: public void result(Any any) duke@1: { duke@1: set_result(any); duke@1: } duke@1: duke@1: duke@1: /** duke@1: * Throws an org.omg.CORBA.NO_IMPLEMENT exception. duke@1: *

duke@1: * Specifies any return value for the call. Unless the method duke@1: * set_exception is called, if the invoked method duke@1: * has a non-void result type, the method set_result duke@1: * must be called exactly once before the DIR returns. duke@1: * If the operation has a void result type, the method duke@1: * set_result may optionally be duke@1: * called once with an Any object whose type is duke@1: * tk_void. Calling the method set_result before duke@1: * the method arguments has been called or after duke@1: * the method set_result or set_exception has been duke@1: * called will result in a BAD_INV_ORDER exception. Calling the method duke@1: * set_result without having previously called duke@1: * the method ctx when the IDL operation contains a duke@1: * context expression, or when the NVList passed to arguments did not duke@1: * describe all parameters passed by the client, may result in a MARSHAL duke@1: * system exception. duke@1: * duke@1: * @param any an Any object containing the return value to be set duke@1: * @see CORBA duke@1: * package comments for unimplemented features duke@1: */ duke@1: public void set_result(org.omg.CORBA.Any any) duke@1: { duke@1: throw new org.omg.CORBA.NO_IMPLEMENT(); duke@1: } duke@1: duke@1: duke@1: /** duke@1: * The DIR may call set_exception at any time to return an exception to the duke@1: * client. The Any passed to set_exception must contain either a system duke@1: * exception or a user exception specified in the raises expression duke@1: * of the invoked operation's IDL definition. Passing in an Any that does duke@1: * not duke@1: * contain an exception will result in a BAD_PARAM system exception. Passing duke@1: * in an unlisted user exception will result in either the DIR receiving a duke@1: * BAD_PARAM system exception or in the client receiving an duke@1: * UNKNOWN_EXCEPTION system exception. duke@1: * duke@1: * @param any the Any object containing the exception duke@1: * @deprecated use set_exception() duke@1: */ duke@1: @Deprecated duke@1: public void except(Any any) duke@1: { duke@1: set_exception(any); duke@1: } duke@1: duke@1: /** duke@1: * Throws an org.omg.CORBA.NO_IMPLEMENT exception. duke@1: *

duke@1: * Returns the given exception to the client. This method duke@1: * is invoked by the DIR, which may call it at any time. duke@1: * The Any object passed to this method must duke@1: * contain either a system duke@1: * exception or one of the user exceptions specified in the duke@1: * invoked operation's IDL definition. Passing in an duke@1: * Any object that does not contain an exception duke@1: * will cause a BAD_PARAM system exception to be thrown. Passing duke@1: * in an unlisted user exception will result in either the DIR receiving a duke@1: * BAD_PARAM system exception or in the client receiving an duke@1: * UNKNOWN_EXCEPTION system exception. duke@1: * duke@1: * @param any the Any object containing the exception duke@1: * @exception BAD_PARAM if the given Any object does not duke@1: * contain an exception or the exception is an duke@1: * unlisted user exception duke@1: * @exception UNKNOWN_EXCEPTION if the given exception is an unlisted duke@1: * user exception and the DIR did not duke@1: * receive a BAD_PARAM exception duke@1: * @see CORBA duke@1: * package comments for unimplemented features duke@1: */ duke@1: public void set_exception(Any any) duke@1: { duke@1: throw new org.omg.CORBA.NO_IMPLEMENT(); duke@1: } duke@1: duke@1: /** duke@1: * Returns the context information specified in IDL for the operation duke@1: * when the operation is not an attribute access and the operation's IDL duke@1: * definition contains a context expression; otherwise it returns duke@1: * a nil Context reference. Calling the method duke@1: * ctx before the method arguments has duke@1: * been called or after the method ctx, duke@1: * set_result, or set_exception duke@1: * has been called will result in a duke@1: * BAD_INV_ORDER system exception. 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: * @exception BAD_INV_ORDER if (1) the method ctx is called duke@1: * before the method arguments or duke@1: * (2) the method ctx is called duke@1: * after calling set_result or duke@1: * set_exception duke@1: */ duke@1: public abstract Context ctx(); duke@1: duke@1: }