Page Manager and Page Broker Examples

Registering a PageHandler to a PageBroker to create the Page Tree

 

    To create the Page Tree, each node is responsible for registering subordinate nodes, starting with the root.  The root node is registered by the initalization of the system, the root node is responsible for registering all nodes 1 node deep on the tree.  Each of those nodes is responsible for registering nodes under it which are two nodes deep on the tree.  Lets look at an example.  

    Imagine a web application which two types of users can log into.  Administrators, and normal users.  When administrators log in, they are presented with the AdminMainMenu.  When normal users log in, they are presented with the UserMainMenu.  For the purposes of this example we'll keep this fairly concise and forget about what sorts of things might be on the UserMainMenu.  On the AdminMainMenu there might be a number of options.  Since users have to log into this web application, there certainly must be a way the admin can add users.  So lets Imagine there's an Enrollment link off the AdminMainMenu.  Off the Enrollment screen you could imagine an AddUser screen, a DeleteUser screen and a ModifyUser screen.  There's probably other links off the AdminMainMenu other then Enrollment too, lets say a screen to send messages to other logged in users, a SendMessage screen. If you take the sample web application I've described (which admittedly doesn't do much) and tried to describe it using a graphical tree, here's what it might look like:

 

    You'll notice that I've given each node on the tree a name.  The lingo we use to describe the name we give to each node is UID; an acronym that stands for Unique Identifier.  As you can imagine, there is no limitation to attaching a different "AddUser" node under UserMainMenu.  If we did that, it would be awfully confusing to know which one we were talking about if just called it the "AddUser" node.  That's why there a second way of addressing each node called the FQUID. An acronym that stands for Fully Qualified Unique Identifier. The FQUID of the AddUser node as drawn above is AdminMainMenu.AddUser.  A period delimits between the parent node names. Some people might find it ironic that you must "fully qualify" a unique identifier for it to be truly unique.  The theory is the UID is only unique at it's local level, as you cannot have two AddUser nodes attached to the same parent.

    Each node on the tree now represents a functional piece of this web application.  In the tree above, all of the nodes are PageHandlers.  The PageHandler interface simply means it is capable of rendering itself.  A PageBroker is a special kind of PageHandler which can also have zero or more children attached to it.  In the above case the Root, AdminMainMenu and UserMainMenu nodes are PageBrokers.  Adduser, DeleteUser, ModifyUser and SendMessage can be implemented as PageHandlers or PageBrokers with no children.  All nodes are PageHandlers, and this includes the root.  Customarily the RootPageBroker is the login page.  

    The tree is created when the RootPageBroker is instantiated by system initalization functions.  The RootPageBroker will in turn register AdminMainMenu and UserMainMenu.  The AdminMainMenu will in turn register each of it's children, AddUser, DeleteUser and ModifyUser.  Here's what might appear in the RootPageBroker to register the two nodes AdminMainMenu and UserMainMenu:

    

public class RootPageBroker extends PageBroker {
    public RootPageBroker(ManagerTracker MT, String fquid, PageBroker PB) throws TemplatePageException {
        super(MT,fquid,PB);
        //Register children nodes
        this.registerPageHandler("AdminMainMenu",new AdminMainMenu(MT,"Home", this));
        this.registerPageHandler("UserMainMenu",new UserMainMenu(MT,"UserMainMenu", this));
    }

    In this example we are calling the registerPageHandler method of the RootPageBroker.  The first argument is the name of the node being registered.  This is the UID value, and not the FQUID value.  The second parameter is the PageHandler (or PageBroker) object being registered.  The parameters for instantiating a PageBroker or PageHandler are not strictly defined by the java interface.  However, the superclass constructor for the PageBroker is strictly defined; so it would be wise to create the constructors of your PageBrokers and PageHandlers in the same fashion to avoid confusion.  In the PageBroker constructor used here, the first parameter is a pointer to the ManagerTracker.  The second parameter is the FQUID of the node, so the node will know it's own name.  In this case the FQUID is the same as the UID.  As you will see in other nodes, that's not always the case.  The third parameter is a pointer to the current node, this allows the Child to have a pointer to it's parent.  Lets look at the AdminMainMenu constructor:

     public class AdminMainMenu extends PageBroker {
        public AdminMainMenu(ManagerTracker MT, String fquid, PageBroker PB) throws TemplatePageException {
            super(MT,fquid,PB);
            this.registerPageHandler("AddUser",new AddUserBroker(MT,fquid+".AddUser", this));
            this.registerPageHandler("DeleteUser",new DeleteUserBroker(MT,fquid+".DeleteUser", this));
            this.registerPageHandler("ModifyUser",new ModifyUserBroker(MT,fquid+".ModifyUser", this));
        }

    In this case we can see the three children of the AdminMainMenu being added.  The only significant difference is you can see when the Brokers are being instantiated the FQUID value is being added to the UID value.  Also the period delimitor is added to seperate the FQUID value from the UID value.  

Examples from demo Site:
GeneralPageBroker

Asking the PageManager to handle a request

    When a request comes into the servlet, control is usually passed to the Page Manager, which then directs control to the appropriate node on the tree. Control can also be passed to the Page Manager again later in execution. You could imagine the need to perform an action, such as inserting a new user, then wanting to send the user back to a different node, such as the MainMenu.  There are two ways of doing this, passing control to the Page Manager, or passing control to a parent Page Broker.

Passing control to another node via the Page Manager:

 

public class SamplePageBroker extends PageBroker {

    public HTTPResponse render(TransactionTracker TT, HTTPRequest req, WebSession thisSession) throws ApolloException {
        //Perform some actions
        return MT.getPM().handleRequest(TT, "AdminMainMenu.AddUser", req, thisSession);
}

    As you can see control is passed off to the node AdminMainMenu.AddUser.  That node is now responsible for rendering a response to the user's browser.  As you can see, you're passing in a request object and a session object.  You may need to modify these prior to passing them.

Passing control via a Parent Page Broker

public class SamplePageBroker extends PageBroker {

    public HTTPResponse render(TransactionTracker TT, HTTPRequest req, WebSession thisSession) throws ApolloException {
        //Perform some actions
        return getParentPageBroker().handleRequest("AddUser", newRequest, thisSession);
}

Examples from the demo site:
StatusBarBroker

Creating a PageBroker

A page broker is a node on the Page Tree which can have children registered to it. This type of node extends the PageBroker class. Here's an example of a page broker from the demo site.  

Examples from the demo site:
GeneralPageBroker