net.xoetrope.builder
Class XuiBuilder

java.lang.Object
  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

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

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

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.