IBM VisualAge
Bean Extender Technology Release 2.0 README
12/11/97
Welcome to IBM VisualAge Bean Extender
IBM VisualAge Bean Extender, hereafter referred to as Bean
Extender, is intended
to support the creation of beans,
including applications and applets, by the aggregation and
republishing of existing bean components.
It also provides sample source code and demo code
for use by both bean developers and tools developers.
See the Bean Extender Licensing Terms for terms
and conditions governing the use and redistribution of Bean Extender.
Release 2.0 of Bean Extender Technology includes the following new features:
- Network deployment has been enhanced through the addition of
catalog and warehouse servers which may be interconnected to
form a virtual single warehouse and catalog. This allows
islands of development within an enterprise to easily connect
with each other and still retain control over published
content.
- Dipping Framework extensions now allow more control over
the morphing operation. In addition, dips can now get more
information about the dipped bean. The tools have been enhanced
to make the more easily integratable into other products.
- The Bean Extender set of classes has been split into separate
runtime and development time sets to allow for easier deployment.
- A serialization version checking tool has been added to the Bean
Extender tool suite to allow developers to check compatibility
between two versions of the same Serializable class file.
Compatibility is based on the set of rules defined in JavaSoft's
Object Serialization Specification.
- The managed bean code has been enhanced to support registration
of user-defined repositories such as the new network deployment
repository. It also now handles the JAR file
manifest tags Depends-On and Design-Time. Signed
JAR files are now treated specially as read-only to prevent corruption
of signed content or invalidation of the signature.
- The Dip Creation Wizard is a code generation tool for creating
beans known as "dips". The wizard takes care of generating all
the appropriate source code, text bundle, documentation, and
makefile to support building and packaging the dip, leaving the
developer free to focus on business logic. See the
Guide to Features for more
information on the Dip Creation Wizard.
Release 2.0 of Bean Extender Technology includes the following new
demos and sample beans.
- The network deployment demo shows how two developers and an
end-user interact via three separate machines to deploy, find, use,
and update beans. See the Guide to
Demos for a description of how to run the network deployment
demo.
- Two new samples, Splash Screen Dip and Performance Dip, cover
real life examples of dips built with the Dip Creation Wizard.
See the Guide to
Demos for a description of how to run the Dip Creation Wizard and
re-create the new sample dips.
- The Travel Services Demo has been enhanced so that it may now be
run as a multi-tier application which utilizes the Java RMI and
JDBC capabilities.
See the Bean Extender Guide to
Features for details.
Bean Extender 2.0 is not compatible with any previous release of Bean
Extender. This is due to a variety of reasons, but first and foremost
is JavaSoft's change in the Java package naming convention from
uppercase first level to lower case first level. This change will guarantee
code breaks on operating systems where filenames are case sensitive and
has caused problems on operating systems where filenames are not.
The Bean Management feature in Bean Extender will attempt to work around known
problems so that uppercase and lowercase package names can work
together when possible.
This release contains the following features:
Composition
Packaging and Deployment
Samples
Demos
For more information on the programming features, see the
Bean Extender Guide to Features.
For more information about Bean Extender, see the
documentation suite.
Bean Extender requires 10 MB of hard drive space and 4 MB of temporary
space for the two zip files. The recommended minimum
system configuration is the equivalent of a 133 MHz Pentium-class
processor with 32 MB of memory.
Bean Extender requires that you have the
Java Development Kit (JDK) 1.1.1 or
later installed.
Bean Extender has been tested on WindowsTM 95,
Windows NT 3.5.1, Windows NT 4.0, OS/2 Warp Version 4, and AIX 4.1.4
using JDK 1.1.1, 1.1.2, 1.1.3, 1.1.4, and 1.1.5 where possible.
However Bean Extender is pure Java and should run on any JDK 1.1.1 or later
enabled system.
For additional information on IBM's activities with Java and JavaBeans, see:
- Create a directory for Bean Extender. For example:
c:\extender
You can use the directory name of your choice.
- Download the following zip files from
alphaWorks
to c:\extender.
extender2.0-rt.zip
extender2.0-doc.zip
- Unzip both files using winunzip or a compatible
tool into the directory created in step 1.
- Create a subdirectory on your file system that
can be used as a work space by Bean Extender.
You can use the directory name of your choice. For example:
c:\extender\working
This directory is used by Bean Extender for a variety of file
manipulation operations.
Note: Do not place any personal files in this subdirectory because they can get
deleted.
- If you don't already have one, create a HOME directory and environment
variable, for example:
mkdir c:\home
set HOME=c:\home
The HOME directory will be used to store Bean Extender
properties. It should be added to your normal environment
settings file such as autoexec.bat or .profile.
The name of the HOME drive and directory are arbitrary, but the path name must
contain at least 4 characters. For the example above, the HOME
environment variable should contain:
c:\home
- Append the following to your system environment CLASSPATH:
C:\extender\jars\runtime.jar;C:\extender\jars\develop.jar;C:\extender\jars\awidgets.jar;C:\extender\working
(or substitute the drive and directory you have chosen). If you
plan to run the Dip Creation Wizard, you will also have to add
it's Beanery.jar, sk.jar, and C:\extender\jars\dipWizard.jar to the
CLASSPATH. Beanery.jar and sk.jar come from the Beanery, which is
available from IBM's
alphaWorks web
site. See Managing Jar Dependencies for an
alternative to adding lots of jar files to your CLASSPATH. See Placement of Working Directory in the
CLASSPATH for additional information.
- Issue the following command:
java com.ibm.beans.util.Configure
Be sure to enter the working directory that you created in step 4
under the Working tab, then press Exit and save changes.
When the command completes, you should have a file in
your HOME directory called BeanSystem.properties. For more
information on Configure, see Bean Extender Configuration in
the Guide to Features.
To run the Assembly Surface, type:
java com.ibm.beans.tools.assembly.AssemblySurfaceMain
Generating a Visual Bean
If you are using the Assembly Surface to create a visual bean, you
must open the Layout view prior to generating the bean. Then, under
the Layout view's Options->Generate as menu you may choose whether
the bean should be derived from Panel, Frame or Applet. The default
is to derive the new bean from java.awt.Panel.
Note that if you fail to open the Layout view prior to generating the
bean you will get an "Unable to run the generated bean" error if you
attempt to run the bean. You can correct the problem by opening the
Layout view, selecting the correct bean type as described above,
generating a new bean, then running the new version of the bean.
If you have accidentally opened the Layout view and do not wish to
generate a bean which is a visual component, select the Discard...
menu item from the Layout view's View menu, then click the OK
button on the dialog that appears. This will close the Layout view
and indicate that the current bean is not a visual component.
As your beans get more complicated and dependencies between beans
grow, or when you clear your working directory, you may receive
ClassNotFound exceptions when loading JAR files
or using beans in a JAR file. You can either load each individual
JAR file dependency to resolve the problem or you can use the JarJava
utility to help resolve the dependencies. Just place all directories
containing JAR or zip files on the CLASSPATH and run your Java
application using the JarJava utility. For example, the following will
allow you to load any JAR file in c:\extender\jars without
worrying about dependencies on other JAR files located in that directory:
set CLASSPATH=%CLASSPATH%;c:\extender\jars
java com.ibm.beans.tools.JarJava com.ibm.beans.tools.assembly.AssemblySurfaceMain
- Assembly Surface
- Beans generated with the Edit data and Dippable attributes
cannot be edited using the Edit beans button in the Beans
view. The workaround is to save your session state using
the File->Save as menu item and
restore it later using the File->Open menu item
to edit your bean.
- The Assembly Surface Beans view pop-up menu behaves
strangely on some operating systems with some versions of
the JDK (in particular, Microsoft Windows NT Version 4.0
with JDK 1.1.2, although similar behavior may occur on
other systems). The symptom is that the mouse click used
to select an item from the pop-up menu is first passed
through to the underlying Beans view, which causes a
different bean to be selected, and then the menu action is
applied to the incorrectly selected bean. If this occurs,
the work-around is to use the buttons at the bottom of the
Beans view instead of the pop-up menu.
- If a repository containing many beans is opened in the
Beans or Available dips view of the Assembly Surface, it
is possible
that not all beans will be displayed, even when the view
is
scrolled. If this occurs, one possible solution is to
divide the
repository into two or more smaller repositories using the
import/export capability of the Assembly Surface and then
open the new
smaller repositories instead of the single original large
repository.
Start by marking some of the beans in the original
repository in the
Beans view of the Assembly Surface and then click the
Export beans
button. Next open a new, empty repository in the
Repositories page
of the Beans view, then click on the Import beans button
at the
bottom of the new repository notebook page. This
copies the
previously exported beans to the new repository. Then
return to the
original repository page and click the Delete beans
button to remove
the copied beans from the original repository.
Alternatively, if you do not wish to modify the original
repository,
make a copy of the repository prior to starting this
procedure and use
the copy instead of the original in the preceding sequence
of steps.
- The Event Connections Model requires that the source of the event
(that is, the bean with which the listener was registered) must
also be the bean that fires the event (that is, the event source
object within the EventObject dispatched).
- When the Assembly Surface Generate button is
selected, a bean is
saved to a repository, but this
does not save the implementations of the contents with the bean.
When the assembled bean is deployed, the run time for its content
must be deployed as well. Packaging of the bean and
the run time on which it depends is left up to the
developer/assembler. Users of the bean will need
to add each deployed item (all the required JAR files) to their
CLASSPATH, or use a tool such as described previously to
place the implementation into a location already on the
CLASSPATH.
- The Publish View
- This release only supports "pure"
Java events. These are events whose listener methods take a
single argument subclassed from EventObject. Thus, this
release does not support publication of events taking multiple
arguments, events returning values, or events taking
no arguments.
- The current implementation of the code editing
window requires you to select the Save button
in order to save your editing work.
- Constructors of the bean being assembled should
not be added for exposure within the bean's
beanInfo. When the beanInfo getMethodDescriptor()
method is eventually called, these constructors
will not be
returned, even though the BeanInfo view currently
allows them to be added.
- The current implementation of the Publish view
only supports multicast events. There is no support
for unicast events (those
whose add/remove listener methods throw exceptions).
- The current implementation of the Publish view
does not support republishing a WindowEvent,
AdjustableEvent, or ItemSelectableEvent of an inner
bean as an event of the resulting aggregate bean.
This is due to the aggregate bean changing the source of
the event to make it appear to any listeners that the
source of the event was the aggregate bean itself.
This, in effect, hides the details of the inner
beans. The previous events, however, expose additional
details about the inner beans which may not be true
of the aggregate.
- When republishing a user-defined event (an event
whose subtype is not an AWT event type), the
generated code may cause security violations when
run in an applet, depending on the security
restrictions enforced by the browser used.
- Some Java-defined events constrain the type of object
that can source those events. For instance, a
java.awt.event.ItemEvent source can only be an
instance of java.awt.ItemSelectable. Hence, it is
invalid to attempt to republish such an event from
an object that is not of the appropriate type.
For instance, it is invalid to attempt to
republish an ItemEvent from a container that does
not implement ItemSelectable. Attempting to do so
results in a compilation error.
- When republishing a Java-defined event (such as ItemEvent
or ActionEvent), if the object that is actually
fired at runtime is an instance of a user-defined
subclass of the Java-defined event, then the
listener for the republished event will receive an
instance of the Java-defined event rather than an
instance of the user-defined event. For instance,
if an ActionEvent is republished from an inner
button, and at runtime the button fires an event
that is an instance of some user-defined subclass
of ActionEvent (rather than an instance of
ActionEvent), the listener to the container that
republishes the event will receive an ActionEvent,
rather than an instance of the user-defined
subclass of ActionEvent.
- Visual Layout in the Assembly Surface
- If you wish to resize the aggregate bean to be
larger or smaller than the size available within the
Assembly Surface, you must create a separate window
for the Layout view. Please refer to the section
Using the
Assembly Surface User Interface in the
Bean Extender Guide
to Features for specific
information on how to create this separate window.
- Dimensionless beans:
Upon opening the Layout view, all beans that are descendants from
java.awt.Component are automatically inserted
and positioned
within the Layout view panel (assuming the
Options->Automatically add beans
menu item is checked). However, any bean which returns a
preferred size of
0 (zero) will not be automatically added when the
Layout view is initially
opened.
You must manually insert these initially dimensionless beans.
To manually insert a bean, select the bean in the
Assembly Surface
Contents view. Then, from the Layout view, choose the
Edit->Add menu item. Your bean is then centered at the
insertion point you choose.
- The Edit->Add menu item is not enabled in any of the
following conditions:
- When the current selection in the Assembly Surface
Contents view has already been added to the Layout.
- When the current selection in the Assembly Surface
Contents view is derived from java.awt.Window (such
as a Frame or a Dialog), and thus cannot be added to a
panel due to a Java API restriction.
- When the current selection in the Assembly Surface
Contents view is itself not derived from
java.awt.Component, and thus cannot be added to a panel.
- Selecting Edit->Hide on a bean does not work with JDK 1.1.1.
It causes the process running the bean to hang. The
same problem happens if visibility is set in the scripting
initialize method.
- Bean Management
- It may be necessary to periodically clean out the contents
of your working
directory. The contents should not be removed while Bean
Extender is running.
-
When the contents of the working directory
are cleared, it may cause ClassNotFound exceptions when
trying to run
beans generated by the Assembly Surface. This is due to
the
contents of the bean and the bean implementation itself
not being
directly on the CLASSPATH. There are two possible
work-arounds:
- Use the Assembly Surface to open and browse the
repositories
(JAR or directory) that contain the required .class
files. This
primes the working directory with the
implementations,
making the beans runnable again.
- Add the JAR files or directories that contain the
.class
files to your CLASSPATH.
- Despite the Javadoc in RepositoryModelFactory and
NetRepositoryModel, URLs that specific network repository
models may not contain asterisk wildcards. "Default"
server information may be obtained from the
BeanSystem.properties file.
- Dip Creation Wizard
- WARNING: The code generator does NOT preserve changes to
source files made outside the wizard. A warning message is
shown before overwriting a file, but if you say yes, any
changes you made to the file will be lost.
- Values entered are checked for correct form, but not
content. Use valid characters for forming file system names in
names entered.
- JIT
The JIT compiler can cause problems with exception handling
on the WIN32 platforms and can cause scripting problems
on OS/2 platforms.
- JDK 1.1.3
There are problems with process termination and the debugger
when using JDK 1.1.3. When you are debugging a bean in the
Assembly Surface, you should close the beans window before
closing the debugger window.
- JDK 1.1.4 and JDK 1.1.5
JDK 1.1.4 and 1.1.5 are problematic on all operating systems due to a
bug which prevents applets from being instantiated as a
bean.
- Network Deployment
- Ordered content being refreshed through a subscription or manually
is updated on a client only if the warehouse copy has changed.
There currently is no provision to force downloads in the
event that the client copy has been corrupted or deleted.
- Currently, there is no way to remove an order.
- If the Network Deployment Warehouse Server is stopped, the
communications settings are restored from a file, and the
server is then restarted, the Network Deployment Client
will not be able to perform any warehouse server tasks
until it is explicitly reconnected to the server. From
the Options menu, select "Set Warehouse Server
Connection", and then click the OK button on the
connection dialog.
- Scripting
- The terminate method of a script may not always be called. In
particular, it cannot be called during design time in the
FormBuilder demo. It will be called in the FormRunner script demo
launcher.
- If you use scripting (open the Scripting view) in the
Assembly Surface, it cannot stop using scripting.
If you want to create a new bean without scripting, you need to remove
the Scripting view first then exit and restart the Assembly
Surface.
- If you are developing beans using NetRexx as the scripting
language, you need to install NetRexx Version
1.105 or later on your computer and put NetRexxC.zip on your class
path.
- Bean Extender scripting classes do not require any NetRexx
run-time support. Some NetRexx language features
may require NetRexx run-time support. All the NetRexx run-time
classes are in NetRexxR.zip. You can load the NetRexxR.zip
repository into the Assembly Surface and use the export/import
features to selectively include any required run-time support
in your scripted bean's repository.
- Samples
- Audio Player Media Sample
The media sample AudioPlayer requires an applet
environment in order to play an audio clip. As a
consequence, some methods of invoking the AudioPlayer will
not play audio clips. The AudioPlayer sample does work
correctly when you run appletviewer with AudioPlayer.html.
- Performance Dip
- On some implementations of Java, the clock is only accurate
down to about 10 milliseconds. Methods that execute in less
time than this threshold may have a time of 0 milliseconds
reported.
- When testing the Performance Dip with visible beans from
within the Assembly Surface Tool, a deadlock
situation can occur
if both the Log view is open and the Layout view are
open. This
problem occurs if the bean attempts to draw at the
same time as
the timing message is being output to the log. To
avoid this
potential problem, do not have the Log view and the
Layout view
open at the same time. This problem only occurs within the
Assembly Surface tool, and will not occur when the
dipped bean
is deployed.
- Particularly for visual beans, the log may contain timing
information on more methods, properties, and events than
desired. If you would like to only receive timing
information on
methods from your immediate class, and not consider methods
inherited from ancestor classes, then clear the
"Dippable class
overrides parents method(s)" checkbox on the Advanced
Customization page of the morphing dialog when
morphing the bean
to which the dip will be applied.
- Much of the API reference for the Performance Dip
was auto generated
by the Dip Creation Wizard and may not be entirely useful.
Please see the Guide to Features for documentation instead.
- Splash Screen Dip
Much of the API reference for the Splash Screen Dip was
auto generated by the Dip Creation Wizard and may not be
entirely useful. Please see the Guide to Features for
documentation instead.
- Utilities
Due to limitations in the file selection dialog on WIN32 platforms,
it is not possible to select just a directory. A
work-around is to use a known default file name of "[directory
repository]". If you accidentally select a file while
browsing for a directory, the default file name is replaced. You
need to type in the work-around default file name to be able to
select a directory repository.
- Web Browsers
A Java 1.1 capable browser, such as HotJava, is
required to use beans generated by the Assembly Surface on the
Web. Generated applets can also be run in the JDK 1.1.x
appletviewer.
Sample source files are located in the c:\extender\src
directory, where
c:\extender is the location where the product was installed.
The demos included are:
- Travel Services Application
- 401(k) Investment Application
Documentation for the demos can be found in the Guide to Demos.
The documentation suite also contains
the "API Reference" that includes the APIs and incomplete documentation for
the demos.
Updating the Demo Source Code
If you decide you want to change the demo code, you can recompile
it with javac. However, if you change the class you will need to change
the .jar file so that you can use your modified bean on the Assembly
Surface.
Unfortunately, the jar command does not provide the ability to update or
add to an existing .jar file. (This is being requested with BugID 4036599.)
Until the jar command has the capability of updating an existing .jar file,
you can use the Info-ZIP command. The Info-ZIP command was written
by the same developers who wrote zlib, which is the basis for the jar
command. The commands appear to be compatible. If you do not already have
a copy of Info-ZIP, you can obtain one at the following location:
When you have the Info-ZIP command, you can update the .jar file. The
following example shows you how:
- Change the directory to the top of the source tree for the samples.
Assuming that you installed Bean Extender on your D drive, enter
the following command:
cd D:\extender\src
- Update the appropriate class with the following command:
zip -u -0 D:\extender\jars\xxx.jar com\ibm\beans\samples\yyy\zzz.class
where:
For the 401(k) Investment Application demo:
xxx = 401k
yyy = a401k
zzz = b401kDap
Or for the Travel Services Application demo:
xxx = travel
yyy = travel
zzz = Itinerary
This puts a new copy of the class into the .jar file.
Note: It is important that you use the fully-qualified directory path
for the new copy of the class.
Running BeanExtender Demos In Web Browsers
Below is a list of testing activity that indicates which browsers
successfully run the BeanExtender 401kDemo and TravelDemo.
IMPORTANT: make sure that your browser security is set as low as
possible when attempting to run the BeanExtender demos.
appletviewer (JDK 1.1.2):
- 401k (local): Runs successfully.
- Travel (local): Runs successfully.
HotJava 1.0.1 (JDK 1.1.2):
Note: set the JDK_HOME and JRE_HOME environment variables
to the top-level directory of your JDK installation before
running HotJava 1.0.1.
- 401k (local): Runs successfully.
Insure that the BeanExtender runtime.jar, develop.jar, and working
directory are on the CLASSPATH before running HotJava 1.0.1.
When running on NT, modify the "codebase" value in the applet's
HTML to use backward slashes instead of forward slashes.
- Travel (local): Runs successfully.
Insure that the BeanExtender runtime.jar, develop.jar, and working
directory are on the CLASSPATH before running HotJava 1.0.1.
When running on NT, modify the "codebase" value in the applet's
HTML to use backward slashes instead of forward slashes.
- 401k (network): Runs successfully but requires special browser
invocation and changes to 401kDemo.html. See the comments in
401kDemo.html
for details.
- Travel (network): Runs successfully but requires special browser
invocation and changes to TravelDemo.html. See the comments in
TravelDemo.html
for details.
HotJava 1.1 (JDK 1.1.2/JDK 1.1.4/JDK 1.1.5):
Netscape Communicator 4.04 (JDK 1.1 patch from Netscape):
- Neither the 401kDemo nor the TravelDemo run, due to two
known limitations of Netscape. The first is described in
http://developer.netscape.com/software/jdk/relnotes.htm
Under "Features Not Yet Implemented" it says "Loading multiple jar
files from within an APPLET tag is not supported."
The second limitation is that Beans.instantiate() fails,
possibly due to limitations in JDK 1.1.4 (or bugs in the
particular version of the JDK that Netscape is using).
Internet Explorer 4.0/4.01 (JDK 1.1.2):
- 401k (local): Runs successfully provided that the
CLASSPATH setting in ControlPanel->System->Environment
contains the fully qualified path names for all JAR files used
by the demo. (This list of
JAR files used by each demo is listed in the "archive" tag
in the corresponding HTML file. In addition, runtime.jar
and develop.jar are also used by both demos.)
We noted that when running an applet within Internet Explorer,
the HOME environment variable does not have its proper value
(its value appears to be modified by Internet Explorer).
As a result, BeanExtender code that uses the working directory
or other properties in the %HOME%\BeanSystem.properties file
will not operate properly in this environment.
- Travel (local): Same as 401k (local).
Although the Travel demo runs, the header and footer images
are not displayed due to an Internet Explorer security violation
when loading local .gif files.
- 401k (network): Runs successfully when the system
CLASSPATH setting (in the ControlPanel->System settings)
does not include any classes used by the demo, when all
the JAR files used by the demos (including runtime.jar and
develop.jar) are on the server machine, and when the
HTML file (401kDemo.html or TravelDemo.html) is modified
with the appropriate codebase and archive settings, as
described in the HTML file. (The modifications to the HTML
file for Internet Explorer are the same as described for
the HotJava browser.)
- Travel (network): Same as 401k (network).
When making changes to existing sample source, the placement on the
CLASSPATH of the
working directory created during install and the src directory is
important. There could be copies of the samples cached in the
working
directory, and if the working directory is in the CLASSPATH ahead of
the
src directory, your changes will not be found. You need to either
place the src directory ahead of the working directory or remove the
cached copies from the working directory.
If you have comments, questions, problems, or suggestions, you can
voice them on the
alphaWorks
Community Exchange.
© Copyright International Business Machines Corporation 1997.
All rights reserved.
Note to U.S. Government Users - Documentation related to restricted
rights -- Use, duplication or disclosure is subject to restrictions set
forth in GSA ADP Schedule Contract with IBM Corp.
Trademarks
The following terms are trademarks of the IBM Corporation in the United
States or other countries or both:
The following terms are trademarks of other companies:
- Microsoft, Windows, Windows NT, and the Windows 95 logo are trademarks or
registered trademarks of Microsoft Corporation.
- Java, JavaSoft, HotJava, JavaBeans and Sun are trademarks of Sun
Microsystems, Inc.
- Other company, product, and service names, which may be denoted by a double
asterisk (**), may be trademarks or service marks of others.