001: /*
002: * Copyright 1997-2002 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: package org.omg.CORBA.portable;
026:
027: import org.omg.CORBA.Request;
028: import org.omg.CORBA.NamedValue;
029: import org.omg.CORBA.NVList;
030: import org.omg.CORBA.Context;
031: import org.omg.CORBA.ContextList;
032: import org.omg.CORBA.ExceptionList;
033: import org.omg.CORBA.TypeCode;
034: import org.omg.CORBA.SystemException;
035:
036: /**
037: * Specifies a portable API for ORB-vendor-specific
038: * implementation of the org.omg.CORBA.Object methods.
039: *
040: * Each stub (proxy) contains a delegate
041: * object, to which all org.omg.CORBA.Object methods are forwarded.
042: * This allows a stub generated by one vendor's ORB to work with the delegate
043: * from another vendor's ORB.
044: *
045: * @see org.omg.CORBA.Object
046: * @author OMG
047: * @version 1.44 05/05/07
048: */
049:
050: public abstract class Delegate {
051:
052: /**
053: * Return an InterfaceDef for the object reference provided.
054: * @param self The object reference whose InterfaceDef needs to be returned
055: * @return the InterfaceDef
056: */
057: public abstract org.omg.CORBA.Object get_interface_def(
058: org.omg.CORBA.Object self);
059:
060: /**
061: * Returns a duplicate of the object reference provided.
062: * @param obj The object reference whose duplicate needs to be returned
063: * @return the duplicate object reference
064: */
065: public abstract org.omg.CORBA.Object duplicate(
066: org.omg.CORBA.Object obj);
067:
068: /**
069: * Releases resources associated with the object reference provided.
070: * @param obj The object reference whose resources need to be released
071: */
072: public abstract void release(org.omg.CORBA.Object obj);
073:
074: /**
075: * Checks if the object reference is an instance of the given interface.
076: * @param obj The object reference to be checked.
077: * @param repository_id The repository identifier of the interface
078: * to check against.
079: * @return true if the object reference supports the interface
080: */
081: public abstract boolean is_a(org.omg.CORBA.Object obj,
082: String repository_id);
083:
084: /**
085: * Determines whether the server object for the object reference has been
086: * destroyed.
087: * @param obj The object reference which delegated to this delegate.
088: * @return true if the ORB knows authoritatively that the server object does
089: * not exist, false otherwise
090: */
091: public abstract boolean non_existent(org.omg.CORBA.Object obj);
092:
093: /**
094: * Determines if the two object references are equivalent.
095: * @param obj The object reference which delegated to this delegate.
096: * @param other The object reference to check equivalence against.
097: * @return true if the objects are CORBA-equivalent.
098: */
099: public abstract boolean is_equivalent(org.omg.CORBA.Object obj,
100: org.omg.CORBA.Object other);
101:
102: /**
103: * Returns an ORB-internal identifier (hashcode) for this object reference.
104: * @param obj The object reference which delegated to this delegate.
105: * @param max specifies an upper bound on the hash value returned by
106: * the ORB.
107: * @return ORB-internal hash identifier for object reference
108: */
109: public abstract int hash(org.omg.CORBA.Object obj, int max);
110:
111: /**
112: * Creates a Request instance for use in the Dynamic Invocation Interface.
113: * @param obj The object reference which delegated to this delegate.
114: * @param operation The name of the operation to be invoked using the
115: * Request instance.
116: * @return the created Request instance
117: */
118: public abstract Request request(org.omg.CORBA.Object obj,
119: String operation);
120:
121: /**
122: * Creates a Request instance for use in the Dynamic Invocation Interface.
123: *
124: * @param obj The object reference which delegated to this delegate.
125: * @param ctx The context to be used.
126: * @param operation The name of the operation to be
127: * invoked.
128: * @param arg_list The arguments to the operation in the
129: * form of an NVList.
130: * @param result A container for the result as a NamedValue.
131: * @return The created Request object.
132: *
133: */
134: public abstract Request create_request(org.omg.CORBA.Object obj,
135: Context ctx, String operation, NVList arg_list,
136: NamedValue result);
137:
138: /**
139: * Creates a Request instance for use in the Dynamic Invocation Interface.
140: *
141: * @param obj The object reference which delegated to this delegate.
142: * @param ctx The context to be used.
143: * @param operation The name of the operation to be
144: * invoked.
145: * @param arg_list The arguments to the operation in the
146: * form of an NVList.
147: * @param result A container for the result as a NamedValue.
148: * @param exclist A list of possible exceptions the
149: * operation can throw.
150: * @param ctxlist A list of context strings that need
151: * to be resolved and sent with the
152: * Request.
153: * @return The created Request object.
154: */
155: public abstract Request create_request(org.omg.CORBA.Object obj,
156: Context ctx, String operation, NVList arg_list,
157: NamedValue result, ExceptionList exclist,
158: ContextList ctxlist);
159:
160: /**
161: * Provides a reference to the orb associated with its parameter.
162: *
163: * @param obj the object reference which delegated to this delegate.
164: * @return the associated orb.
165: * @see <a href="package-summary.html#unimpl"><code>portable</code>
166: * package comments for unimplemented features</a>
167: */
168: public org.omg.CORBA.ORB orb(org.omg.CORBA.Object obj) {
169: throw new org.omg.CORBA.NO_IMPLEMENT();
170: }
171:
172: /**
173: * Returns the <code>Policy</code> object of the specified type
174: * which applies to this object.
175: *
176: * @param self The object reference which delegated to this delegate.
177: * @param policy_type The type of policy to be obtained.
178: * @return A <code>Policy</code> object of the type specified by
179: * the policy_type parameter.
180: * @exception org.omg.CORBA.BAD_PARAM raised when the value of policy type
181: * is not valid either because the specified type is not supported by this
182: * ORB or because a policy object of that type is not associated with this
183: * Object.
184: * @see <a href="package-summary.html#unimpl"><code>portable</code>
185: * package comments for unimplemented features</a>
186: */
187: public org.omg.CORBA.Policy get_policy(org.omg.CORBA.Object self,
188: int policy_type) {
189: throw new org.omg.CORBA.NO_IMPLEMENT();
190: }
191:
192: /**
193: * Retrieves the <code>DomainManagers</code> of this object.
194: * This allows administration services (and applications) to retrieve the
195: * domain managers, and hence the security and other policies applicable
196: * to individual objects that are members of the domain.
197: *
198: * @param self The object reference which delegated to this delegate.
199: * @return The list of immediately enclosing domain managers of this object.
200: * At least one domain manager is always returned in the list since by
201: * default each object is associated with at least one domain manager at
202: * creation.
203: * @see <a href="package-summary.html#unimpl"><code>portable</code>
204: * package comments for unimplemented features</a>
205: */
206: public org.omg.CORBA.DomainManager[] get_domain_managers(
207: org.omg.CORBA.Object self) {
208: throw new org.omg.CORBA.NO_IMPLEMENT();
209: }
210:
211: /**
212: * Associates the policies passed in
213: * with a newly created object reference that it returns. Only certain
214: * policies that pertain to the invocation of an operation at the client
215: * end can be overridden using this operation. Attempts to override any
216: * other policy will result in the raising of the CORBA::NO_PERMISSION
217: * exception.
218: *
219: * @param self The object reference which delegated to this delegate.
220: * @param policies A sequence of references to Policy objects.
221: * @param set_add Indicates whether these policies should be added
222: * onto any otheroverrides that already exist (ADD_OVERRIDE) in
223: * the object reference, or they should be added to a clean
224: * override free object reference (SET_OVERRIDE).
225: * @return A new object reference with the new policies associated with it.
226: *
227: * @see <a href="package-summary.html#unimpl"><code>portable</code>
228: * package comments for unimplemented features</a>
229: */
230: public org.omg.CORBA.Object set_policy_override(
231: org.omg.CORBA.Object self, org.omg.CORBA.Policy[] policies,
232: org.omg.CORBA.SetOverrideType set_add) {
233: throw new org.omg.CORBA.NO_IMPLEMENT();
234: }
235:
236: /**
237: * Returns true if this object is implemented by a local servant.
238: *
239: * @param self The object reference which delegated to this delegate.
240: * @return true only if the servant incarnating this object is located in
241: * this Java VM. Return false if the servant is not local or the ORB
242: * does not support local stubs for this particular servant. The default
243: * behavior of is_local() is to return false.
244: */
245: public boolean is_local(org.omg.CORBA.Object self) {
246: return false;
247: }
248:
249: /**
250: * Returns a Java reference to the servant which should be used for this
251: * request. servant_preinvoke() is invoked by a local stub.
252: * If a ServantObject object is returned, then its servant field
253: * has been set to an object of the expected type (Note: the object may
254: * or may not be the actual servant instance). The local stub may cast
255: * the servant field to the expected type, and then invoke the operation
256: * directly. The ServantRequest object is valid for only one invocation,
257: * and cannot be used for more than one invocation.
258: *
259: * @param self The object reference which delegated to this delegate.
260: *
261: * @param operation a string containing the operation name.
262: * The operation name corresponds to the operation name as it would be
263: * encoded in a GIOP request.
264: *
265: * @param expectedType a Class object representing the expected type of the servant.
266: * The expected type is the Class object associated with the operations
267: * class of the stub's interface (e.g. A stub for an interface Foo,
268: * would pass the Class object for the FooOperations interface).
269: *
270: * @return a ServantObject object.
271: * The method may return a null value if it does not wish to support
272: * this optimization (e.g. due to security, transactions, etc).
273: * The method must return null if the servant is not of the expected type.
274: */
275: public ServantObject servant_preinvoke(org.omg.CORBA.Object self,
276: String operation, Class expectedType) {
277: return null;
278: }
279:
280: /**
281: * servant_postinvoke() is invoked by the local stub after the operation
282: * has been invoked on the local servant.
283: * This method must be called if servant_preinvoke() returned a non-null
284: * value, even if an exception was thrown by the servant's method.
285: * For this reason, the call to servant_postinvoke() should be placed
286: * in a Java finally clause.
287: *
288: * @param self The object reference which delegated to this delegate.
289: *
290: * @param servant the instance of the ServantObject returned from
291: * the servant_preinvoke() method.
292: */
293: public void servant_postinvoke(org.omg.CORBA.Object self,
294: ServantObject servant) {
295: }
296:
297: /**
298: * request is called by a stub to obtain an OutputStream for
299: * marshaling arguments. The stub must supply the operation name,
300: * and indicate if a response is expected (i.e is this a oneway
301: * call).
302: *
303: * @param self The object reference which delegated to this delegate.
304: * @param operation a string containing the operation name.
305: * The operation name corresponds to the operation name as it would be
306: * encoded in a GIOP request.
307: * @param responseExpected false if the operation is a one way operation,
308: * and true otherwise.
309: * @return OutputStream the OutputStream into which request arguments
310: * can be marshaled.
311: * @see <a href="package-summary.html#unimpl"><code>portable</code>
312: * package comments for unimplemented features</a>
313: */
314: public OutputStream request(org.omg.CORBA.Object self,
315: String operation, boolean responseExpected) {
316: throw new org.omg.CORBA.NO_IMPLEMENT();
317: }
318:
319: /**
320: * invoke is called by a stub to invoke an operation. The stub provides an
321: * OutputStream that was previously returned by a request()
322: * call. invoke returns an InputStream which contains the
323: * marshaled reply. If an exception occurs, invoke may throw an
324: * ApplicationException object which contains an InputStream from
325: * which the user exception state may be unmarshaled.
326: *
327: * @param self The object reference which delegated to this delegate.
328: * @param output the OutputStream which contains marshaled arguments
329: * @return input the InputStream from which reply parameters can be
330: * unmarshaled.
331: * @throws ApplicationException thrown when implementation throws
332: * (upon invocation) an exception defined as part of its remote method
333: * definition.
334: * @throws RemarshalException thrown when remarshalling fails.
335: * @see <a href="package-summary.html#unimpl"><code>portable</code>
336: * package comments for unimplemented features</a>
337: */
338: public InputStream invoke(org.omg.CORBA.Object self,
339: OutputStream output) throws ApplicationException,
340: RemarshalException {
341: throw new org.omg.CORBA.NO_IMPLEMENT();
342: }
343:
344: /**
345: * releaseReply may optionally be called by a stub to release a
346: * reply stream back to the ORB when the unmarshaling has
347: * completed. The stub passes the InputStream returned by
348: * invoke() or ApplicationException.getInputStream(). A null
349: * value may also be passed to releaseReply, in which case the
350: * method is a noop.
351: *
352: * @param self The object reference which delegated to this delegate.
353: * @param input the InputStream returned from invoke().
354: * @see <a href="package-summary.html#unimpl"><code>portable</code>
355: * package comments for unimplemented features</a>
356: */
357: public void releaseReply(org.omg.CORBA.Object self,
358: InputStream input) {
359: throw new org.omg.CORBA.NO_IMPLEMENT();
360: }
361:
362: /**
363: * Provides the implementation to override the toString() method
364: * of the delegating CORBA object.
365: *
366: * @param self the object reference that delegated to this delegate
367: * @return a <code>String</code> object that represents the object
368: * reference that delegated to this <code>Delegate</code>
369: * object
370: */
371:
372: public String toString(org.omg.CORBA.Object self) {
373: return self.getClass().getName() + ":" + this .toString();
374: }
375:
376: /**
377: * Provides the implementation to override the hashCode() method
378: * of the delegating CORBA object.
379: *
380: * @param self the object reference that delegated to this delegate
381: * @return an <code>int</code> that represents the hashcode for the
382: * object reference that delegated to this <code>Delegate</code>
383: * object
384: */
385: public int hashCode(org.omg.CORBA.Object self) {
386: return System.identityHashCode(self);
387: }
388:
389: /**
390: * Provides the implementation to override the equals(java.lang.Object obj)
391: * method of the delegating CORBA object.
392: *
393: * @param self the object reference that delegated to this delegate
394: * @param obj the <code>Object</code> with which to compare
395: * @return <code>true</code> if <code>obj</code> equals <code>self</code>;
396: * <code>false</code> otherwise
397: */
398: public boolean equals(org.omg.CORBA.Object self,
399: java.lang.Object obj) {
400: return (self == obj);
401: }
402: }
|