001: /*
002: * Copyright 1996-2004 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package org.omg.CORBA;
027:
028: /**
029: * An object that captures the explicit state of a request
030: * for the Dynamic Skeleton Interface (DSI). This class, the
031: * cornerstone of the DSI, is analogous to the <code>Request</code>
032: * object in the DII.
033: * <P>
034: * The ORB is responsible for creating this embodiment of a request,
035: * and delivering it to a Dynamic Implementation Routine (DIR).
036: * A dynamic servant (a DIR) is created by implementing the
037: * <code>DynamicImplementation</code> class,
038: * which has a single <code>invoke</code> method. This method accepts a
039: * <code>ServerRequest</code> object.
040: *
041: * The abstract class <code>ServerRequest</code> defines
042: * methods for accessing the
043: * method name, the arguments and the context of the request, as
044: * well as methods for setting the result of the request either as a
045: * return value or an exception. <p>
046: *
047: * A subtlety with accessing the arguments of the request is that the
048: * DIR needs to provide type information about the
049: * expected arguments, since there is no compiled information about
050: * these. This information is provided through an <code>NVList</code>,
051: * which is a list of <code>NamedValue</code> objects.
052: * Each <code>NamedValue</code> object
053: * contains an <code>Any</code> object, which in turn
054: * has a <code>TypeCode</code> object representing the type
055: * of the argument. <p>
056: *
057: * Similarly, type information needs to be provided for the response,
058: * for either the expected result or for an exception, so the methods
059: * <code>result</code> and <code>except</code> take an <code>Any</code>
060: * object as a parameter. <p>
061: *
062: * @see org.omg.CORBA.DynamicImplementation
063: * @see org.omg.CORBA.NVList
064: * @see org.omg.CORBA.NamedValue
065: *
066: * @version 1.15 09/09/97
067: */
068:
069: public abstract class ServerRequest {
070:
071: /**
072: * Retrieves the name of the operation being
073: * invoked. According to OMG IDL's rules, these names must be unique
074: * among all operations supported by this object's "most-derived"
075: * interface. Note that the operation names for getting and setting
076: * attributes are <code>_get_<attribute_name></code>
077: * and <code>_set_<attribute_name></code>,
078: * respectively.
079: *
080: * @return the name of the operation to be invoked
081: * @deprecated use operation()
082: */
083: @Deprecated
084: public String op_name() {
085: return operation();
086: }
087:
088: /**
089: * Throws an <code>org.omg.CORBA.NO_IMPLEMENT</code> exception.
090: * <P>
091: * Retrieves the name of the operation being
092: * invoked. According to OMG IDL's rules, these names must be unique
093: * among all operations supported by this object's "most-derived"
094: * interface. Note that the operation names for getting and setting
095: * attributes are <code>_get_<attribute_name></code>
096: * and <code>_set_<attribute_name></code>,
097: * respectively.
098: *
099: * @return the name of the operation to be invoked
100: * @see <a href="package-summary.html#unimpl"><code>CORBA</code>
101: * package comments for unimplemented features</a>
102: */
103: public String operation() {
104: throw new org.omg.CORBA.NO_IMPLEMENT();
105: }
106:
107: /**
108: * Specifies method parameter types and retrieves "in" and "inout"
109: * argument values.
110: * <P>
111: * Note that this method is deprecated; use the method
112: * <code>arguments</code> in its place.
113: * <P>
114: * Unless it calls the method <code>set_exception</code>,
115: * the DIR must call this method exactly once, even if the
116: * method signature contains no parameters. Once the method <code>
117: * arguments</code> or <code>set_exception</code>
118: * has been called, calling <code>arguments</code> on the same
119: * <code>ServerRequest</code> object
120: * will result in a <code>BAD_INV_ORDER</code> system exception.
121: * The DIR must pass in to the method <code>arguments</code>
122: * an NVList initialized with TypeCodes and Flags
123: * describing the parameter types for the operation, in the order in which
124: * they appear in the IDL specification (left to right). A
125: * potentially-different NVList will be returned from
126: * <code>arguments</code>, with the
127: * "in" and "inout" argument values supplied. If it does not call
128: * the method <code>set_exception</code>,
129: * the DIR must supply the returned NVList with return
130: * values for any "out" arguments before returning, and may also change
131: * the return values for any "inout" arguments.
132: *
133: * @param params the arguments of the method, in the
134: * form of an <code>NVList</code> object
135: * @deprecated use the method <code>arguments</code>
136: */
137: @Deprecated
138: public void params(NVList params) {
139: arguments(params);
140: }
141:
142: /**
143: * Specifies method parameter types and retrieves "in" and "inout"
144: * argument values.
145: * Unless it calls the method <code>set_exception</code>,
146: * the DIR must call this method exactly once, even if the
147: * method signature contains no parameters. Once the method <code>
148: * arguments</code> or <code>set_exception</code>
149: * has been called, calling <code>arguments</code> on the same
150: * <code>ServerRequest</code> object
151: * will result in a <code>BAD_INV_ORDER</code> system exception.
152: * The DIR must pass in to the method <code>arguments</code>
153: * an NVList initialized with TypeCodes and Flags
154: * describing the parameter types for the operation, in the order in which
155: * they appear in the IDL specification (left to right). A
156: * potentially-different NVList will be returned from
157: * <code>arguments</code>, with the
158: * "in" and "inout" argument values supplied. If it does not call
159: * the method <code>set_exception</code>,
160: * the DIR must supply the returned NVList with return
161: * values for any "out" arguments before returning, and it may also change
162: * the return values for any "inout" arguments.
163: *
164: * @param args the arguments of the method, in the
165: * form of an NVList
166: * @see <a href="package-summary.html#unimpl"><code>CORBA</code>
167: * package comments for unimplemented features</a>
168: */
169: public void arguments(org.omg.CORBA.NVList args) {
170: throw new org.omg.CORBA.NO_IMPLEMENT();
171: }
172:
173: /**
174: * Specifies any return value for the call.
175: * <P>
176: * Note that this method is deprecated; use the method
177: * <code>set_result</code> in its place.
178: * <P>
179: * Unless the method
180: * <code>set_exception</code> is called, if the invoked method
181: * has a non-void result type, the method <code>set_result</code>
182: * must be called exactly once before the DIR returns.
183: * If the operation has a void result type, the method
184: * <code>set_result</code> may optionally be
185: * called once with an <code>Any</code> object whose type is
186: * <code>tk_void</code>. Calling the method <code>set_result</code> before
187: * the method <code>arguments</code> has been called or after
188: * the method <code>set_result</code> or <code>set_exception</code> has been
189: * called will result in a BAD_INV_ORDER exception. Calling the method
190: * <code>set_result</code> without having previously called
191: * the method <code>ctx</code> when the IDL operation contains a
192: * context expression, or when the NVList passed to arguments did not
193: * describe all parameters passed by the client, may result in a MARSHAL
194: * system exception.
195: *
196: * @param any an <code>Any</code> object containing the return value to be set
197: * @deprecated use the method <code>set_result</code>
198: */
199: @Deprecated
200: public void result(Any any) {
201: set_result(any);
202: }
203:
204: /**
205: * Throws an <code>org.omg.CORBA.NO_IMPLEMENT</code> exception.
206: * <P>
207: * Specifies any return value for the call. Unless the method
208: * <code>set_exception</code> is called, if the invoked method
209: * has a non-void result type, the method <code>set_result</code>
210: * must be called exactly once before the DIR returns.
211: * If the operation has a void result type, the method
212: * <code>set_result</code> may optionally be
213: * called once with an <code>Any</code> object whose type is
214: * <code>tk_void</code>. Calling the method <code>set_result</code> before
215: * the method <code>arguments</code> has been called or after
216: * the method <code>set_result</code> or <code>set_exception</code> has been
217: * called will result in a BAD_INV_ORDER exception. Calling the method
218: * <code>set_result</code> without having previously called
219: * the method <code>ctx</code> when the IDL operation contains a
220: * context expression, or when the NVList passed to arguments did not
221: * describe all parameters passed by the client, may result in a MARSHAL
222: * system exception.
223: *
224: * @param any an <code>Any</code> object containing the return value to be set
225: * @see <a href="package-summary.html#unimpl"><code>CORBA</code>
226: * package comments for unimplemented features</a>
227: */
228: public void set_result(org.omg.CORBA.Any any) {
229: throw new org.omg.CORBA.NO_IMPLEMENT();
230: }
231:
232: /**
233: * The DIR may call set_exception at any time to return an exception to the
234: * client. The Any passed to set_exception must contain either a system
235: * exception or a user exception specified in the raises expression
236: * of the invoked operation's IDL definition. Passing in an Any that does
237: * not
238: * contain an exception will result in a BAD_PARAM system exception. Passing
239: * in an unlisted user exception will result in either the DIR receiving a
240: * BAD_PARAM system exception or in the client receiving an
241: * UNKNOWN_EXCEPTION system exception.
242: *
243: * @param any the <code>Any</code> object containing the exception
244: * @deprecated use set_exception()
245: */
246: @Deprecated
247: public void except(Any any) {
248: set_exception(any);
249: }
250:
251: /**
252: * Throws an <code>org.omg.CORBA.NO_IMPLEMENT</code> exception.
253: * <P>
254: * Returns the given exception to the client. This method
255: * is invoked by the DIR, which may call it at any time.
256: * The <code>Any</code> object passed to this method must
257: * contain either a system
258: * exception or one of the user exceptions specified in the
259: * invoked operation's IDL definition. Passing in an
260: * <code>Any</code> object that does not contain an exception
261: * will cause a BAD_PARAM system exception to be thrown. Passing
262: * in an unlisted user exception will result in either the DIR receiving a
263: * BAD_PARAM system exception or in the client receiving an
264: * UNKNOWN_EXCEPTION system exception.
265: *
266: * @param any the <code>Any</code> object containing the exception
267: * @exception BAD_PARAM if the given <code>Any</code> object does not
268: * contain an exception or the exception is an
269: * unlisted user exception
270: * @exception UNKNOWN_EXCEPTION if the given exception is an unlisted
271: * user exception and the DIR did not
272: * receive a BAD_PARAM exception
273: * @see <a href="package-summary.html#unimpl"><code>CORBA</code>
274: * package comments for unimplemented features</a>
275: */
276: public void set_exception(Any any) {
277: throw new org.omg.CORBA.NO_IMPLEMENT();
278: }
279:
280: /**
281: * Returns the context information specified in IDL for the operation
282: * when the operation is not an attribute access and the operation's IDL
283: * definition contains a context expression; otherwise it returns
284: * a nil <code>Context</code> reference. Calling the method
285: * <code>ctx</code> before the method <code>arguments</code> has
286: * been called or after the method <code>ctx</code>,
287: * <code>set_result</code>, or <code>set_exception</code>
288: * has been called will result in a
289: * BAD_INV_ORDER system exception.
290: *
291: * @return the context object that is to be used
292: * to resolve any context strings whose
293: * values need to be sent with the invocation.
294: * @exception BAD_INV_ORDER if (1) the method <code>ctx</code> is called
295: * before the method <code>arguments</code> or
296: * (2) the method <code>ctx</code> is called
297: * after calling <code>set_result</code> or
298: * <code>set_exception</code>
299: */
300: public abstract Context ctx();
301:
302: }
|