| Frames | No Frames |
1: /* UtilDelegate.java -- 2: Copyright (C) 2002, 2005 Free Software Foundation, Inc. 3: 4: This file is part of GNU Classpath. 5: 6: GNU Classpath is free software; you can redistribute it and/or modify 7: it under the terms of the GNU General Public License as published by 8: the Free Software Foundation; either version 2, or (at your option) 9: any later version. 10: 11: GNU Classpath is distributed in the hope that it will be useful, but 12: WITHOUT ANY WARRANTY; without even the implied warranty of 13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14: General Public License for more details. 15: 16: You should have received a copy of the GNU General Public License 17: along with GNU Classpath; see the file COPYING. If not, write to the 18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19: 02110-1301 USA. 20: 21: Linking this library statically or dynamically with other modules is 22: making a combined work based on this library. Thus, the terms and 23: conditions of the GNU General Public License cover the whole 24: combination. 25: 26: As a special exception, the copyright holders of this library give you 27: permission to link this library with independent modules to produce an 28: executable, regardless of the license terms of these independent 29: modules, and to copy and distribute the resulting executable under 30: terms of your choice, provided that you also meet, for each linked 31: independent module, the terms and conditions of the license of that 32: module. An independent module is a module which is not derived from 33: or based on this library. If you modify this library, you may extend 34: this exception to your version of the library, but you are not 35: obligated to do so. If you do not wish to do so, delete this 36: exception statement from your version. */ 37: 38: 39: package javax.rmi.CORBA; 40: 41: import org.omg.CORBA.Any; 42: import org.omg.CORBA.BAD_PARAM; 43: import org.omg.CORBA.COMM_FAILURE; 44: import org.omg.CORBA.CompletionStatus; 45: import org.omg.CORBA.INVALID_TRANSACTION; 46: import org.omg.CORBA.INV_OBJREF; 47: import org.omg.CORBA.MARSHAL; 48: import org.omg.CORBA.NO_PERMISSION; 49: import org.omg.CORBA.OBJECT_NOT_EXIST; 50: import org.omg.CORBA.OMGVMCID; 51: import org.omg.CORBA.ORB; 52: import org.omg.CORBA.SystemException; 53: import org.omg.CORBA.TRANSACTION_REQUIRED; 54: import org.omg.CORBA.TRANSACTION_ROLLEDBACK; 55: import org.omg.CORBA.TypeCode; 56: import org.omg.CORBA.portable.InputStream; 57: import org.omg.CORBA.portable.OutputStream; 58: 59: import java.rmi.AccessException; 60: import java.rmi.MarshalException; 61: import java.rmi.NoSuchObjectException; 62: import java.rmi.Remote; 63: import java.rmi.RemoteException; 64: import java.rmi.ServerError; 65: import java.rmi.ServerException; 66: import java.rmi.UnexpectedException; 67: 68: import javax.transaction.InvalidTransactionException; 69: import javax.transaction.TransactionRequiredException; 70: import javax.transaction.TransactionRolledbackException; 71: 72: /** 73: * A delegate, implementing the functionality, provided by the {@link Util}. 74: * 75: * The default delegate can be altered by setting the system property 76: * "javax.rmi.CORBA.UtilClass" to the name of the alternative class that must 77: * implement this interface. 78: * 79: * @author Audrius Meskauskas (AudriusA@Bioinformatics.org) 80: */ 81: public interface UtilDelegate 82: { 83: /** 84: * Used by local stubs to create a copy of the object. 85: */ 86: Object copyObject(Object obj, ORB orb) 87: throws RemoteException; 88: 89: /** 90: * Used by local stubs to create a multiple copies of the object, preserving 91: * sharing accross the parameters if necessary. 92: */ 93: Object[] copyObjects(Object[] obj, ORB orb) 94: throws RemoteException; 95: 96: /** 97: * Get the value handler that Serializes Java objects to and from CDR (GIOP) 98: * streams. 99: */ 100: ValueHandler createValueHandler(); 101: 102: String getCodebase(Class clz); 103: 104: /** 105: * Checks if the given stub is local. 106: */ 107: boolean isLocal(Stub stub) 108: throws RemoteException; 109: 110: Class loadClass(String className, String remoteCodebase, ClassLoader loader) 111: throws ClassNotFoundException; 112: 113: /** 114: * Converts CORBA {@link SystemException} into RMI {@link RemoteException}. 115: * The exception is converted as defined in the following table: 116: * <p> 117: * <table border = "1"> 118: * <tr> 119: * <th>CORBA Exception</th> 120: * <th>RMI Exception</th> 121: * </tr> 122: * <tr> 123: * <td>{@link COMM_FAILURE}</td> 124: * <td>{@link MarshalException}</td> 125: * </tr> 126: * <tr> 127: * <td>{@link INV_OBJREF}</td> 128: * <td>{@link NoSuchObjectException}</td> 129: * </tr> 130: * <tr> 131: * <td>{@link NO_PERMISSION}</td> 132: * <td>{@link AccessException}</td> 133: * </tr> 134: * <tr> 135: * <td>{@link MARSHAL}</td> 136: * <td>{@link MarshalException}</td> 137: * </tr> 138: * <tr> 139: * <td>{@link BAD_PARAM} (all other cases)</td> 140: * <td>{@link MarshalException}</td> 141: * </tr> 142: * <tr> 143: * <td>{@link OBJECT_NOT_EXIST}</td> 144: * <td>{@link NoSuchObjectException}</td> 145: * </tr> 146: * <tr> 147: * <td>{@link TRANSACTION_REQUIRED}</td> 148: * <td>{@link TransactionRequiredException}</td> 149: * </tr> 150: * <tr> 151: * <td>{@link TRANSACTION_ROLLEDBACK}</td> 152: * <td>{@link TransactionRolledbackException}</td> 153: * </tr> 154: * <tr> 155: * <td>{@link INVALID_TRANSACTION}</td> 156: * <td>{@link InvalidTransactionException}</td> 157: * </tr> 158: * <tr> 159: * <td bgcolor="lightgray">Any other {@link SystemException}</td> 160: * <td bgcolor="lightgray">{@link RemoteException}</td> 161: * </tr> 162: * </table> 163: * </p> 164: * <p> 165: * The exception detailed message always consists of 166: * <ol> 167: * <li>the string "CORBA "</li> 168: * <li>the CORBA name of the system exception</li> 169: * <li>single space</li> 170: * <li>the hexadecimal value of the system exception's minor code, preceeded 171: * by 0x (higher bits contain {@link OMGVMCID}).</li> 172: * <li>single space</li> 173: * <li>the {@link CompletionStatus} of the exception: "Yes", "No" or "Maybe".</li> 174: * </ol> 175: * The subsequent content is not part of the official RMI-IIOP standart and is 176: * added for compatibility with Sun's implementation: 177: * <ol> 178: * <li>the phrase "<code>; nested exception is: <i>(line feed)(tab)</i></code>"</li> 179: * <li>the full name of the mapped SystemException, as returned by 180: * Class.getName().</li> 181: * <li>the ": ". 182: * <li>the value, returned by .getMessage() of the passed parameter.</li> 183: * </ol> 184: * <p> 185: * For instance, if the Internet connection was refused: 186: * </p><p> 187: * <code>CORBA COMM_FAILURE 0x535500C9 No</code> 188: * </p><p> 189: * The original CORBA exception is set as the cause of the RemoteException 190: * being created. 191: * </p> 192: */ 193: RemoteException mapSystemException(SystemException ex); 194: 195: /** 196: * Get the Tie that handles invocations on the given target. The target/Tie 197: * pair must be previously registered using {@link #registerTarget}. 198: * 199: * @return the Tie, or null if no such is known. 200: */ 201: Tie getTie(Remote target); 202: 203: /** 204: * Register the Tie-target pair. 205: */ 206: void registerTarget(Tie tie, Remote target); 207: 208: /** 209: * Deactivate the associated Tie, if it is found and is not connected to other 210: * registered targets. 211: */ 212: void unexportObject(Remote target) 213: throws NoSuchObjectException; 214: 215: /** 216: * Converts the exception that was thrown by the implementation method on a 217: * server side into RemoteException that can be transferred and re-thrown on a 218: * client side. The method converts exceptions as defined in the following 219: * table: <table border = "1"> 220: * <tr> 221: * <th>Exception to map (or subclass)</th> 222: * <th>Maps into</th> 223: * </tr> 224: * <tr> 225: * <td>{@link Error}</td> 226: * <td>{@link ServerError}</td> 227: * </tr> 228: * <tr> 229: * <td>{@link RemoteException}</td> 230: * <td>{@link ServerException}</td> 231: * </tr> 232: * <tr> 233: * <td>{@link SystemException}</td> 234: * <td>wrapException({@link #mapSystemException})</td> 235: * </tr> 236: * <tr> 237: * <td>{@link RuntimeException}</td> 238: * <td><b>rethrows</b></td> 239: * </tr> 240: * <tr> 241: * <td>Any other exception</td> 242: * <td>{@link UnexpectedException}</td> 243: * </tr> 244: * </table> 245: * 246: * @param e an exception that was thrown on a server side implementation. 247: * 248: * @return the corresponding RemoteException unless it is a RuntimeException. 249: * 250: * @throws RuntimeException the passed exception if it is an instance of 251: * RuntimeException. 252: * 253: * @specnote It is the same behavior, as in Suns implementations 1.4.0-1.5.0. 254: */ 255: RemoteException wrapException(Throwable orig); 256: 257: /** 258: * Write the passed parameter to the output stream as CORBA object. If the 259: * parameter is an instance of Remote and not an instance of Stub, the method 260: * instantiates a suitable Tie, connects the parameter to this Tie and then 261: * connects that Tie to the ORB that is requested from the output stream. Then 262: * the object reference is written to the stream, making remote invocations 263: * possible. This method is used in write_value(..) method group in 264: * {@link org.omg.CORBA_2_3.portable.OutputStream} and also may be called 265: * directly from generated Stubs and Ties. 266: * 267: * @param output a stream to write to, must be 268: * org.omg.CORBA_2_3.portable.OutputStream 269: * @param obj an object to write. 270: */ 271: void writeRemoteObject(OutputStream output, Object obj); 272: 273: /** 274: * Write abstract interface to the CORBA output stream. The write format is 275: * matching CORBA abstract interface. Remotes and CORBA objects are written as 276: * objects, other classes are supposed to be value types and are written as 277: * such. {@link Remote}s are processed as defined in 278: * {@link #writeRemoteObject}. The written data contains discriminator, 279: * defining, that was written. Another method that writes the same content is 280: * {@link org.omg.CORBA_2_3.portable.OutputStream#write_abstract_interface(java.lang.Object)}. 281: * 282: * @param output a stream to write to, must be 283: * {@link org.omg.CORBA_2_3.portable.OutputStream}. 284: * 285: * @param object an object to write, must be CORBA object, Remote 286: */ 287: void writeAbstractObject(OutputStream output, Object object); 288: 289: /** 290: * Write the passed java object to the output stream in the form of the CORBA 291: * {@link Any}. This includes creating an writing the object {@link TypeCode} 292: * first. Such Any can be later read by a non-RMI-IIOP CORBA implementation 293: * and manipulated, for instance, by means, provided in 294: * {@link org.omg.DynamicAny.DynAny}. Depending from the passed value, this 295: * method writes CORBA object, value type or value box. For value types Null 296: * is written with the abstract interface, its typecode having repository id 297: * "IDL:omg.org/CORBA/AbstractBase:1.0" and the empty string name. 298: * 299: * @param output the object to write. 300: * @param object the java object that must be written in the form of the CORBA 301: * {@link Any}. 302: */ 303: void writeAny(OutputStream output, Object object); 304: 305: /** 306: * Read Any from the input stream. 307: */ 308: Object readAny(InputStream input); 309: 310: }