To understand the functions of Proto2Bean converter tool, we need fist decide what proto-bean should be. In the following text I first describe the functionality and design patterns for proto-beans, as I see this now, and then proto2bean converter requirements. I also attach "beanmodel.wrl" a simple VRML model that I want to implement in beans, as well as more detailed example of "event wiring" for two beans from this model.

Before going to design patterns I'll try to explain the main idea behind "wiring" proto-beans. In short bean with EventIn definition in its PROTO interface is a ** listener ** for events from other beans with corresponding EventOut. Thus ROUTEing from EventOut to EventIn is replaced by registering bean with EventIn of <FieldType = AType> as a listener with the bean that has EventOut of the same type :  <FieldType = AType>. 

Proto2Bean tool generates: 

- listener interface classes, one for each EventIn with <EventName> name
- concrete proto-bean classes, one for each PROTO
- concrete event classes, one for each <EventName> 

Event classes are constrained by <EventName> which allows to make a distinction between events with the same field type but with different semantics, such as :

eventIn SFTime startTime
eventIn SFTime stopTime

This ensures that listener for "startTime" events can not be **automatically** registered with the event source of "stopTime" events. On the other hand both of this event types extend base SFTime event class. Extending base event class allows for more sophisticated tools connect listeners to sources that "understand" the same ** base event class **. 


*** Design patterns ***

//
// Design patterns for PROTO interface :
//
PROTO <ProtoName> [
    eventIn       <FieldType> set_<EventName>
    eventOut      <FieldType> <EventName>_changed   
    exposedField  <FieldType> <ExposedFieldName>       <DefaultValue>
    field         <FieldType> <FieldName>              <DefaultValue>
] { ... }

//
// Design patterns for PROTO with EventIn :
//

// The following Listener interface is generated 
// ** for each EventIn in PROTO interface **

public interface <EventName>EventListener extends java.util.EventListener {
  // EventIn handling method
  void handle<EventName>EventIn(<EventName>Event evt);
}

// Concrete bean class for PROTO with ** at least one EventIn **

public class <ProtoName> implements 
<EventName1>EventListener, <EventName2>EventListener, ... {

  // Constructor:
  public <ProtoName>(Node protoNode);

  // EventIn handling methods:

  void handle<EventName1>EventIn(<EventName1>Event evt);
  ...
  // EventIn handling method
  void handle<EventName2>EventIn(<EventName2>Event evt);

}

// Declarations for events processed by "EventIn" listener 
public class <EventName>Event extends <FieldType>Event {...}
public class <FieldType>Event extends java.util.EventObject {...}

//
// Design patterns for PROTO with EventOut :
//

// Concrete bean class for PROTO with ** at least one EventOut **
public class <ProtoName> implements EventOutObserver {

  // Constructor:
  public <ProtoName>(Node protoNode);

  // Fire EventOut <EventName> event to the listener
  public void fire<EventName>Event(<EventName>Event evt) {...}

  // EventListener registration methods 
  // conform to the following design patterns :
   public void add<EventName>EventListener(<EventName>EventListener listener);
   public void remove<EventName>EventListener(<EventName>EventListener listener);

}

*** Fields ***

* PROTO "fields" are accessible in ** design time only ** with "setter/getter" methods :

public <FieldType> get<FieldName>(); 
public void set<FieldName>(<FieldType> fieldValue); 

This access may be required to change shape properties such as "size", "radius", etc... Setting new value in the field results in setting new <DefaultValue> in PROTO interface.

* Exposed fields. 

public <FieldType> get<ExposedFieldName>(); 
public void set<ExposedFieldName>(<FieldType> fieldValue); 

Setting exposed field in Proto-Bean automatically sets the value of the corresponding field in VRML node and generates a <ExposedFieldName>_changed eventOut. 

* EventIns. 

VRML EventIns are ** write-only **. When eventIn "setter" method of some Prot-Bean class is called, input event is sent to the eventIn of the corresponding node : 

public void set<EventInName>(<FieldType> eventInValue); 

* EventOuts. 

These are ** read-only ** properties. The "setter" access method for eventOuts is not defined. To access current value of the eventOut of some node, "getter" method of the corresponding Proto-Bean class should be called : 

public <FieldType> get<EventOutName>(); 


*** Bound Properties ***

Proto-beans may provide a change notification service for some or all of its properties : eventIns, eventOuts and fields. Such properties are known as "bound properties" and allow other components to bind special behavior to property changes. In case when node bean classes want to report a bound property update to any registered listeners they should call proto-bean "firePropertyChange" method. 

The PropertyChangeListener event listener interface is used to report updates to Proto-bean ** bound ** properties. Proto-bean supports bound properties by a pair of multicast event listener registration methods for PropertyChangeListeners: 

public void addPropertyChangeListener(PropertyChangeListener x); 
public void removePropertyChangeListener(PropertyChangeListener x); 

Proto-bean fires "PropertyChangeEvent" event to registered listeners, whenever any of its fields, eventIns or eventOuts get changed. 
"PropertyChangeEvent" event is fired AFTER bean internal state is updated. Any bean, which may be also "not-VRML bean", can register itself as a PropertyChangeListener with a source Proto-bean to be notified of its property updates. When a property change occurs on a bound property the Prot-bean calls :

PropertyChangeListener. propertyChange(PropertyChangeEvent)

method on any registered listeners, passing a PropertyChangeEvent that encapsulates the eventIn/eventOut/field name of the property and its old and new values. 

*** Constrained Properties ***

The VetoableChangeListener event listener interface is used to report updates to constrained
properties. 
Proto-bean may treat eventIn-s and fields (in design time) as  constrained properties. In this case it should include a pair of multicast event listener registration methods for VetoableChangeListeners:

public void addVetoableChangeListener(VetoableChangeListener x);
public void removeVetoableChangeListener(VetoableChangeListener x);

When ** constrained ** eventIn or field is going to change its value, the proto-bean should call "VetoableChangeListener.vetoableChange" method on any registered listeners, passing a PropertyChangeEvent object that encapsulates the eventIn or field name and its old and new values. If recipient does not wish the requested "edit" to be performed it may throw a PropertyVetoException. It is the source proto-bean responsibility to catch this exception, revert to the old value, and issue a new VetoableChangeListener.vetoableChange event to re-port the reversion.

Exposing eventIn-s and fields as constrained properties may be useful to allow other "non-VRML" beans control proto-beans behavior.

>Actually, I think the tool should create the .java source for the bean
>from the PROTO interface declaration, then compile that into a .class
>file and package it up into a jar file. The generation of the code for
>the bean can be completely automated. It is simply a reflection of the
>PROTO interface in Java.

*** Proto2Bean tool ***

A tool automatically generating .java sources for the proto-bean is very useful but lacks flexibility. There should be some way to specify :
- for what eventIn-s listener support to generate;
- which fields and eventIn/eventOut-s to expose as bound properties;
- which fields and eventIn-s to expose as constrained properties;

Besides, it is absolutely legal and may be convenient for developer to provide additional functionality in proto-bean class by exposing other "non-VRML" interfaces. Proto2Bean can not provide automatic support for such additional functionality.

Still I think that automatic Proto2Bean generator is very useful and can be enhanced with the above feature later.

*** Example ***

In the attached example there are four PROTO-s (to be beans) :
- SpinBox - spining and glowing shape
- Glow (yellow sphere) - "glow" source
- StartButton (green cone) - start spin button;
- StopButton (gray cylinder) - stop spin button;

beans.txt - detailed description of registering SpinBox bean as a listener in StartButton bean for "StartTimeEvent" events.

Dima