1: /* java.beans.Beans 2: Copyright (C) 1998, 1999, 2004, 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: package java.beans; 39: 40: import gnu.java.beans.DummyAppletStub; 41: import gnu.java.io.ClassLoaderObjectInputStream; 42: 43: import java.applet.Applet; 44: import java.beans.beancontext.BeanContext; 45: import java.io.IOException; 46: import java.io.ObjectInputStream; 47: import java.net.URL; 48: 49: /** 50: * <code>Beans</code> provides some helper methods that allow the basic 51: * operations of Bean-ness. 52: * 53: * @author John Keiser 54: * @author Robert Schuster 55: * 56: * @since 1.1 57: * @status updated to 1.4 58: * 59: */ 60: public class Beans 61: { 62: static boolean designTime = false; 63: static boolean guiAvailable = true; 64: 65: /** 66: * Once again, we have a java.beans class with only 67: * static methods that can be instantiated. When 68: * will the madness end? :) 69: */ 70: public Beans() 71: { 72: // Does intentionally nothing here. 73: } 74: 75: /** Creates a bean. 76: * <p>This is a convenience method that calls <code>instantiate(cl, beanName, null, null)</code>.</p> 77: * 78: * @see instantiate(ClassLoader, String, BeanContext, AppletInitializer) 79: * @param cl ClassLoader to be used or <code>null</code> for the system classloader. 80: * @param beanName Name of a serialized bean or class name. 81: * @return A newly created bean. 82: * @throws IOException If access of an IO resource failed. 83: * @throws ClassNotFoundException If the class name is not known or does not lead to a proper bean class. 84: */ 85: public static Object instantiate(ClassLoader cl, String beanName) 86: throws IOException, ClassNotFoundException 87: { 88: return instantiate(cl, beanName, null, null); 89: } 90: 91: /** Creates a bean. 92: * 93: * <p>This is a convenience method that calls <code>instantiate(cl, beanName, beanContext, null)</code>.</p> 94: * 95: * @see instantiate(ClassLoader, String, BeanContext, AppletInitializer) 96: * @param cl ClassLoader to be used or <code>null</code> for the system classloader. 97: * @param beanName Name of a serialized bean or class name. 98: * @param beanContext Context to which the newly created Bean should be added. 99: * @return A newly created bean. 100: * @throws IOException If access of an IO resource failed. 101: * @throws ClassNotFoundException If the class name is not known or does not lead to a proper bean class. 102: */ 103: public static Object instantiate( 104: ClassLoader cl, 105: String beanName, 106: BeanContext beanContext) 107: throws IOException, ClassNotFoundException 108: { 109: return instantiate(cl, beanName, beanContext, null); 110: } 111: 112: /** Instantiates a bean according to Beans 1.0. 113: * 114: * <p>In Beans 1.0 the instantiation scheme is as follows:</p> 115: * <p>The name should be dot-separated (e.g "place.for.beans.myBean") and indicate either a 116: * serialized object or a class name. In the first case all dots in the name are replaced with 117: * slashes ('/') and ".ser" is appended ("place.for.beans.myBean" becomes "place/for/beans/myBean.ser"). 118: * The bean is then loaded as an application or system resource depending on whether a 119: * <code>ClassLoader</code> was provided.</p> 120: * 121: * <p>If no such resource exists or if it contains no bean the name is interpreted as a class name of 122: * which an instance is then created.</p> 123: * 124: * <p>If a <code>BeanContext</code> instance is available the created bean is added to it.</p> 125: * 126: * <p>If the created Bean is an <code>Applet</code> or subclass and an <code>AppletInitializer</code> 127: * instance is available the applet is initialized and afterwards activated using the initializer. Additionally 128: * every instantiated <code>Applet</code> bean is initialized using the {@link Applet.init} method. 129: * Furthermore every applet gets a default <code>AppletStub</code>. The <code>Applet</code>'s 130: * document base is the location of the ".ser" file if it was deserialized or the location of its class 131: * file if it was instantiated.</p> 132: * 133: * <p>A <code>ClassNotFoundException</code> is not only thrown when a class name was unknown 134: * but even when the class has public no-argument constructor 135: * (<code>IllegalAccessException</code> is wrapped) or an exception is thrown while 136: * invoking such a constructor (causing exception is wrapped).</p> 137: * 138: * @param cl ClassLoader to be used or <code>null</code> for the system classloader. 139: * @param beanName Name of a serialized bean or class name. 140: * @param beanContext Context to which the newly created Bean should be added. 141: * @param initializer The AppletInitializer which is used for initializing <code>Applet</code> beans. 142: * @return A newly created bean. 143: * @throws IOException If access of an IO resource failed. 144: * @throws ClassNotFoundException If the class name is not known or does not lead to a proper bean class. 145: */ 146: public static Object instantiate( 147: ClassLoader cl, 148: String beanName, 149: BeanContext beanContext, 150: AppletInitializer initializer) 151: throws IOException, ClassNotFoundException 152: { 153: Object bean = null; 154: URL beanLocation = null; 155: URL classLocation = null; 156: 157: // Converts bean name into a resource name (eg. "a.b.c" -> "a/b/c"). 158: String resourceName = beanName.replace('.', '/'); 159: 160: /* Tries to get an input stream of the Bean, reading it as a system resource 161: * if no ClassLoader is present or as an application resource if a classloader 162: * is given. 163: */ 164: beanLocation = 165: (cl == null) 166: ? ClassLoader.getSystemResource(resourceName + ".ser") 167: : cl.getResource(resourceName + ".ser"); 168: 169: // Reads the serialized Bean from the returned URL. 170: if (beanLocation != null) 171: { 172: // Deserializes the bean instance. 173: ObjectInputStream ois = 174: (cl == null) 175: ? new ObjectInputStream(beanLocation.openStream()) 176: : new ClassLoaderObjectInputStream( 177: beanLocation.openStream(), 178: cl); 179: 180: bean = ois.readObject(); 181: 182: /* Implementation note: The result of ObjectInputStream.readObject() 183: * may have been null at this point (its a valid value to deserialize) 184: * and we explicitly want to try instantiation in such a case 185: * (this is important for compatibility). 186: */ 187: } 188: 189: // Instantiates the Bean using reflective instantiation if it has not been created yet. 190: if (bean == null) 191: { 192: // Makes sure that the deserialization was NOT done. 193: beanLocation = null; 194: 195: Class beanClass; 196: if (cl == null) 197: { 198: beanClass = Class.forName(beanName); 199: classLocation = 200: ClassLoader.getSystemResource(resourceName + ".class"); 201: } 202: else 203: { 204: beanClass = cl.loadClass(beanName); 205: classLocation = cl.getResource(resourceName + ".class"); 206: } 207: 208: // Instantiates and optionally registers the new bean. 209: try 210: { 211: bean = beanClass.newInstance(); 212: } 213: catch(Exception e) { 214: /* Wraps all kinds of Exceptions in a ClassNotFoundException (this behavior 215: * matches with official >= 1.5, this was different for <=1.4) 216: */ 217: throw new ClassNotFoundException(null, e); 218: } 219: } 220: 221: /* Applet beans are treated in the following way: 222: * - all AppletS get a default AppletStub 223: * - all AppletS are initialized using the AppletInitializer instance (if it is available) 224: * - as every other Bean Applets are added to a BeanContext if one is available 225: * - each instantiated Applet is initialized using Applet.init() (this is not done for deserialized ones) 226: * - finally AppletS get activated using the AppletInitializerS activate-Method 227: * 228: * The order of operations is important for compatibility. 229: */ 230: Applet applet = null; 231: if (bean instanceof Applet) 232: { 233: // Makes a second instanceof call unneccessary (instanceof is expensive). 234: applet = (Applet) bean; 235: 236: /* The AppletStub's code and document base is set as follows: 237: * The code base is always the URL from where the class data originated 238: * (without the package name). 239: * If the Applet was deserialized the document base is the location of 240: * the serialized instance (usually the ".ser" file) otherwise its the URL 241: * from where the class data originated (usually the absolute directory 242: * location of the ".class" file). 243: */ 244: applet.setStub( 245: new DummyAppletStub( 246: applet 247: .getClass() 248: .getProtectionDomain() 249: .getCodeSource() 250: .getLocation(), 251: (beanLocation == null) ? classLocation : beanLocation)); 252: 253: // Runs the Applet's initialization using an AppletInitializer. 254: if (initializer != null) 255: { 256: initializer.initialize(applet, beanContext); 257: } 258: } 259: 260: // Adds the new bean to its BeanContext. 261: if (beanContext != null) 262: { 263: beanContext.add(bean); 264: } 265: 266: if (applet != null) 267: { 268: 269: // Initializes an instantiated (not deserialized) Applet using its own method. 270: if (beanLocation == null) 271: { 272: applet.init(); 273: } 274: 275: // Runs the Applet's activation using an AppletInitializer. 276: if (initializer != null) 277: { 278: initializer.activate(applet); 279: } 280: } 281: 282: return bean; 283: } 284: 285: /** 286: * Returns the Bean as a different class type. 287: * This should be used instead of casting to get a new 288: * type view of a Bean, because in the future there may 289: * be new types of Bean, even Beans spanning multiple 290: * Objects. 291: * 292: * @param bean the Bean to cast. 293: * @param newClass the Class to cast it to. 294: * 295: * @return the Bean as a new view, or if the operation 296: * could not be performed, the Bean itself. 297: */ 298: public static Object getInstanceOf(Object bean, Class<?> newClass) 299: { 300: return bean; 301: } 302: 303: /** 304: * Determines whether the Bean can be cast to a different 305: * class type. 306: * This should be used instead of instanceof to determine 307: * a Bean's castability, because in the future there may 308: * be new types of Bean, even Beans spanning multiple 309: * Objects. 310: * 311: * @param bean the Bean to cast. 312: * @param newClass the Class to cast it to. 313: * 314: * @return whether the Bean can be cast to the class type 315: * in question. 316: */ 317: public static boolean isInstanceOf(Object bean, Class<?> newBeanClass) 318: { 319: return newBeanClass.isInstance(bean); 320: } 321: 322: /** 323: * Returns whether the GUI is available to use. 324: * <p>Defaults to true.</p> 325: * 326: * @return whether the GUI is available to use. 327: */ 328: public static boolean isGuiAvailable() 329: { 330: return guiAvailable; 331: } 332: 333: /** 334: * Returns whether it is design time. Design time means 335: * we are in a RAD tool. 336: * <p>Defaults to false.</p> 337: * 338: * @return whether it is design time. 339: */ 340: public static boolean isDesignTime() 341: { 342: return designTime; 343: } 344: 345: /** 346: * Sets whether the GUI is available to use. 347: * 348: * @param guiAvailable whether the GUI is available to use. 349: */ 350: public static void setGuiAvailable(boolean guiAvailable) 351: throws SecurityException 352: { 353: Beans.guiAvailable = guiAvailable; 354: } 355: 356: /** 357: * Sets whether it is design time. Design time means we 358: * are in a RAD tool. 359: * 360: * @param designTime whether it is design time. 361: */ 362: public static void setDesignTime(boolean designTime) 363: throws SecurityException 364: { 365: Beans.designTime = designTime; 366: } 367: 368: }