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