[cp-patches] RFC: java.beans.Beans - fixes for 1.4 compatibility

[Robert Schuster]

This patch adds two variants of java.beans.Beans.instantiate which have 
been introduced with 1.4 .For better integration I restructured the 
class a bit (There are 4 versions of instantiate now, all being based on 
the most generic).

Apologies for the rather unreadable patch. This one has been lying on my 
HD for quite a while I swear to make smaller upgrades in the future.

cu
Robert

Index: gnu/java/beans/DummyAppletContext.java
===================================================================
RCS file: gnu/java/beans/DummyAppletContext.java
diff -N gnu/java/beans/DummyAppletContext.java
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ gnu/java/beans/DummyAppletContext.java      18 Dec 2004 23:10:18 -0000
@@ -0,0 +1,199 @@
+/* gnu.java.beans.DummyAppletContext
+   Copyright (C) 2004 Free Software Foundation, Inc.
+
+This file is part of GNU Classpath.
+
+GNU Classpath is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option)
+any later version.
+
+GNU Classpath is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GNU Classpath; see the file COPYING.  If not, write to the
+Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+02111-1307 USA.
+
+Linking this library statically or dynamically with other modules is
+making a combined work based on this library.  Thus, the terms and
+conditions of the GNU General Public License cover the whole
+combination.
+
+As a special exception, the copyright holders of this library give you
+permission to link this library with independent modules to produce an
+executable, regardless of the license terms of these independent
+modules, and to copy and distribute the resulting executable under
+terms of your choice, provided that you also meet, for each linked
+independent module, the terms and conditions of the license of that
+module.  An independent module is a module which is not derived from
+or based on this library.  If you modify this library, you may extend
+this exception to your version of the library, but you are not
+obligated to do so.  If you do not wish to do so, delete this
+exception statement from your version. */
+
+
+package gnu.java.beans;
+
+import java.applet.Applet;
+import java.applet.AppletContext;
+import java.applet.AudioClip;
+import java.awt.Image;
+import java.awt.Toolkit;
+import java.io.IOException;
+import java.io.InputStream;
+import java.net.URL;
+import java.util.Collections;
+import java.util.Enumeration;
+import java.util.Iterator;
+
+/** A placeholder <code>AppletContext</code> implementation that does nothing.
+ *
+ * <p>This is the default implementation for GNU Classpath and is used for 
<code>Applet</code>
+ * beans being created with address@hidden java.beans.Beans.instantiate}.</p>
+ * <p>It has no functionality in order to allow it to be used without any 
dependencies
+ * (e.g. sound, network access, ...).</p>
+ *
+ * @author Robert Schuster
+ */
+class DummyAppletContext implements AppletContext
+{
+  private static final Enumeration EMPTY_ENUMERATION = 
Collections.enumeration(Collections.EMPTY_SET);
+  private static final AudioClip DUMMY_CLIP = new DummyAudioClip();
+
+  DummyAppletContext()
+  {
+  }
+
+  /** Implementation is VM neutral and returns a dummy address@hidden 
AudioClip} instance
+   * for every URL that returns a non-<code>null</code> object on
+   * <code>URL.openConnection()</code>.
+   *
+   * FIXME: When Java Sound API (javax.sound) is included in Classpath or URL 
is able to handle
+   * sampled sound this should be adjusted.
+   *
+   * @see java.applet.AppletContext#getAudioClip(java.net.URL)
+   */
+  public AudioClip getAudioClip(URL url)
+  {
+    try
+      {
+       return (url.openConnection() != null ? DUMMY_CLIP : null);
+      }
+    catch (IOException ioe)
+      {
+       return null;
+      }
+  }
+
+  /** Loads the <code>Image</code> instance by delegating to
+   * address@hidden java.awt.Toolkit.createImage(URL) }.
+   *
+   * @see java.applet.AppletContext#getImage(java.net.URL)
+   * @see java.awt.Toolkit#createImage(java.net.URL)
+   */
+  public Image getImage(URL url)
+  {
+    return Toolkit.getDefaultToolkit().createImage(url);
+  }
+
+  /** Returns <code>null</code> for every argument.
+   *
+   * @see java.applet.AppletContext#getApplet(java.lang.String)
+   */
+  public Applet getApplet(String name)
+  {
+    return null;
+  }
+
+  /** Returns always an empty <code>Enumeration</code>.
+   *
+   * @see java.applet.AppletContext#getApplets()
+   */
+  public Enumeration getApplets()
+  {
+    return EMPTY_ENUMERATION;
+  }
+
+  /** Does nothing.
+   *
+   * @see java.applet.AppletContext#showDocument(java.net.URL)
+   */
+  public void showDocument(URL url)
+  {
+  }
+
+  /** Does nothing.
+   *
+   * @see java.applet.AppletContext#showDocument(java.net.URL, 
java.lang.String)
+   */
+  public void showDocument(URL url, String target)
+  {
+  }
+
+  /** Does nothing.
+   *
+   * @see java.applet.AppletContext#showStatus(java.lang.String)
+   */
+  public void showStatus(String message)
+  {
+  }
+
+  /** Does nothing.
+   *
+   * @see java.applet.AppletContext#setStream(java.lang.String, 
java.io.InputStream)
+   */
+  public void setStream(String key, InputStream stream)
+    throws IOException
+  {
+    throw new IOException("Dummy implementation imposes zero InputStream 
associations.");
+  }
+
+  /** Returns <code>null</code> for every argument.
+   *
+   * @see java.applet.AppletContext#getStream(java.lang.String)
+   */
+  public InputStream getStream(String key)
+  {
+    return null;
+  }
+
+  /** Returns always an empty iterator.
+   *
+   * @see java.applet.AppletContext#getStreamKeys()
+   */
+  public Iterator getStreamKeys()
+  {
+    return Collections.EMPTY_SET.iterator();
+  }
+
+  /** Dummy <code>AudioClip</code> implementation that does nothing but
+   * preventing <code>NullPointerException</code>S being thrown in programs
+   * that expect a valid <code>AudioClip</code> instance to be returned by
+   * their Applet.
+   *
+   * @author Robert Schuster
+   */
+  static class DummyAudioClip implements AudioClip
+  {
+    public void play()
+    {
+    }
+
+    public void stop()
+    {
+    }
+
+    public void loop()
+    {
+    }
+
+    public String toString()
+    {
+      return "DummyAudioClip never plays anything - implement javax.sound and 
make us happy :)";
+    }
+  }
+}
Index: gnu/java/beans/DummyAppletStub.java
===================================================================
RCS file: gnu/java/beans/DummyAppletStub.java
diff -N gnu/java/beans/DummyAppletStub.java
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ gnu/java/beans/DummyAppletStub.java 18 Dec 2004 23:10:18 -0000
@@ -0,0 +1,115 @@
+/* gnu.java.beans.DummyAppletStub
+   Copyright (C) 2004 Free Software Foundation, Inc.
+
+This file is part of GNU Classpath.
+
+GNU Classpath is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option)
+any later version.
+
+GNU Classpath is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GNU Classpath; see the file COPYING.  If not, write to the
+Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+02111-1307 USA.
+
+Linking this library statically or dynamically with other modules is
+making a combined work based on this library.  Thus, the terms and
+conditions of the GNU General Public License cover the whole
+combination.
+
+As a special exception, the copyright holders of this library give you
+permission to link this library with independent modules to produce an
+executable, regardless of the license terms of these independent
+modules, and to copy and distribute the resulting executable under
+terms of your choice, provided that you also meet, for each linked
+independent module, the terms and conditions of the license of that
+module.  An independent module is a module which is not derived from
+or based on this library.  If you modify this library, you may extend
+this exception to your version of the library, but you are not
+obligated to do so.  If you do not wish to do so, delete this
+exception statement from your version. */
+
+
+package gnu.java.beans;
+
+import java.applet.AppletContext;
+import java.applet.AppletStub;
+import java.net.URL;
+
+/** Placeholder implementation of <code>AppletStub</code> providing no 
functionality.
+ * <p>This class is used for <code>Applet</code> being created with
+ * address@hidden java.beans.Bean.instantiate}.</p>
+ *
+ * @author Robert Schuster
+ */
+public class DummyAppletStub implements AppletStub
+{
+  private URL documentBase;
+  private URL codeBase;
+  private DummyAppletContext context;
+
+  public DummyAppletStub(URL newCodeBase, URL newDocumentBase)
+  {
+    codeBase = newCodeBase;
+    documentBase = newDocumentBase;
+
+    context = new DummyAppletContext();
+  }
+
+  /** Returns always <code>true</code>.
+   *
+   * @see java.applet.AppletStub#isActive()
+   */
+  public boolean isActive()
+  {
+    return true;
+  }
+
+  /**
+   * @see java.applet.AppletStub#getDocumentBase()
+   */
+  public URL getDocumentBase()
+  {
+    return documentBase;
+  }
+
+  /**
+   * @see java.applet.AppletStub#getCodeBase()
+   */
+  public URL getCodeBase()
+  {
+    return codeBase;
+  }
+
+  /** Implementation returns <code>null</code> for every parameter name.
+   *
+   * @see java.applet.AppletStub#getParameter(java.lang.String)
+   */
+  public String getParameter(String name)
+  {
+    return null;
+  }
+
+  /** Returns a non-functional context instance.
+   *
+   * @see java.applet.AppletStub#getAppletContext()
+   */
+  public AppletContext getAppletContext()
+  {
+    return context;
+  }
+
+  /** Does nothing.
+   *
+   * @see java.applet.AppletStub#appletResize(int, int)
+   */
+  public void appletResize(int width, int height)
+  {
+  }
+}
Index: java/beans/Beans.java
===================================================================
RCS file: /cvsroot/classpath/classpath/java/beans/Beans.java,v
retrieving revision 1.11
diff -u -r1.11 Beans.java
--- java/beans/Beans.java       17 Nov 2004 08:20:48 -0000      1.11
+++ java/beans/Beans.java       18 Dec 2004 23:10:23 -0000
@@ -1,5 +1,5 @@
 /* java.beans.Beans
-   Copyright (C) 1998, 1999 Free Software Foundation, Inc.
+   Copyright (C) 1998, 1999, 2004 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation; either version 2, or (at your option)
 any later version.
- 
+
 GNU Classpath is distributed in the hope that it will be useful, but
 WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
@@ -38,20 +38,24 @@
 
 package java.beans;
 
+import gnu.java.beans.DummyAppletStub;
 import gnu.java.io.ClassLoaderObjectInputStream;
 
 import java.applet.Applet;
+import java.beans.beancontext.BeanContext;
 import java.io.IOException;
-import java.io.InputStream;
 import java.io.ObjectInputStream;
+import java.net.URL;
 
 /**
  * <code>Beans</code> provides some helper methods that allow the basic
  * operations of Bean-ness.
  *
  * @author John Keiser
+ * @author Robert Schuster
+ *
  * @since 1.1
- * @version 1.1.0, 29 Jul 1998
+ * @status updated to 1.4
  *
  */
 public class Beans
@@ -66,119 +70,208 @@
    */
   public Beans()
   {
-    // Do nothing here.
+    // Does intentionally nothing here.
   }
 
-  /**
-   * Allows you to instantiate a Bean.  This method takes
-   * a ClassLoader from which to read the Bean and the
-   * name of the Bean.<P>
-   *
-   * The Bean name should be a dotted name, like a class.
-   * It can represent several things.  Beans will search
-   * for the Bean using the name like this:<P>
-   * <OL>
-   * <LI>Searches for a serialized instance of the Bean
-   * using getResource(), mangling the Bean name by
-   * replacing the dots with slashes and appending .ser
-   * (for example, gnu.beans.BlahDeBlah would cause
-   * Beans to search for gnu/beans/BlahDeBlah.ser using
-   * getResource()).</LI>
-   * <LI>Searches for the Bean class using the beanName,
-   * and then instantiates it with the no-arg constructor.
-   * At that point, if it is an Applet, it provides it
-   * with AppletContext and AppletStub, and then calls
-   * init().</LI>
-   * </OL>
-   *
-   * @param cl the ClassLoader to use, or <CODE>null</CODE>
-   *        to use the default ClassLoader.
-   * @param beanName the name of the Bean.
+  /** Creates a bean.
+   * <p>This is a convenience method that calls <code>instantiate(cl, 
beanName, null, null)</code>.</p>
+   *
+   * @see instantiate(ClassLoader, String, BeanContext, AppletInitializer)
+   * @param cl ClassLoader to be used or <code>null</code> for the system 
classloader.
+   * @param beanName Name of a serialized bean or class name.
+   * @return A newly created bean.
+   * @throws IOException If access of an IO resource failed.
+   * @throws ClassNotFoundException If the class name is not known or does not 
lead to a proper bean class.
+   */
+  public static Object instantiate(ClassLoader cl, String beanName)
+    throws IOException, ClassNotFoundException
+  {
+    return instantiate(cl, beanName, null, null);
+  }
+
+  /** Creates a bean.
    *
-   * @return the Bean.
+   * <p>This is a convenience method that calls <code>instantiate(cl, 
beanName, beanContext, null)</code>.</p>
    *
-   * @XXX
+   * @see instantiate(ClassLoader, String, BeanContext, AppletInitializer)
+   * @param cl ClassLoader to be used or <code>null</code> for the system 
classloader.
+   * @param beanName Name of a serialized bean or class name.
+   * @param beanContext Context to which the newly created Bean should be 
added.
+   * @return A newly created bean.
+   * @throws IOException If access of an IO resource failed.
+   * @throws ClassNotFoundException If the class name is not known or does not 
lead to a proper bean class.
    */
-  public static Object instantiate (ClassLoader cl, String beanName)
+  public static Object instantiate(ClassLoader cl, String beanName,
+                                   BeanContext beanContext)
     throws IOException, ClassNotFoundException
   {
-    Object bean;
-    InputStream serStream;
-    
-    if (cl == null)
-      {
-        serStream = ClassLoader.getSystemResourceAsStream
-          (beanName.replace ('.','/')+".ser");
-      }
-    else
-      {
-        serStream = cl.getResourceAsStream (beanName.replace ('.', '/')
-                                            + ".ser");
-      }
-    
-    if (serStream != null)
+    return instantiate(cl, beanName, beanContext, null);
+  }
+
+  /** Instantiates a bean according to Beans 1.0.
+   *
+   * <p>In Beans 1.0 the instantiation scheme is as follows:</p>
+   * <p>The name should be dot-separated (e.g "place.for.beans.myBean") and 
indicate either a
+   * serialized object or a class name. In the first case all dots in the name 
are replaced with
+   * slashes ('/') and ".ser" is appended ("place.for.beans.myBean" becomes 
"place/for/beans/myBean.ser").
+   * The bean is then loaded as an application or system resource depending on 
whether a
+   * <code>ClassLoader</code> was provided.</p>
+   *
+   * <p>If no such resource exists or if it contains no bean the name is 
interpreted as a class name of
+   * which an instance is then created.</p>
+   *
+   * <p>If a <code>BeanContext</code> instance is available the created bean 
is added to it.</p>
+   *
+   * <p>If the created Bean is an <code>Applet</code> or subclass and an 
<code>AppletInitializer</code>
+   * instance is available the applet is initialized and afterwards activated 
using the initializer. Additionally
+   * every instantiated <code>Applet</code> bean is initialized using the 
address@hidden Applet.init} method.
+   * Furthermore every applet gets a default <code>AppletStub</code>. The 
<code>Applet</code>'s
+   * document base is the location of the ".ser" file if it was deserialized 
or the location of its class
+   * file if it was instantiated.</p>
+   *
+   * <p>A <code>ClassNotFoundException</code> is not only thrown when a class 
name was unknown
+   * but even when the class has public no-argument constructor
+   * (<code>IllegalAccessException</code> is wrapped) or an exception is 
thrown while
+   * invoking such a constructor (causing exception is wrapped).</p>
+   *
+   * @param cl ClassLoader to be used or <code>null</code> for the system 
classloader.
+   * @param beanName Name of a serialized bean or class name.
+   * @param beanContext Context to which the newly created Bean should be 
added.
+   * @param initializer The AppletInitializer which is used for initializing 
<code>Applet</code> beans.
+   * @return A newly created bean.
+   * @throws IOException If access of an IO resource failed.
+   * @throws ClassNotFoundException If the class name is not known or does not 
lead to a proper bean class.
+   */
+  public static Object instantiate(ClassLoader cl, String beanName,
+                                   BeanContext beanContext,
+                                   AppletInitializer initializer)
+    throws IOException, ClassNotFoundException
+  {
+    Object bean = null;
+    URL beanLocation = null;
+    URL classLocation = null;
+
+    // Converts bean name into a resource name (eg. "a.b.c" -> "a/b/c").  
+    String resourceName = beanName.replace('.', '/');
+
+    /* Tries to get an input stream of the Bean, reading it as a system 
resource
+     * if no ClassLoader is present or as an application resource if a 
classloader
+     * is given.
+     */
+    beanLocation = (cl == null)
+                   ? ClassLoader.getSystemResource(resourceName + ".ser")
+                   : cl.getResource(resourceName + ".ser");
+
+    // Reads the serialized Bean from the returned URL.
+    if (beanLocation != null)
       {
-        if(cl == null)
-          {
-            ObjectInputStream ois = new ObjectInputStream(serStream);
-            bean = ois.readObject();
-          }
-        else
-          {
-            ClassLoaderObjectInputStream ois =
-              new ClassLoaderObjectInputStream (serStream, cl);
-            bean = ois.readObject();
-          }
+       // Deserializes the bean instance.
+       ObjectInputStream ois = (cl == null)
+                               ? new ObjectInputStream(beanLocation
+                                                       .openStream())
+                               : new ClassLoaderObjectInputStream(beanLocation
+                                                                  
.openStream(),
+                                                                  cl);
+
+       bean = ois.readObject();
+
+       /* Implementation note: The result of ObjectInputStream.readObject()
+       * may have been null at this point (its a valid value to deserialize)
+       * and we explicitly want to try instantiation in such a case
+       * (this is important for compatibility).
+       */
       }
-    else if(cl == null)
+
+    // Instantiates the Bean using reflective instantiation if it has not been 
created yet.
+    if (bean == null)
       {
-        Class beanClass = Class.forName(beanName);
-        try
-          {
-            bean = beanClass.newInstance();
-          }
-        catch(IllegalAccessException E)
-          {
-            bean = null;
-          }
-        catch(InstantiationException E)
-          {
-            bean = null;
-          }
+       // Makes sure that the deserialization was NOT done.
+       beanLocation = null;
+
+       Class beanClass;
+       if (cl == null)
+         {
+           beanClass = Class.forName(beanName);
+           classLocation = ClassLoader.getSystemResource(resourceName
+                                                         + ".class");
+         }
+       else
+         {
+           beanClass = cl.loadClass(beanName);
+           classLocation = cl.getResource(resourceName + ".class");
+         }
+
+       // Instantiates and optionally registers the new bean.
+       try
+         {
+           bean = beanClass.newInstance();
+         }
+       catch (IllegalAccessException iae)
+         {
+           // Wraps the illegal access as a ClassNotFoundException (as does 
JDK 1.5.0). 
+           throw new ClassNotFoundException(null, iae);
+         }
+       catch (InstantiationException ie)
+         {
+           // Repackages the cause of the InstantiationException into a 
ClassNotFoundException (as does JDK 1.5.0). 
+           throw new ClassNotFoundException(null, ie.getCause());
+         }
       }
-    else
+
+    /* Applet beans are treated in the following way:
+     * - all AppletS get a default AppletStub
+     * - all AppletS are initialized using the AppletInitializer instance (if 
it is available)
+     * - as every other Bean Applets are added to a BeanContext if one is 
available
+     * - each instantiated Applet is initialized using Applet.init() (this is 
not done for deserialized ones)
+     * - finally AppletS get activated using the AppletInitializerS 
activate-Method
+     *
+     * The order of operations is important for compatibility.
+     */
+    Applet applet = null;
+    if (bean instanceof Applet)
       {
-        Class beanClass = cl.loadClass(beanName);
-        try
-          {
-            bean = beanClass.newInstance();
-          }
-        catch(IllegalAccessException E)
-          {
-            bean = null;
-          }
-        catch(InstantiationException E)
-          {
-            bean = null;
-          }
+       // Makes a second instanceof call unneccessary (instanceof is 
expensive).
+       applet = (Applet) bean;
+
+       /* The AppletStub's code and document base is set as follows:
+        * The code base is always the URL from where the class data originated
+        * (without the package name).
+        * If the Applet was deserialized the document base is the location of
+        * the serialized instance (usually the ".ser" file) otherwise its the 
URL
+        * from where the class data originated (usually the absolute directory
+        * location of the ".class" file).
+        */
+       applet.setStub(new DummyAppletStub(applet.getClass()
+                                                .getProtectionDomain()
+                                                .getCodeSource().getLocation(),
+                                          (beanLocation == null)
+                                          ? classLocation : beanLocation));
+
+       // Runs the Applet's initialization using an AppletInitializer.
+       if (initializer != null)
+         initializer.initialize(applet, beanContext);
       }
 
-    if(bean instanceof Applet)
+    // Adds the new bean to its BeanContext.
+    if (beanContext != null)
+      beanContext.add(bean);
+
+    if (applet != null)
       {
-        Applet a = (Applet)bean;
-        //a.setAppletContext(???);
-        //a.setStub(???);
-        if(serStream == null)
-          {
-            a.init();
-          }
+       // Initializes an instantiated (not deserialized) Applet using its own 
method.
+       if (beanLocation == null)
+         applet.init();
+
+       // Runs the Applet's activation using an AppletInitializer.
+       if (initializer != null)
+         initializer.activate(applet);
       }
 
     return bean;
   }
 
   /**
-   * Get the Bean as a different class type.
+   * Returns the Bean as a different class type.
    * This should be used instead of casting to get a new
    * type view of a Bean, because in the future there may
    * be new types of Bean, even Beans spanning multiple
@@ -196,7 +289,7 @@
   }
 
   /**
-   * Determine whether the Bean can be cast to a different
+   * Determines whether the Bean can be cast to a different
    * class type.
    * This should be used instead of instanceof to determine
    * a Bean's castability, because in the future there may
@@ -204,7 +297,7 @@
    * Objects.
    *
    * @param bean the Bean to cast.
-   * @param newBeanClass the Class to cast it to.
+   * @param newClass the Class to cast it to.
    *
    * @return whether the Bean can be cast to the class type
    *         in question.
@@ -215,8 +308,8 @@
   }
 
   /**
-   * Find out whether the GUI is available to use.
-   * Defaults to true.
+   * Returns whether the GUI is available to use.
+   * <p>Defaults to true.</p>
    *
    * @return whether the GUI is available to use.
    */
@@ -226,9 +319,9 @@
   }
 
   /**
-   * Find out whether it is design time.  Design time means
+   * Returns whether it is design time.  Design time means
    * we are in a RAD tool.
-   * Defaults to false.
+   * <p>Defaults to false.</p>
    *
    * @return whether it is design time.
    */
@@ -238,7 +331,8 @@
   }
 
   /**
-   * Set whether the GUI is available to use.
+   * Sets whether the GUI is available to use.
+   *
    * @param guiAvailable whether the GUI is available to use.
    */
   public static void setGuiAvailable(boolean guiAvailable)
@@ -248,7 +342,7 @@
   }
 
   /**
-   * Set whether it is design time.  Design time means we
+   * Sets whether it is design time.  Design time means we
    * are in a RAD tool.
    *
    * @param designTime whether it is design time.