net.xoetrope.xui
Class XPageManager

java.lang.Object
  net.xoetrope.xui.XPageManager

public class XPageManager
extends java.lang.Object

A class for loading and displaying XPages. This class manages access to individual pages and coordinates update of the dispaly area. Pages can also be displayed as part of a frameset. The page manager caches the pages to improve performance and maintain state.

Copyright (c) Xoetrope Ltd., 2002-2003

License: see license.txt

$Revision: 2.16 $

Field Summary

protected static PageAnnotationProcessor	annotationProcessor A processor for page annotations
protected XProject	currentProject The owner project and the context in which this object operates.
protected java.lang.String	packageName The component package being used in this XProject instance (AWT or Swing)
protected XPageDisplay	pageDisplay XPageDisplay interface for showing pages
protected java.util.Stack	pageHistory The pageHistory Stack used to go 'back'
protected java.util.Hashtable	pageNameMap
protected java.util.Hashtable	pages Hashtable cache of used XPage Objects
protected java.util.Vector	secondaryLoaders Used to load pages from XML definition
protected boolean	triggerValidations A flag that controls whether or not validations are triggered on page transition

Constructor Summary

XPageManager(XProject project)
Constructor which creates a hastable to store the pages

Method Summary

void	addHistory(java.lang.String className) Add the page to the pageHistory stack
void	addSecondaryLoader(XPageLoader pl) Set the page loader class.
protected boolean	checkValidations(java.lang.String target) Check that the validations pass, provided that the validateOnPageTransition flag is set to true
PageSupport	getCurrentPage(java.lang.String target) Get the page currently displayed by a particular target container
int	getNumTargets() Get the number of frame/target from the current frameset
PageSupport	getPage(java.lang.String className) Get a page
PageSupport	getPreviousPage() Get the page previously displayed by the 'content' target container
java.lang.Object	getTarget(int idx) Get the target for a page display request
java.lang.Object	getTarget(java.lang.String name) Get a named frame/target from the current frameset
void	loadFrames(java.lang.String frameSetName, boolean useFrames) Loads a frameset.
PageSupport	loadPage(java.lang.String className) Load a page.
PageSupport	loadPage(java.lang.String className, boolean cache) Load a page.
PageSupport	loadPageAs(java.lang.String cacheName, java.lang.String className, boolean cache) Load a page and cache it under a name other than its page name.
protected void	logPageCreationError(java.lang.String className, java.lang.String message, java.lang.Exception e) Log the page creation error message
void	mapPageName(java.lang.String key, java.lang.String pageName) Set the page name used for a particular key.
void	reset() Reset the page history and dump any loaded pages.
void	setPackageName(java.lang.String pkgName) Set the package name.
void	setPageDisplay(XPageDisplay pgDisplay) Set the interface to invoke when a page has been displayed.
void	setTriggerValidations(boolean state)
PageSupport	showDialog(java.lang.Object parent, java.lang.String className, java.lang.String title, int x, int y) Load and show a dialog.
PageSupport	showPage(java.lang.String className) Load and show a page.
PageSupport	showPage(java.lang.String className, java.lang.String target) Load and show a page.
PageSupport	showPage(java.lang.String className, java.lang.String target, java.util.Hashtable attribs) Load and show a page.
PageSupport	showPrevious() Show the previously displayed page.
void	unloadPage(java.lang.String className) Remove a page from page cache.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

pages

protected java.util.Hashtable pages

Hashtable cache of used XPage Objects

packageName

protected java.lang.String packageName

The component package being used in this XProject instance (AWT or Swing)

pageHistory

protected java.util.Stack pageHistory

The pageHistory Stack used to go 'back'

pageDisplay

protected XPageDisplay pageDisplay

XPageDisplay interface for showing pages

secondaryLoaders

protected java.util.Vector secondaryLoaders

Used to load pages from XML definition

currentProject

protected XProject currentProject

The owner project and the context in which this object operates.

triggerValidations

protected boolean triggerValidations

A flag that controls whether or not validations are triggered on page transition

annotationProcessor

protected static PageAnnotationProcessor annotationProcessor

A processor for page annotations

pageNameMap

protected java.util.Hashtable pageNameMap

Constructor Detail

XPageManager

public XPageManager(XProject project)

Constructor which creates a hastable to store the pages

Parameters:

project - the owner project

Method Detail

setPackageName

public void setPackageName(java.lang.String pkgName)

Set the package name.

Parameters:

pkgName - the name of the package we're running from.

setPageDisplay

public void setPageDisplay(XPageDisplay pgDisplay)

Set the interface to invoke when a page has been displayed. Reads the startup parameters Frames and UsesFrames to control loading of the frame set. If Frames is not specified it defaults to "frames", and if UsesFrames is not specified it defaults to "true".

Parameters:

pgDisplay - The XPageDisplay interface

loadPage

public PageSupport loadPage(java.lang.String className)

Load a page. Check first to see if we have it in the Hashtable

Parameters:

className - the name of the class we want to load. If the new page is a dialog or a dialog derivative it is not cached

Returns:

The created or cached page

loadPage

public PageSupport loadPage(java.lang.String className,
                            boolean cache)

Load a page. Check first to see if we have it in the Hashtable when the cache flag is set to true.

Parameters:

className - the name of the class we want to load.

cache - whether or not to cache the page, or check the class being cached

Returns:

the cached page or the newly created page.

loadPageAs

public PageSupport loadPageAs(java.lang.String cacheName,
                              java.lang.String className,
                              boolean cache)

Load a page and cache it under a name other than its page name. Check first to see if we have it in the Hashtable when the cache flag is set to true.

Parameters:

cacheName - the name by which the page will be known in the cache

className - the name of the class we want to load.

cache - whether or not to cache the page, or check the class being cached

Returns:

the cached page or the newly created page.

unloadPage

public void unloadPage(java.lang.String className)

Remove a page from page cache.

Parameters:

className - the name of the class we want to remove.

logPageCreationError

protected void logPageCreationError(java.lang.String className,
                                    java.lang.String message,
                                    java.lang.Exception e)

Log the page creation error message

Parameters:

message - the error message

e - the exception

loadFrames

public void loadFrames(java.lang.String frameSetName,
                       boolean useFrames)

Loads a frameset. Check first to see if we have it in the Hashtable

Parameters:

frameSetName - the name of the frameSet we want to load.

useFrames - true to setup the frameset or false to add just a single target area

getPage

public PageSupport getPage(java.lang.String className)

Get a page

Parameters:

className - the page name

Returns:

the page or else null if the page hasn't been loaded yet.

getCurrentPage

public PageSupport getCurrentPage(java.lang.String target)

Get the page currently displayed by a particular target container

Parameters:

target - the target container name

Returns:

the page or else null if the page hasn't been loaded yet.

getPreviousPage

public PageSupport getPreviousPage()

Get the page previously displayed by the 'content' target container

Returns:

the page or else null if there wasn't a previous page

showPage

public PageSupport showPage(java.lang.String className)

Load and show a page.

Parameters:

className - The name, without package info, of the page to be displayed

Returns:

the page being displayed

showPage

public PageSupport showPage(java.lang.String className,
                            java.lang.String target)

Load and show a page.

Parameters:

className - The name, without package info, of the page to be displayed

target - the area to update

Returns:

the page being displayed

showPage

public PageSupport showPage(java.lang.String className,
                            java.lang.String target,
                            java.util.Hashtable attribs)

Load and show a page.

Parameters:

className - The name, without package info, of the page to be displayed

target - the area to update

attribs - attributes for use by the new page / taregt

Returns:

the page being displayed

showPrevious

public PageSupport showPrevious()

Show the previously displayed page.

Returns:

The previous XPage

showDialog

public PageSupport showDialog(java.lang.Object parent,
                              java.lang.String className,
                              java.lang.String title,
                              int x,
                              int y)

Load and show a dialog.

Parameters:

parent - the parent of this dialog or null.

className - The name, without package info, of the page to be displayed

title - the the dialog title

x - the x coordinate, or -1 for ignore/default location. Some widget set implementations may also support values of -2 for centered on screen

y - the location of the dialog on screen location is to be used. To centre the dialog on the mouse location, if the dialog is displayed in response to say a mouse event, the following code can be added:

      Point pt = (( MouseEvent )getCurrentEvent() ).getPoint();
      Point topLeft = myObject.getLocationOnScreen();
      pt.translate( topLeft.x, topLeft.y );
      pageMgr.showDialog( "MyDialog", translate( "MYDIALOG_TITLE" ), pt.x, pt.y );
 

Returns:

the page being displayed

checkValidations

protected boolean checkValidations(java.lang.String target)

Check that the validations pass, provided that the validateOnPageTransition flag is set to true

Parameters:

target - the target container name

Returns:

false if the validations were checked and found to fail, otherwise true

setTriggerValidations

public void setTriggerValidations(boolean state)

addSecondaryLoader

public void addSecondaryLoader(XPageLoader pl)

Set the page loader class. XuiBuilder is an example of a secondary page loader that loads pages from an XML description.

Parameters:

pl - the page loader instance

getTarget

public java.lang.Object getTarget(java.lang.String name)

Get a named frame/target from the current frameset

Parameters:

name - the name of the frame

Returns:

the target frame

getNumTargets

public int getNumTargets()

Get the number of frame/target from the current frameset

Returns:

the number of target frames

getTarget

public java.lang.Object getTarget(int idx)

Get the target for a page display request

Parameters:

idx - the target area

Returns:

the container to be updated

addHistory

public void addHistory(java.lang.String className)

Add the page to the pageHistory stack

Parameters:

className - The name, without package info, of the page to be displayed

reset

public void reset()

Reset the page history and dump any loaded pages.

mapPageName

public void mapPageName(java.lang.String key,
                        java.lang.String pageName)

Set the page name used for a particular key. For example a frameset might specify the startup page as HOME, only to have it remapped on startup to 'Welcome' or whatever is appropriate at the time. The XLifeCycleListener.initialize method may be used to set such parameters at startup

Parameters:

key - the lookup key

pageName - the mapped name