net.xoetrope.builder
Class XuiBuilder

java.lang.Object
  extended by net.xoetrope.builder.XuiBuilder
All Implemented Interfaces:
XPageLoader

public class XuiBuilder
extends java.lang.Object

    
implements XPageLoader

    

A builder of XUI pages from an XML source. An instance of the class is setup by XApplet as a secondary page loader so that if a class file for the page is not found then an attempt is made to load the page from an XML file with the same base name.
Components, Menus, Events, Validations and Data Binding can be configured via the XML declarations.
The loading process itself relies heavily on the component factories to do the bulk of the work involved in constructing and adding components. The XPage class also performs much of the work involved in adding events and binding data.

Copyright (c) Xoetrope Ltd., 2002-2003

License: see license.txt

$Revision: 2.61 $


Field Summary
protected  WidgetAdapter adapter
           
protected  java.util.Hashtable attributeSets
           
protected  java.lang.Object checkBoxGroup
           
protected  XStyleFactory componentFactory
           
protected static java.util.Hashtable currentAttributes
           
protected  XProject currentProject
           
static java.lang.String DEFAULT_PAGE_CLASS
          The default class used to instantiate a page.
protected  XAttributeEvaluator evaluator
          The default attribute evaluator.
protected  java.lang.String includeFileName
           
protected  XLayoutHelper layoutHelper
           
protected  XAppender menuBar
           
protected  java.lang.String packageName
           
protected  PageSupport page
           
protected  PageSupport rootPage
           
protected  java.lang.ClassLoader secondaryClassloader
          A secondary classloader for attempts to load classes referenced by a page
protected  java.util.Hashtable validationFactories
           
 
Constructor Summary
XuiBuilder(XProject project)
          Construct an instance of the builder with the default package set to net.xoetrope.awt
XuiBuilder(XProject project, java.lang.String packageName)
          Construct a new builder and set the default package
 
Method Summary
protected  void addBindings(PageSupport page, XmlElement model)
          Adds data bindings to the page.
protected  java.lang.Object addComponent(XmlElement childNode)
          Adds an individual component element to the page (this method may be called recursively for nested elements).
protected  void addComponents(java.lang.Object page, XmlElement model)
          Adds the elements specified by the Components element and its children
protected  void addEvents(PageSupport page, XmlElement model)
          Adds the event handlers.
protected  void addHandler(PageSupport xpage, java.lang.Object targetComp, java.lang.String typeStr, java.lang.String name)
          Adds an event handler.
protected  void addMenu(PageSupport page, XmlElement model)
          Adds a menu to the application.
 void addMenuHandler(PageSupport xpage, java.lang.String targetStr, java.lang.String methodStr)
          Add a menu handler
 void addScripts(PageSupport page, XmlElement scriptsNode)
          Store the scripts in the page
protected  void addValidations(PageSupport page, XmlElement model)
          Adds validation rules to the components
 java.lang.Object evaluateAttribute(PageSupport page, java.lang.String attributeValue)
          Get the value of an attribute.
static java.util.Hashtable getCurrentAttributes()
          Get the table of component attributes
protected  XDataBinding getFactoryBinding(PageSupport page, java.lang.Object compType, XModel model, XmlElement bindingNode)
          Try to get a binding factory to construct the binding
protected  int getInt(java.lang.String s, int def)
          Convert a string to an int or else return the default value
protected  java.lang.Object getMenuItem(java.lang.String name)
          Gets a reference to a menu object
protected  XValidationFactory getValidationFactory(java.lang.String validationFileName)
          Construct a validation factory appropriate to this builder
protected  void init(java.lang.String packageName)
          Initialize the builder
 void insertAttributes(XmlElement node)
          Insert the attributes of a named attribute set into the node
 void loadAttributeSet(XmlElement childNode)
          Process an attribute element
protected  PageSupport loadClass(java.lang.String className)
          Loads a class as the basis for a page
 void loadFrames(java.lang.String defPackageName, java.lang.String frameSetName, XPageDisplay pageDisplay, boolean useFrames)
          Loads a frameset.
protected  void loadOtherElement(PageSupport page, XmlElement childNode)
          Load any element other than the predefined node types e.g.
 PageSupport loadPage(java.lang.String defPackageName, java.lang.String pageName, boolean include)
          Loads an XPage via a reader obtained from the XProject (searches the classpath).
protected  void loadSingleTarget(XPageDisplay pageDisplay)
          Load a single target, used in case a frameset is not loaded
 PageSupport readPage(java.io.Reader reader, java.lang.String pageName, boolean include)
          Read an XML description of the page and construct a new XPage.
static void registerBindingFactory(XDataBindingFactory fact)
          Register a data binding factory.
 void setAttributeEvaluator(XAttributeEvaluator e)
          Set the attribute evaluator object.
 void setClassLoader(java.lang.ClassLoader cl)
          Set a secondary classloader for loading the classes referenced by pages
protected  void setComponentAttributes(java.lang.String compType, java.lang.Object comp, java.util.Hashtable attribs)
          Iterate through the attributes and set the attributes for a component
 void setPackageName(java.lang.String defPackageName)
          Set the default package name.
 void setPageAttribute(java.lang.Object c, java.lang.String name, java.lang.String value)
          Get a page attribute (this version does nothing)
protected  void setPageName(java.lang.String pageName)
          Set the name of the page
protected  void setResourceBundle(PageSupport page, java.lang.String attribValue)
          Set the name of the page's resource bundle
protected  void setupPage(XmlElement model, java.lang.String pageName, boolean include)
          Loads the page based on the contents of the page tag or by using default values.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

packageName

protected java.lang.String packageName

componentFactory

protected XStyleFactory componentFactory

checkBoxGroup

protected java.lang.Object checkBoxGroup

page

protected PageSupport page

rootPage

protected PageSupport rootPage

menuBar

protected XAppender menuBar

validationFactories

protected java.util.Hashtable validationFactories

attributeSets

protected java.util.Hashtable attributeSets

currentAttributes

protected static java.util.Hashtable currentAttributes

layoutHelper

protected XLayoutHelper layoutHelper

currentProject

protected XProject currentProject

adapter

protected WidgetAdapter adapter

evaluator

protected XAttributeEvaluator evaluator
The default attribute evaluator. The evaluator can be replaced to support various ways of evaluating and interpreting dynamic attributes


secondaryClassloader

protected java.lang.ClassLoader secondaryClassloader
A secondary classloader for attempts to load classes referenced by a page


includeFileName

protected java.lang.String includeFileName

DEFAULT_PAGE_CLASS

public static final java.lang.String DEFAULT_PAGE_CLASS
The default class used to instantiate a page. As of XUI 2.0 the implementation of the page can be customized to suit different widget libraries.

See Also:
Constant Field Values
Constructor Detail

XuiBuilder

public XuiBuilder(XProject project)
Construct an instance of the builder with the default package set to net.xoetrope.awt

Parameters:
project - the current project

XuiBuilder

public XuiBuilder(XProject project,
                  java.lang.String packageName)
Construct a new builder and set the default package

Parameters:
project - the current project
packageName - the name of the default package e.g. net.xoetrope.awt
Method Detail

init

protected void init(java.lang.String packageName)
Initialize the builder

Parameters:
packageName - the default componnet package or use AWT if none is specified

setClassLoader

public void setClassLoader(java.lang.ClassLoader cl)
Set a secondary classloader for loading the classes referenced by pages

Specified by:
setClassLoader in interface XPageLoader
Parameters:
cl - the class loader

setPackageName

public void setPackageName(java.lang.String defPackageName)
Set the default package name. The default package name is used when creating widgets such that a button class like XButton is instatiated as .XButton.class. By default this expands to net.xoetrope.awt.XButton.clas

Specified by:
setPackageName in interface XPageLoader
Parameters:
defPackageName - the default package name

loadPage

public PageSupport loadPage(java.lang.String defPackageName,
                            java.lang.String pageName,
                            boolean include)
Loads an XPage via a reader obtained from the XProject (searches the classpath). The pageName is assumed to be the name of an XML file. For example if the pageName is 'welcome' then the 'welcome.xml' file is read as a UTF8 encoded XML file (by default).

Specified by:
loadPage in interface XPageLoader
Parameters:
defPackageName - the package or path to the page
pageName - the page name or the name of the class implementing the page
include - true if the page to be loaded is being included in another page in which case any class attribute of the included page is ignored
Returns:
the page

loadFrames

public void loadFrames(java.lang.String defPackageName,
                       java.lang.String frameSetName,
                       XPageDisplay pageDisplay,
                       boolean useFrames)
Loads a frameset. If a frameset is used then the calls to the XPageDisplay interface should use the form that specifies the target areas. By default frames are specified in a file (if found) called frames.xml. The frames are added to a container laid out with a BorderLayout.
Frames can be used to control how parts of the screen are updated. The default page updated by the page transition/swapping methods is the 'content' frame. Other areas can be used as non swapping areas for toolbars, navigation controls, sidebars or status areas. Frames may also be hidden and shown as needed.

Specified by:
loadFrames in interface XPageLoader
Parameters:
defPackageName - the package or path to the page
frameSetName - the page name or the name of the class implementing the page
pageDisplay - the object that will display the pages and frameset
useFrames - true to setup the frameset or false to add just a single target area

loadSingleTarget

protected void loadSingleTarget(XPageDisplay pageDisplay)
Load a single target, used in case a frameset is not loaded

Parameters:
pageDisplay - the object that will display the pages and frameset

readPage

public PageSupport readPage(java.io.Reader reader,
                            java.lang.String pageName,
                            boolean include)
Read an XML description of the page and construct a new XPage. An instance of the class specified by the class attribute is constructed or else an instance of XPage if no class attribute is specified. The new page is populated but is not yet added to its parent.
The startup file parameter 'DefaultClass' is used to obtain a default for each page's class if a class parameter is not specified in the page's XML
The startup file parameter 'Validations' is used to obtain a default for each page's set of validation rules

Parameters:
reader - a input stream from which to read the page
pageName - the name of the page
include - the page to be loaded is being included in another page
Returns:
the page

loadClass

protected PageSupport loadClass(java.lang.String className)
                         throws java.lang.ClassNotFoundException,
                                java.lang.IllegalAccessException,
                                java.lang.InstantiationException
Loads a class as the basis for a page

Parameters:
className - the full class name
Returns:
an instance of the XPage class or a derivative
Throws:
java.lang.ClassNotFoundException
java.lang.IllegalAccessException
java.lang.InstantiationException

loadOtherElement

protected void loadOtherElement(PageSupport page,
                                XmlElement childNode)
Load any element other than the predefined node types e.g. Component, Bindings etc... Allows an editor to insert extra data in the page, e.g. guides

Parameters:
page - the page currently being loaded
childNode - the xml element to process

setupPage

protected void setupPage(XmlElement model,
                         java.lang.String pageName,
                         boolean include)
Loads the page based on the contents of the page tag or by using default values.

Parameters:
pageName - the name of the page
include - the page to be loaded is being included in another page

setResourceBundle

protected void setResourceBundle(PageSupport page,
                                 java.lang.String attribValue)
Set the name of the page's resource bundle

Parameters:
page - the page that owns the resource
the - resource bundle name, minus any extension

setPageAttribute

public void setPageAttribute(java.lang.Object c,
                             java.lang.String name,
                             java.lang.String value)
Get a page attribute (this version does nothing)

Parameters:
c - the component associated with an attribute
name - the attribute name
value - the attribute value

loadAttributeSet

public void loadAttributeSet(XmlElement childNode)
Process an attribute element

Parameters:
attrElement - the attribute element

insertAttributes

public void insertAttributes(XmlElement node)
Insert the attributes of a named attribute set into the node

Parameters:
node - the node to be modified if it has an atttributes attribute

setAttributeEvaluator

public void setAttributeEvaluator(XAttributeEvaluator e)
Set the attribute evaluator object.

Parameters:
e - the new evaluator

evaluateAttribute

public java.lang.Object evaluateAttribute(PageSupport page,
                                          java.lang.String attributeValue)
Get the value of an attribute.

Parameters:
page - the page being loaded
attributeValue - the raw value of the attribute
Returns:
the evaluated value of the attribute

addComponents

protected void addComponents(java.lang.Object page,
                             XmlElement model)
Adds the elements specified by the Components element and its children

Parameters:
page - the new page object
model - the Components XML element (and implicitly its children)

addEvents

protected void addEvents(PageSupport page,
                         XmlElement model)
Adds the event handlers. Events are specified in the XML as having 'type' (e.g. MouseHandler, ActionHandler etc...), 'name' (the method name to be invoked) and 'target' (the name of the component to which the handler is attached) attributes

Parameters:
page - The page that contains the response methods
model - the 'events' XML element

addHandler

protected void addHandler(PageSupport xpage,
                          java.lang.Object targetComp,
                          java.lang.String typeStr,
                          java.lang.String name)
Adds an event handler.

Parameters:
xpage - The page that contains the response methods
targetComp - the component to which the event handler is added
typeStr - the type of handler
name - the name of the response method

addMenuHandler

public void addMenuHandler(PageSupport xpage,
                           java.lang.String targetStr,
                           java.lang.String methodStr)
Add a menu handler

Parameters:
xpage - the owner page
targetStr - the name of the menu/menuItem
methodStr - the name of teh response method

registerBindingFactory

public static void registerBindingFactory(XDataBindingFactory fact)
Register a data binding factory. An add-on library or plug-in may wish to customize the data bindings, particularly if it provides extended model node types. Such extended nodes may need adapters to be useful for some or all widgets and other binding contexts. Registration of the binding factory allows the necessary adapters and bindings to be created on request.

Parameters:
fact - the new binding factory

addBindings

protected void addBindings(PageSupport page,
                           XmlElement model)
Adds data bindings to the page.

Parameters:
page - the page to which the component/data bindings are added
model - the data model

getFactoryBinding

protected XDataBinding getFactoryBinding(PageSupport page,
                                         java.lang.Object compType,
                                         XModel model,
                                         XmlElement bindingNode)
Try to get a binding factory to construct the binding

Parameters:
page - the page that will own the binding
compType - the component type
model - the source data model
bindingNode - the XML element defining the binding
Returns:
the new binding if one could be constructed

setPageName

protected void setPageName(java.lang.String pageName)
Set the name of the page

Parameters:
pageName - the new page name.

addComponent

protected java.lang.Object addComponent(XmlElement childNode)
Adds an individual component element to the page (this method may be called recursively for nested elements). Several methods will be attempted until a component is successfully created. Firstly the built-in component types are checked, then any additional registered component constructors. The types can be specified by type ID, type name or class name.

Parameters:
childNode - the XML element containing the component specification.
Returns:
the new component

addMenu

protected void addMenu(PageSupport page,
                       XmlElement model)
Adds a menu to the application. Although specified in the XML as part of the page the menu is actually added to the application frame.

Parameters:
page - the page
model - the Menu XML element

addValidations

protected void addValidations(PageSupport page,
                              XmlElement model)
Adds validation rules to the components

Parameters:
page - the page
model - the Validations XML element

addScripts

public void addScripts(PageSupport page,
                       XmlElement scriptsNode)
Store the scripts in the page

Parameters:
page - the current page
scriptsNode - the scripts xml node

setComponentAttributes

protected void setComponentAttributes(java.lang.String compType,
                                      java.lang.Object comp,
                                      java.util.Hashtable attribs)
Iterate through the attributes and set the attributes for a component

Parameters:
comp - the component
attribs - the attributes.

getMenuItem

protected java.lang.Object getMenuItem(java.lang.String name)
Gets a reference to a menu object

Parameters:
name - the name of the menu item
Returns:
the named manu item

getValidationFactory

protected XValidationFactory getValidationFactory(java.lang.String validationFileName)
Construct a validation factory appropriate to this builder

Parameters:
validationFileName - the validations file to read
Returns:
the validation factory

getInt

protected int getInt(java.lang.String s,
                     int def)
Convert a string to an int or else return the default value

Parameters:
s - the number as a string
def - the default value
Returns:
the converted value

getCurrentAttributes

public static java.util.Hashtable getCurrentAttributes()
Get the table of component attributes

Returns:
the attributes hash table.