org.jdesktop.jdnc.form
Class JForm

java.lang.Object
  extended by java.awt.Component
      extended by java.awt.Container
          extended by javax.swing.JComponent
              extended by javax.swing.JPanel
                  extended by org.jdesktop.jdnc.form.JForm
All Implemented Interfaces:
java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, javax.accessibility.Accessible

public class JForm
extends javax.swing.JPanel

Form component class for enabling display, editing, and actions on a collection of data fields, each of which corresponds to an identifiable element within an application data model. For example, a form field may map to a named column on a RowSet, a property on a JavaBean, or a keyed element in a map, etc. A single form can be used to display/edit data fields from multiple data models.

For each data field in the form, a user-interface component is created to display and edit (if field is writable) values for that field in the data model. Each user-interface component is "bound" to the data model field using a Binding instance, which handles the following tasks:

Changed (JW): the Form can handle non-visual data fields - will not create a component/binding if the metaData customProperty DataConstants.NON_VISUAL_FIELD is set to Boolean.TRUE. To use the Form component, an application need only bind the form to the desired fields on its data models, and by default the form will handle creating the necessary user-interface components and bindings, and will add those components to the form using a standard layout scheme. Applications generally should not need to interact directly with the component or binding objects at all. For example, the following code creates a form which can display/edit each column in a DefaultTableModelExt (and in the future, a RowSet):

     DefaultTableModelExt data = new DefaultTableModelExt("http://foo.bar/appdata");
     JForm form = new JForm();
     try {
          form.bind(data); // creates components/bindings for all columns
     } catch (BindException e) {
     }
 
Once the form is created and bound, as in the example above, the form handles execution of the binding operations as the user interacts with the user-interface components in the form.

The following is an example which shows how a form is bound to multiple data models:


     Customer customer = new Customer();
     Cart cart = new Cart();

     JForm form = new JForm();
     try {
         form.bind(customer, "firstName");  // binds to "firstName" property
         form.bind(customer, "lastName"); // binds to "lastName" property
         form.bind(customer, "address"); // binds to "address" property (nested bean)
         form.bind(cart, "items"); // binds to "items" property
     } catch (BindException e) {
     }
 

Version:
1.0
Author:
Amy Fowler
See Also:
Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class javax.swing.JPanel
javax.swing.JPanel.AccessibleJPanel
 
Nested classes/interfaces inherited from class javax.swing.JComponent
javax.swing.JComponent.AccessibleJComponent
 
Nested classes/interfaces inherited from class java.awt.Container
java.awt.Container.AccessibleAWTContainer
 
Nested classes/interfaces inherited from class java.awt.Component
java.awt.Component.AccessibleAWTComponent, java.awt.Component.BltBufferStrategy, java.awt.Component.FlipBufferStrategy
 
Field Summary
 
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
 
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
 
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
 
Constructor Summary
JForm()
          Creates a new form component.
JForm(DataModel model)
          Creates a new form component and binds it to the specified data model.
 
Method Summary
protected  void addBinding(Binding binding)
          Added to ease subclassing without actually exposing the private bindings-list.
 Binding bind(Binding binding, javax.swing.JComponent component)
          Adds the specified binding to this form.
 Binding[] bind(DataModel model)
          Binds the form to each visual field in the specified DataModel object.
 Binding bind(DataModel model, java.lang.String fieldName)
          Binds the form to the specified field in the DataModel object.
 Binding bind(DataModel model, java.lang.String fieldName, javax.swing.JComponent component)
          Binds the specified component to the field in the DataModel object.
 Binding[] bind(DefaultTableModelExt tabularData)
          Binds the form to each column in the specified DefaultTableModelExt object.
 Binding bind(DefaultTableModelExt tabularData, java.lang.String columnName)
          Binds the form to the specified column in the DefaultTableModelExt object.
 Binding[] bind(java.lang.Object bean)
          Binds the form to each property in the specified JavaBean object.
 Binding bind(java.lang.Object bean, java.lang.String propertyName)
          Binds the form to the specified property in the JavaBean object.
 void clearBindings()
          Removes all the bindings from the form.
 void doReset()
          Public callback for reset action.
 void doSubmit()
          Public callback for submit action.
protected  void executeSubmit()
          Invoked from the submit action if and only if all form component values were successfully pushed to the form's data model.
 boolean getAutoLayout()
           
 BindingHandler getBindingHandler()
          quickshot to get hold of handler...
 Binding[] getBindings()
           
 FormFactory getFormFactory()
          If the form factory was never explicitly set, this method will return the default FormFactory instance obtained from FormFactory:getDefaultFormFactory().
protected  void initActions()
           
 boolean isFormValid()
           
 boolean isModified()
           
 boolean pull()
          For each binding defined in this form, pull the value from the data model and load it into the user-interface component.
 boolean push()
          If all form fields are in a valid state, push each value contained in a user-interface component its associated data model.
 void setAutoLayout(boolean autoLayout)
          Sets the "autoLayout" property.
 void setFormFactory(FormFactory factory)
          Sets the form factory for this form.
 void unbind(Binding binding)
          Removes the specified binding from this form.
 
Methods inherited from class javax.swing.JPanel
getAccessibleContext, getUI, getUIClassID, paramString, setUI, updateUI
 
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
 
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
 
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

JForm

public JForm()
Creates a new form component.


JForm

public JForm(DataModel model)
      throws BindException
Creates a new form component and binds it to the specified data model.

Parameters:
model - data model whose fields should be bound in this form
Throws:
BindException - if there were errors when binding to the data model
Method Detail

initActions

protected void initActions()

setAutoLayout

public void setAutoLayout(boolean autoLayout)
Sets the "autoLayout" property. The default is true. If set to false, then the application must take responsibility for adding the bound user-interface components to the form.

Parameters:
autoLayout - boolean value indicating whether or not the components created and bound in this form are automatically added to and layed out in the form
See Also:
getAutoLayout()

getAutoLayout

public boolean getAutoLayout()
Returns:
boolean value indicating whether or not the components created and bound in this form are automatically added to and layed out in the form
See Also:
setAutoLayout(boolean)

setFormFactory

public void setFormFactory(FormFactory factory)
Sets the form factory for this form.

Parameters:
factory - FormFactory instance used to create the components and bindings for data model fields bound to the form

getFormFactory

public FormFactory getFormFactory()
If the form factory was never explicitly set, this method will return the default FormFactory instance obtained from FormFactory:getDefaultFormFactory().

Returns:
FormFactory instance used to create the components and bindings for data model fields bound to the form

bind

public Binding[] bind(DefaultTableModelExt tabularData)
               throws BindException
Binds the form to each column in the specified DefaultTableModelExt object. The bind operation will create the best user-interface components to display/edit the data model values based on each column's MetaData object. It will also create the bindings from those user-interface components to the data model. And finally, if "autoLayout" is true, it will also add and layout those components within the form according to the mechanism defined by the form factory.

Parameters:
tabularData - DefaultTableModelExt being bound to the form
Returns:
array of Binding instances created from bind operation
Throws:
BindException - if there were errors when binding to the data model
See Also:
MetaData

bind

public Binding bind(DefaultTableModelExt tabularData,
                    java.lang.String columnName)
             throws BindException
Binds the form to the specified column in the DefaultTableModelExt object. The bind operation will create the best user-interface component to display/edit the data model value based on the column's MetaData object. It will also create the binding from the user-interface component to the data model. And finally, if "autoLayout" is true, it will also add and layout the component within the form according to the mechanism defined by the form factory.

Parameters:
tabularData - DefaultTableModelExt being bound to the form
columnName - String containing the name of the column
Returns:
Binding instance created from bind operation
Throws:
BindException - if there were errors when binding to the data model

bind

public Binding[] bind(java.lang.Object bean)
               throws BindException
Binds the form to each property in the specified JavaBean object. The bind operation will create the best user-interface components to display/edit the data model values based on each property's description. It will also create the bindings from those user-interface components to the data model. And finally, if "autoLayout" is true, it will also add and layout those components within the form according to the mechanism defined by the form factory.

Parameters:
bean - JavaBean object being bound to the form
Returns:
array of Binding instances created from bind operation
Throws:
BindException - if there were errors when binding to the data model

bind

public Binding bind(java.lang.Object bean,
                    java.lang.String propertyName)
             throws BindException
Binds the form to the specified property in the JavaBean object. The bind operation will create the best user-interface component to display/edit the data model value based on the property's description. It will also create the binding from the user-interface component to the data model. And finally, if "autoLayout" is true, it will also add and layout the component within the form according to the mechanism defined by the form factory.

Parameters:
bean - JavaBean object being bound to the form
propertyName - String containing the name of the property
Returns:
Binding instance created from bind operation
Throws:
BindException - if there were errors when binding to the data model

bind

public Binding[] bind(DataModel model)
               throws BindException
Binds the form to each visual field in the specified DataModel object. The bind operation will create the best user-interface components to display/edit the data model values based on each field's MetaData object. It will also create the bindings from those user-interface components to the data model. And finally, if "autoLayout" is true, it will also add and layout those components within the form according to the mechanism defined by the form factory.

Parameters:
model - DataModel object being bound to the form
Returns:
array of Binding instances created from bind operation
Throws:
BindException - if there were errors when binding to the data model

bind

public Binding bind(DataModel model,
                    java.lang.String fieldName)
             throws BindException
Binds the form to the specified field in the DataModel object. The bind operation will create the best user-interface component to display/edit the data model value based on the field's MetaData object. It will also create the binding from the user-interface component to the data model. And finally, if "autoLayout" is true, it will also add and layout the component within the form according to the mechanism defined by the form factory.

Parameters:
model - DataModel object being bound to the form
fieldName - String containing the name of the field
Returns:
Binding instance created from bind operation. Will be null for non-visual fields.
Throws:
BindException - if there were errors when binding to the data model

bind

public Binding bind(DataModel model,
                    java.lang.String fieldName,
                    javax.swing.JComponent component)
             throws BindException
Binds the specified component to the field in the DataModel object. This bind operation will attempt to create a Binding instance appropriate for the specified component. If it is unable to do so, a BindException will be thrown. This method can be used when the application wishes to control the type of user-interface component used to display/edit the data model field.

Parameters:
model - DataModel object being bound to the form
fieldName - String containing the name of the field
component - user-interface component being bound to the data model
Returns:
Binding instance created from bind operation
Throws:
BindException - if there were errors when binding to the data model

bind

public Binding bind(Binding binding,
                    javax.swing.JComponent component)
             throws BindException
Adds the specified binding to this form. The user-interface component is the one which should be added to the form if the "autoLayout" property is true. Note that this component may be different from the component which is contained in the Binding instance. This method is invoked by the other bind methods and is typically not invoked directly by applications unless they require the ability to create their own Binding objects.

Parameters:
binding - Binding instance being added to this form
component - user-interface component which should be added to the form
Returns:
Binding instance created from bind operation
Throws:
BindException - if there were errors when binding to the data model

addBinding

protected void addBinding(Binding binding)
Added to ease subclassing without actually exposing the private bindings-list.

Parameters:
binding -

unbind

public void unbind(Binding binding)
Removes the specified binding from this form.

Parameters:
binding - Binding instance being removed

getBindingHandler

public BindingHandler getBindingHandler()
quickshot to get hold of handler...

Returns:

clearBindings

public void clearBindings()
Removes all the bindings from the form.


getBindings

public Binding[] getBindings()
Returns:
array containing all Binding objects currently in this form

pull

public boolean pull()
For each binding defined in this form, pull the value from the data model and load it into the user-interface component.

Returns:
boolean indicating whether or not the data model values were successfully pulled into the user-interface components

isFormValid

public boolean isFormValid()
Returns:
boolean value indicating whether or not all fields in this form have a valid state

isModified

public boolean isModified()
Returns:
boolean value indicating whether or not any form field values have pending edits in the user-interface components since the last time values were pulled or pushed.

doSubmit

public void doSubmit()
Public callback for submit action.


doReset

public void doReset()
Public callback for reset action.


push

public boolean push()
If all form fields are in a valid state, push each value contained in a user-interface component its associated data model.

Returns:
boolean indicating whether or not the form field values were successfully pushed to the data models
See Also:
isFormValid()

executeSubmit

protected void executeSubmit()
Invoked from the submit action if and only if all form component values were successfully pushed to the form's data model.



Copyright © 2005 Sun Microsystems All Rights Reserved.