pivot.wtkx
Class Bindable

java.lang.Object
  extended by pivot.wtkx.Bindable

public abstract class Bindable
extends Object

Base class for objects that wish to leverage WTKX binding. By extending this class, subclasses may use the @Load and @Bind annotations to automate WTKX loading and binding within their class.

A Practical Example:

As an example, consider the following WTKX file, named example.wtkx:

 <Border xmlns:wtkx="http://incubator.apache.org/pivot/wtkx/1.1"
         xmlns="pivot.wtk">
     <content>
         <FlowPane orientation="vertical">
             <Slider wtkx:id="redSlider" bounds="{minimum:0, maximum:255}" value="0"/>
             <Slider wtkx:id="greenSlider" bounds="{minimum:0, maximum:255}" value="0"/>
             <Slider wtkx:id="blueSlider" bounds="{minimum:0, maximum:255}" value="0"/>
             <Border wtkx:id="colorBorder" preferredWidth="120" preferredHeight="30"/>
         </FlowPane>
     </content>
 </Border>
 
You could leverage WTKX binding by subclassing Bindable, like so:

 public class Example extends Bindable {
     @Load(resourceName="example.wtkx") private Border border;

     @Bind(fieldName="border") private Slider redSlider;
     @Bind(fieldName="border") private Slider greenSlider;
     @Bind(fieldName="border") private Slider blueSlider;
     @Bind(fieldName="border", id="colorBorder") private Border colorSample;

     public Example() {
         // Your annotated variables will be null until you call bind()
         bind();
     }
 }
 

Binding implementations:

WTKX binding can be performed using one of two methods. It is important for callers to understand these methods so that they may decide which is appropriate for them. The methods are as follows:
  1. Runtime / Reflection

    The default binding process loads the WTKX at runtime and uses reflection to bind the values to the variables. This method requires security privileges; it is suitable for callers that are deploying to a trusted application, such as a signed applet or a desktop application.

  2. Runtime / No Reflection

    For those callers that are deploying to an unsigned applet, a compile-time annotation processor, BindProcessor, is available and will cause the binding process to load the WTKX at runtime and bind the values to the variables without the use of reflection. This method requires the use of a Sun javac compiler; it is suitable for callers that are willing to adopt a dependency on Sun's compiler in order to function in an untrusted environment.

    Note that it is possible to use the default binding method during development and deploy using the annotation processor.

Author:
gbrown, tvolkert
See Also:
BindProcessor

Nested Class Summary
protected static interface Bindable.Bind
          Annotation that causes a loaded WTKX element to be bound to the annotated field.
protected static interface Bindable.Load
          Annotation that causes the annotated field to be loaded via WTKX and bound to the field.
static interface Bindable.ObjectHierarchy
          Interface denoting a WTKX object hierarchy to which we can bind values.
 
Constructor Summary
protected Bindable()
          Creates a new Bindable object.
 
Method Summary
protected  void bind()
          Applies WTKX binding annotations to this object.
protected  void bind(Dictionary<String,Bindable.ObjectHierarchy> objectHierarchies)
          This is an internal method that callers should neither invoke nor override.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Bindable

protected Bindable()
Creates a new Bindable object.

Method Detail

bind

protected final void bind()
                   throws BindException
Applies WTKX binding annotations to this object. Subclasses should call this before they access their bound variables. Calling this more than once is legal; it will cause the annotated fields to be re-loaded and re-bound.

Note that by default, this method uses reflection to perform the binding. This may necessitate a call to setAccessible(true) on the bound field. If there is a security manager, its checkPermission method will correspondingly be called with a ReflectPermission("suppressAccessChecks") permission. This permission is not granted to un-trusted applets, meaning that this method of binding is not available to un-signed applets.

To mitigate this problem, a compile-time annotation processor, BindProcessor, is available and will cause this method to work without requiring the use of reflection. This in turn will eliminate any security issues with the binding process.

Throws:
BindException - If an error occurs during binding

bind

protected void bind(Dictionary<String,Bindable.ObjectHierarchy> objectHierarchies)
This is an internal method that callers should neither invoke nor override. It exists to support BindProcessor. Dealing directly with this method in any way may yield unpredictable behavior.