net.xoetrope.builder
Class XuiBuilder

java.lang.Object
  net.xoetrope.builder.XuiBuilder

All Implemented Interfaces:

XPageLoader

Direct Known Subclasses:

XHtmlBuilder

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-2007

License: see license.txt

$Revision: 2.59 $

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
protected ComponentCustomizer	customizer
static java.lang.String	DEFAULT_PAGE_CLASS The default class used to instantiate a page.
protected XAttributeEvaluator	evaluator The default attribute evaluator.
protected XuiEventHandler	eventHandler
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	addBinding(XmlElement childNode) Adds data bindings to the page.
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	addEvent(XmlElement childNode) Adds the event handlers.
protected void	addEvents(PageSupport page, XmlElement model) Adds the event handlers.
void	addHandler(PageSupport xpage, java.lang.Object targetComp, java.lang.String typeStr, java.lang.String methodName) Adds an event handler.
protected void	addMenu(PageSupport page, XmlElement model) Adds a menu to the application.
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.
java.lang.String	evaluateAttributeAsString(PageSupport page, java.lang.String attributeValue) Get the value of an attribute.
static java.util.Hashtable	getCurrentAttributes() Get the table of component attributes
XDataBinding	getFactoryBinding(PageSupport page, java.lang.Object compType, java.util.Hashtable instanceConfig) 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
boolean	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
void	popIncludeReference(java.lang.String includeFileName) A method that the editor can overload to keep track of includes
void	popRepeatReference(java.lang.String includeFileName) A method that the editor can overload to keep track of repeats
void	pushIncludeReference(java.lang.String includeFileName) A method that the editor can overload to keep track of includes
void	pushRepeatReference(java.lang.String includeFileName) A method that the editor can overload to keep track of repeats
PageSupport	readPage(java.io.Reader reader, java.lang.String pageName, java.lang.String ext, boolean include) Read an XML description of the page and construct a new XPage.
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	setPage(PageSupport p) Set the current page
void	setPageAttribute(java.lang.Object c, java.lang.String name, java.lang.String value) Get a page attribute (this version does nothing)
protected void	setPageExtension(java.lang.String ext) Set the file extension of the page
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, java.lang.String ext, 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

customizer

protected ComponentCustomizer customizer

evaluator

protected XAttributeEvaluator evaluator

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

eventHandler

protected XuiEventHandler eventHandler

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

setPage

public void setPage(PageSupport p)

Set the current page

Specified by:

setPage in interface XPageLoader

Parameters:

p - the page object

Since:

3.0

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 boolean 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

Returns:

true if a frameset is loaded

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,
                            java.lang.String ext,
                            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

Specified by:

readPage in interface XPageLoader

Parameters:

reader - a input stream from which to read the page

pageName - the name of the page

ext - the file extension

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,
                         java.lang.String ext,
                         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

ext - the file extension

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

evaluateAttributeAsString

public java.lang.String evaluateAttributeAsString(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

addEvent

protected void addEvent(XmlElement childNode)

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:

childNode - the 'events' XML element

addHandler

public void addHandler(PageSupport xpage,
                       java.lang.Object targetComp,
                       java.lang.String typeStr,
                       java.lang.String methodName)

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

methodName - the name of the response method

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

addBinding

protected void addBinding(XmlElement childNode)

Adds data bindings to the page.

Parameters:

model - the data model

getFactoryBinding

public XDataBinding getFactoryBinding(PageSupport page,
                                      java.lang.Object compType,
                                      java.util.Hashtable instanceConfig)

Try to get a binding factory to construct the binding

Parameters:

currentProject - the current project

page - the page that will own the binding

compType - the component type

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.

setPageExtension

protected void setPageExtension(java.lang.String ext)

Set the file extension of the page

Parameters:

ext - the new file extension.

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.

pushIncludeReference

public void pushIncludeReference(java.lang.String includeFileName)

A method that the editor can overload to keep track of includes

popIncludeReference

public void popIncludeReference(java.lang.String includeFileName)

A method that the editor can overload to keep track of includes

pushRepeatReference

public void pushRepeatReference(java.lang.String includeFileName)

A method that the editor can overload to keep track of repeats

popRepeatReference

public void popRepeatReference(java.lang.String includeFileName)

A method that the editor can overload to keep track of repeats