JavaBean Introduction

1. JavaBean IS NOT EnterpriseJavaBeans!
   EJB requires you to install JBoss to run a complete set of services to store objects in a database and render them via the web. Only in object attributes there is a small overlap.
2. JavaBean is simply a support for "virtual properties".
   Instead of a member property "public int foo" you will use two property methods get() and set() to access an object property. This allows you to store the actual value somewhere on the southpole.
3. JavaBean needs no inline meta declarations - it works by reflection.
   There is a standard naming policy since the Java language does not have a native syntax for virtual properties. The reflection mechanism will look for all methods coming in pairs of "setFoo()" and "getFoo()". To be accepted as bean methods however one must mark the class name in the jar file manifest as a bean class.
4. Bean Objects need not implement Serializable - or any other Interface.
   The reflection works on pure method names. In fact an object might store the values in a database and the bean is just a proxy holding a handle. The handle is not supposed to be made persistant or to be transfered to another system - but may be some object reference name may which is meta data over the bean value set.
5. The beef is in the JavaBean framework providing helper methods.
   Classic java handling knows member properties that can be serialized to store them in a file or transfer them to another object (or to duplicate them). The framework extends it to virtual properties mostly opting for xml instead of binary persistance.
6. Mix public persistance attributes with local attributes.
   Standard OO principles did always tell of hiding public properties behind interface set/get methods so that the data implementation can be changed later. Just name private propoerty methods different if you do not want them serialized by the bean framework. Member properties are not seen anyway.
7. Bean frameworks already supports basic data types and lists.
   The scheme can be extended but for most parts it is sufficient to support bool/int/string data items and list members with those. No extension necessary for object types that are themselves beans.
8. Bean framework persistance reconstructs object references.
   Especially for list properties it can store a eference to that object being serialized in another area - i.e. two xml nodes in an xml file being interdependent by 'id="1"' and 'ref="#1"'.
9. Allows third party tools visualize/modify bean properties.
   With the same retroinspection a form generator can be given a bean object - it will seek out the virtual properties and present entry fields / checkboxes on screen. For GUIs one can dragdrop a "copy" of a bean object into another program context (or put a proxy there).

Standard Virtual Properties

http://java.sun.com/products/javabeans/ a.k.a. "JavaBeans Activation FrameWork (JAF)". That documentation is all misleading for concentrating on the server side i.e. how to write a GUI engine that can use the JAF to inspect virtual objects with their virtual properties. Many other tuturials concentrate on GUI beans with the virtual properties relating to "size", "height", "color" and the framework allowing to hibernate the graphical object.

Read/Write Value Property

   public Foo getFoo();
   public void setFoo(Foo value);

It is possible to only use Read or Write but that would not allow to use any of the persistance support.

Read/Write Boolean Property

   public boolean isFoo();
   public void setFoo(boolean value);

A boolean property is-a value property with the additional sugar of allowing "is" as a synonym to "get". Repeat, you may declare both "is" and "get" but you shall not make them behave different.

Read/Write Array Value Property

   public Foo[] getFoo();
   public void setFoo(Foo[] value);

It is allowed to (ab)use a Value Property for an Array by just defining get/set of a native array. In most cases you want an indexed property.

Read/Write Array Indexed Property

   public Foo getFoo(int item);
   public void setFoo(int item, Foo[] value);

In reality you must implement 4 methods (!!!) to get an indexed property as the two array value property methods must be defined as well. Remember to use "throws ArrayIndexOutOfBoundsException".

Event List Properties

   public void addSomeListener(SomeListener);
   public void removeSomeListener(SomeListener);

PropertyChange Event List Properties

private PropertyChangeSupport changes = new PropertyChangeSupport(this);
public void addPropertyChangeListener(PropertyChangeListener p) {
    changes.addPropertyChangeListener(p); }
public void removePropertyChangeListener(PropertyChangeListener p) {
    changes.removePropertyChangeListener(p); }

To be fired when any property does change. Any "bound property" must call "firePropertyChange" when it finds itself being modified. The listeners will each see a "propertyChange(PropertyChangeEvent)" call.

public void setFoo(int foo) {
  int old = this.foo;
  this.foo = foo;
  repaint();
  changes.firePropertyChange("foo", new Integer(old), new Integer(foo));
}

Vetoable PropertyChange support

Allows an attempt for a property change to be vetoed. Such a "set" method will support the "PropertyVetoException". There is again helper support for this scheme:

private VetoableChangeSupport vetoes =  new VetoableChangeSupport(this);

public void addVetoableChangeListener(VetoableChangeListener v) {
     vetoes.addVetoableChangeListener(v); }
public void removeVetoableChangeListener(VetoableChangeListener v) {
     vetoes.removeVetoableChangeListener(v); }


public void setFoo(int foo) throws PropertyVetoException {
  vetoes.fireVetoableChange("foo", new Integer(this.foo), new Integer(foo));
  int old = this.foo;
  this.foo = foo;
  repaint();
  changes.firePropertyChange("foo", new Integer(old), new Integer(foo));
}

Bound Properties

The term "Bound Properties" is another name for simple properties that are connected to change events. Just like in the glue code above one has a VetoableChange event before the virtual property is being changed and a PropertyChange event after the virtual property is being set. Using the PropertySupport member one can inherit the signal event framework - using add/remove one can bind objects as being emitters and listeners. Note: PropertyChange uses a "name" for the change-event subtyping which must be switchcased in the (anonymous) listener.

  class Client implements PropertyChangeListener {
    public void propertyChange(PropertyChangeEvent event) {
      String thePropName = event.getPropertyName();
      Object oldPropValue = event.getOldValue();
      Object newPropValue = event.getNewValue();
  } 
}

JAR Packaging

package.tmp : GNUmakefile */*.java
  echo "Manifest-Version: 1.0" > $@
  echo "Created-By: $(PACKAGE) make" >> $@
  echo "Main-Class: $(MAINCLASS)" >> $@
  echo "Implementation-Title: $(TITLE) " >> $@
  echo "Implementation-Version: $(PACKAGE) $(VERSION)" >> $@
  echo "Implementation-Vendor: $(AUTHOR)" >> $@
  echo "Implementation-Time: `date`" >> $@
  @ for f in */*.java ; do if grep "@javabean" "$$f" >/dev/null ; then :\
  ; F=`echo "$(subdir)/$$f" | sed -e "s/\\.java/.class/"` ; echo "" >> $@ \
  ; echo "echo 'Name: $$F' >> $@ ; echo 'Java-Bean: true' >> $@" \
  ;       echo "Name: $$F" >> $@ ; echo "Java-Bean: true" >> $@ \
  ; fi done

Manifest-Version: 1.0
Created-By: MyProject make
Main-Class: de.draheim.myproject.MainCommand
Implementation-Title: MyProject ShowCase
Implementation-Version: MyProject 0.5
Implementation-Vendor: Guido Draheim
Implementation-Time: Sam Nov  6 18:00:38 CET 2004

Name: de/draheim/myproject/MyFooObject.class
Java-Bean: true

Name: de/draheim/myproject/MyFooBar.class
Java-Bean: true

The "@javabean" tag is best used to rename the documentation when there are both an "interface MyFoo" and "class MyFooObject" around. In that case just mark the "MyFooObject" to be responsible to read and write persistance files containing "MyFoo" nodes. The declaration of that "rename" or "aliasing" looks like this:

  package de.draheim.myproject;
  
  /* MyProject Foo.
   *
   * @javabean.class name="MyFoo"
   * @author (C) 2005 Guido Draheim, All rights reserved.
   */
  public class MyFooObject implements MyFoo {
  }

AOP - Attribute-Oriented Programming

The "@javabean.*" hints can be seen by an doclet extension of the javadoc step. Here is a list of class-level tags:

• .class name=text : name of javabean (unqualified classname). mandatory.
• .class class=text : class name of real bean.
• .class displayName=text : name displayed for the bean
• .class shortDescription=text : oneliner description of the bean
• .icons mono16=text color16=text mono32=text color32=text
• .attribute name=text value=text rtexpr=bool : extra bean info
  (may be repeated with different name, possibly runtime java expr values)

Here is a list of method.level tags:

• .property displayName=text : the name display for the property
• .property shortDescription=text : oneliner description of the prop
• .property propertyEditor=text : fully qualified name of the editor class
• .property readonly=bool : per default it is readwriteable
• .method name=text displayName=text shortDecription=text
• .param name=text displayName=text shortDecription=text propertyEditor=
  (the method/param name is mandatory of course)

Starting with Java5 it is possible to set additional attributes as annotations instead of special comment. That looks like this:

    import java.lang.annotation.*;
    
    @Copyright("2005 Guido Draheim");
    public class MyClass {

Standard annotations: @Depracated, @Overrides, @Inherited (i.e. attributes are inherited from base), @Retention (hint not for runtime objects), @Target (another target for the hint). You can easily define your own annotations by declaring it like "public @interface MyHint" in a MyHint.class.

Form Tools

There are framework tools to represent a bean object to other services. A widely used method is to dump the object tree as an xml file. The other is used to present it as html.

XMLEncoder

The "java.beans.XMLEncoder" is a helper that can store an entire tree of AOP objects to a file - and read it back later. Each object class must have a default constructor of course. The writer-code looks like this boilerplate:

   import java.beans.XMLEncoder;
   import java.beans.ExceptionListener;
   public class MyTreeRoot {
     public static void printXml() throws IOException {
       XMLEncoder output = new XMLEncoder(System.out);
       output.setExceptionListener(new ExceptionListener() {
          public void exceptionThrown(Exception e) {
            System.err.println("RECOVERING"); e.printStackStrace(); }});
       output.writeObject(self); output.flush();  } }

BDK - JavaBeans Development Kit

http://java.sun.com/products/javabeans/software/bdk_download.html offsers a simple GUI designer mainly for graphically oriented beans. There is a draw canvas where beans can be placed and interconnected with event signal paths.

Extra note: originally the whole javabeans stuff was meant to plugged into an IDE - which is the reason for all this "icons" and "shortDescr" attributes. The XMLEncoder/XMLDecoder is actually a new thing that can be used easily and successfully in a non-gui environment.

BeanUtils

http://jakarta.apache.org/commons/beanutils/ has only a dependency on the jakarta commons collection types but gives us a number of data beans and helpers. For example the BeanUtils class has a "copyProperties" call that "Copy property values from the origin bean to the destination bean for all cases where the property names are the same." Nice.

ecolosim.beans

www.codeproject.com/cpp/JavaBeanInMFCDialog.asp

Editor Implementation

An editor for a bean object must implement the PropertyEditor. There is an "PropertyEditorSupport" class that can be subclassed or used as an inner class (due to lack of multiple inheritance).

• http://www.galileocomputing.de/openbook/javainsel4/
• http://www.informatik.uni-frankfurt.de/java/JDK/JDK_tutorials/Introduction_to_the_JavaBeans_API_05_1999/JBeansAPI/shortcourse.html#IndexedProperties

• http://freshmeat.net/projects/sanssouci/
  LGPL Sanssouci is a Java framework for auto-generating fancy Swing GUIs via introspection that display objects directly to the user. The core idea is based on a book and implementation of a quite similar framework called "Naked Objects", but it is a complete clean-room implementation with a Swing-based interface and Java2 compatibility. It has no automatic persistence mechanism, but has a lot of new features not available in Naked Objects.