White Paper: WebLogic Portal Framework

BEA WebLogic Portal Framework

Abstract

This document is intended to give an in depth overview of the technical underpinnings of the portal framework. It is targeted towards developers who have a deep J2EE background and are already familiar with WebLogic Portal.

This document is intended to be used as a supplement to the online documentation and assumes you have already immersed your self in it and are looking for more technical substance. This document will only discuss portal framework and not directly talk about the interaction with WebLogic Workshop, the WebLogic Administration Portal or any of the other features that come with WebLogic Portal; namely: Personalization, Campaigns, Content Management, Commerce Components, Entitlements and User Management. Many features described in this document have not made their way into WebLogic Workshop or the WebLogic Administration Portal as of this writing. Nonetheless, we encourage you to explore these features.

Definition of Terms, Acronyms, and Abbreviations

It is important that we first define a set of terminology, as we will be using these terms throughout the document. Please take the time to become familiar with these concepts.

Netui; Netuix; Customization; Portal Framework; Light Portal (File-based Portal); UIControl; Single File vs. Streamed Rendering; Library

Netuix

Controls

As stated earlier, netuix is an XML framework for rendering applications, whether these applications look like portals or not. Many customers who use our product today create applications from our framework that look nothing like a portal. Typically when people think of portals they think of "My Yahoo!". While many applications developed with netuix look like My Yahoo!, many do not.

A netuix application is represented by one or more XML documents, the most familiar being the .portal file (an XML file with a .portal extension). This portal file may or may not include other portal include files, called .pinc files for short (files with the extension .pinc). Just like a JSP can include other JSP files to distribute functionality, a portal file can include other portal files.

A .pinc file is different from a portal file in that a portal includes the root elements or controls while the .pinc file does not. We will discuss this in more detail later. However, for this discussion the portal file is the parent, and it may in turn include one or more .pinc files, which in turn may include other .pinc files. One other important note: a .pinc file must begin with a Book or a Page element as the root element. More on what Books and Pages are in a bit.

In the portal file, you can think of each element representing an instance of a UI control. (UIControls are not to be confused with business controls in Workshop.)These controls are wired in a hierarchical tree. In other words, each control has a parent and zero or more children. The controls can discover each other at runtime and can modify the tree by adding new children or removing existing children. All controls run through a lifecycle (a set of methods called on the control in a particular order). All the methods are called in turn in a depth first order.

To best illustrate this, let's walk through the sequence of events that happen when a person requests a portal in single file mode from the browser. But before we do that, we first need to cover a few architectural issues with the portal framework. All requests for a portal or desktop come in through the PortalServlet. The PortalServlet is registered in the web.xml file under the url-patterns appmanager and *.portal. If the PortalServlet detects a request ending with .portal it knows the request is for a locale file and does not need to go to the persistence API for the XML.

The first thing the PortalServlet must do is parse the XML file (.portal) and generate a control tree from it. Every element in the portal file represents a control in the control tree, and every attribute on the element represents an instance variable on the control. The same hierarchy is maintained in the XML document as in the control tree. A control is simply a Java class that extends another Java class, namely the UIControl class. In this release we don't explicitly expose controls to developers, but developers can interact with the controls using backing files, context, and skeleton JSPs. This is discussed later.

Note: The PortalServlet doesn't actually parse the XML document on each request. A lot of caching and magic is going on behind the scenes to get the desired performance for the enterprise applications.

Once the control tree is built and all the instance variables are set on the controls, the control tree is run through its lifecycle. The lifecycle can be thought of as a set of methods on the controls that are called on in a well-defined order. The lifecycle methods are as follows:

init()
loadState()
handlePostbackData()
raiseChangeEvents()
preRender() 
saveState()
render()  
dispose()

These methods are called in depth first order. In other words, all the init() methods are called, followed by the loadState() methods, and so on. They will also be called depth first. Example, given the following control tree, the order in which the init() method would be called is: C1, C2, C5, C3, C6, C7, C4, then the loadState() method would be called in the same order, and so on.

The last method to be called would be C4's dispose():

body.html

Portal Controls

This section describes all the netuix controls that make up the portal framework. The control relationship is driven by the XML schema definition controls-netuix-1_0_0.xsd. The following figure summarizes the schema definition.

Desktop

The Desktop control is the parent control that hosts all the other netuix controls. Every portal must have one Desktop control. The Desktop control actually provides little functionality above and beyond entitlement checking and a place to go to discover other controls.

The most important use of the Desktop control from a developer perspective is that it has a PresentationContext that can be traversed to get references to all the child controls, like books, pages, and portlets. A DesktopBackingContext was added in 8.1 sp3 along with a richer set of methods for locuting child controls.

Windows

A Window control provides functionality similar to the windowing concept on your computer. Windows support States and Modes. States affect the rendering of the Window, like minimize, maximize, float, and delete. Modes affect the content, like Edit and Help. (Custom modes are also supported.) Windows can also act as a container for other Windows. For example, a book can contain a page.

All Window controls must have a Content control. The Content control is responsible for hosting the actual content inside the window. The Window control is an abstract class that is one of the three derived classes that must be used in the portal. These derived classes are: Books, Pages and Portlets. The figure below shows the relationship between Windows, Books, Pages and Portlets.

body.html

Book

A Book aggregates a set of navigables. A navigable is a Book or a Page. A Book may have an optional menu control that provides navigation among navigables. From a code standpoint, Navigable is an interface that Book and Page implement.

Page

A Page is used to display a set of Placeables. A Placeable is a Portlet or Book. The Page has a layout which has one or more Placeholders which can host zero or more Placeables.

Portlet

Portlets are used as windows to host may different types of applications. As of this writing the applications can be any one of following: HTML pages, JSP files, .pinc files, Page Flows, Struts, Webflows, JSR 168 Portlets, and WSRP proxy portlets.

Menus

Menus are optional components that are loosely coupled to books and pages. A menu is responsible for displaying some type of navigation component, whether it is a set of tabs, a set of links, or some tree structure. The menu fires PageChaneEvents that the Pages themselves listen to and activate accordingly.

At the time of this writing, WebLogic Portal provides two types of menus: singlelevel and multilevel. Future service packs and releases may include more. You can also create you own menus by using JSPs and the <render:pageUrl/> tag, or from a backing file call the setupPageChangeEvent method an a Book, Page or Portlet backing context before the preRender method.

SingleLevelMenu

Provides a single row of tabs for the book's immediate pages and child books.

MultiLevelMenu

Recursively provides a hierarchical menu for all the books and pages contained within a book. This menu does not stop at the first set of children. It continues down the tree. If the parent book uses a multilevelmenu, then the child books should not use a menu as the multilevelmenu will cover them.

Layouts

Layouts and Placeholders (not to be confused with personalization placeholders) are used to structure the way portlets and books are displayed on a page. Layout placeholders are rendered as HTML table cells.

WebLogic Portal ships with some predefined layouts and the ability to create your own custom layouts. More layouts will probably be shipped in future service packs and future releases. If the supplied layouts don't meet your needs, you will have to create your own custom layout. The next section describes that process in detail.

Information for Creating a Custom Layout

When creating a custom layout you will need to create three things:

The Layout File

The layout file contains the snippet of XML that describes the controls that make up the layout. The markup from this file is what gets copied into the .portal file and into the database for reassembly. A layout file must have a .layout extension and can live anywhere in the Web application directory except WEB-INF.

Note: Changes made to a layout file after it has been created get picked up automatically in the database but will not automatically update the layout in the .portal files. This is because the .portal file contains a copy of the markup and not a reference to it.

The .layout files must be created by hand (text or XML editor). The best way to get started is by copying an existing layout. Layout files shipped with the portal are located in the /framework/markup/layout directory.

Layout File Elements

The parent element for all markup types is:

<netuix:markupDefinition/>

This parent element has two child elements:

<netuix:locale language="nn" [country="nn"] [variant="nnnn"]/>

Defines the working local for the title and description attributes defined later.

<netuix:markup>

Defines the outer envelope stanza that marks the beginning and end of the XML that will define this layout.

Basic Layout Controls

The next set of elements are unique to a layout. When creating your own layout you will have to choose from one of these four base layout controls. The <netuix:layout/> is the most generic of the four and all others are derived from it. The <netuix:layout/> control provides the most flexibility but is also the most difficult to implement.

<netuix:layout title="" [description=""] type = "" htmlLayoutUri="" [iconUri=""] markupName="" markupType="Layout" [skeletonUri=""] [properties=";"]/>

This is the base control for all layouts. This control can be used directly or you can use one of the following three derived controls.

body.html

Attribute	Description
title	This is the internationalized title displayed to the user and administrators when selecting the layout they want to use. Note: The developer only works in one language as defined in the `<netuix:locale>` element described previously. More internationalized versions of the title and description can be added later with the WebLogic Administration Portal.
description	An optional internationalized description of your layout.
type	The type of layout. This is hard coded for the three derived layouts. If you create a custom come up with your own type.
htmlLayoutUri	A fully qualified path (from the top of the Web application) to the html.txt file to be used by the WebLogic Administration Portal.
properties	"name/value pairs that can be passed to the skeleton as hints. These properties can be separated using a semicolon ";".
iconUrl	A fully qualified path (from the top of the Web application) to the `.gif` file to be used by the WebLogic Administration Portal.
markType	This field is required and must be "Layout".
markupName	This field is required and must be unique per Web application. If you copied the XML from another layout you must change this name.
skeletonUri	A fully qualified path (from the top of the Web application) to the skeleton JSP to be used for runtime rendering.
presentationClass	Optionally provides a generic presentation "class," such as a CSS class, for use by external rendering devices.
presentationStyle	Optionally provides a generic presentation "style," such as a CSS style, for use by external rendering devices.
presentationId	Optionally provides a generic presentation "id" for use by external rendering devices.

<netuix:gridLayout columns="(1-n)" [rows = "1-n"] /> Attributes

This layout defines a grid where you can specify the number of columns and rows. This layout is typically used to create one, two , three, column layouts.

Attribute	Description
columns	A required attribute that identifies the number of columns in the grid
rows	An optional attribute specifying the number of rows in the grid. If this attribute is omitted then the default one row will be used

<netuix:borderLayout [layoutStrategy="order | title" ] /> Attributes

This layout has four border placeholders and one center placeholder. The north and south

placeholders span the length of the table. The west, center, and east placeholders comprise the middle row and have respective widths of 25, 50, and 25 percent. The north and south portlets flow horizontally in the placeholders, and the others flow vertically.

Attribute	Description
layoutStragety	Defines what placeholder will be the north, west, center, east and south. If "title" is specified then each placeholders must specify the correct title.

<netuix:flowLayout [orientation="vertical | horizontal"]/> Attributes

A layout that just flows the contents in a vertical or horizontal fashion.

Attribute	Description
orientation	Flow the contents vertical or horizontal. Layout controls contain one or more child placeholder controls. These controls have the following attributes.

Attribute

Description

orientation

Flow the contents vertical or horizontal.

Layout controls contain one or more child placeholder controls. These controls have the following attributes.

<netuix:placeholder title="" [description=""] [flow="horizontal | vertical"] [usingFlow=""] [width=""] markupName="" markupType="Placeholder" [skeletonUri=""]/>

Placeholders are child elements of the above four types of layouts. Every layout must have at least one placeholder child element. Each placeholder has a "layout location." Thie loayout location is defined by its position inside the layout files. Layout locations start at 0, 1, 2.

Attribute	Description
title	This is the internationalized title displayed to the user and administrators when selecting the placeholder they want to use. Note: The developer only works in one language as defined in the <netuix:locale> element described above. More internationalized versions of the title and description can be added later using the WebLogic Administration Portal.
description	An optional internationalized description of your placeholder.
markType	This field is required and must be "Placeholder".
markupName	This field is required and must be unique per Web application. If you copied the XML from another layout you must change this name. The naming convention is layoutMarkupName_placeholdersName, but you can use what you want as long as it is unique.
skeletonUri	A fully qualified path (from the top of the Web application) to the skeleton JSP to be used for runtime rendering. Typically the default skeleton will suffice for all custom layouts, but you have the option to create your own.
flow	An optional value specifying the direction of content flow; default is "vertical."
usingFlow	An optional value specifying whether or not flow should be used; default is "true."
width	An optional hint attribute to tell the parent layout how much width this placeholder wishes to have allocated.
properties	Name/value pairs that can be passed to the skeleton as hints. These properties can be separated using a semicolon ";". Example: `properties="rowspan=2;columnspan=3;myprop=hello"`

Example of a Custom Layout

Now that we have described the four basic layout controls and child placeholder controls, you will have to choose which one of these to base your custom layout on. Unless you are tweaking one of the parameters in the three sub-class layout controls, you may want to choose the <netuix:layout> control.

The easiest way to describe how to create a custom layout is to give an example. Lets create a custom layout with a spanning row at the top with two columns underneath. The two columns will split the real estate in a 30%-70% fashion.

Our layout will look something like this:

body.html

The first thing we need to do is create a layout file (again the easiest way is to copy one from another layout).

We will call our layout file spanningtwocolumn.layout, and it will look something like this:

Listing 1 Sample Code for a Layout File

<netuix:layout title="Spanning Two Column" description="One row and two columns."
    type="spanning" 
    skeletonUri="/customskeletons/spanningtwocolumnlayout.jsp"
    htmlLayoutUri="/framework/markup/layout/spanningtwocolumn.html.txt"
    iconUri="/framework/markup/layout/spanningtwocolumn.gif"
    markupType="Layout" markupName="spanningTwoColumnLayout">
        <netuix:placeholder title="top" description="The top spanning placeholder."
                            markupType="Placeholder" 
                            markupName="spanningTwoColumn_top">
        </netuix:placeholder>
        <netuix:placeholder title="left" description="The bottom left placeholder"
                            markupType="Placeholder"
                            markupName="spanningTwoColumn_left">
        </netuix:placeholder>
        <netuix:placeholder title="right" description="The bottom right placeholder"
                            markupType="Placeholder"     
                            markupName="spanningTwoColumn_right">
        </netuix:placeholder>
</netuix:layout>

The <netuix:markupDefinition>, <netuix:locale/> and <netuix:markup/> elements were left out of the example for the sake of clarity. DON'T forget to include these in your .layout file.

In the previous layout example we are using the <netuix:layout/> element, and we have three placeholders underneath it. Other things to note are the markupNames are unique, and we have identified our own custom skeleton to do the rendering.

The Skeleton JSP

Since a custom skeleton is being used to do the rendering (as specified by the skeletonUri attribute) this JSP needs to be created. Again, the easiest way is to copy an existing one.

Note: The skeleton JSP for the control is called twice: once during "begin render" and once for "end render." Between the begin render and end render phase the children are rendered. This allows you to start HTML tables in the begin render section and close them in the end render section. All skeleton files should have the following JSP tags:

<render:beginRender></render:beginRender>
<render:endRender></render:endRender>.

The body of the beginRender tag is only evaluated during the begin render phase, and the body of the endRender tag is only evaluated during the end render phase.

Here is what our new skeleton JSP (/customskeletons/spanningtwocolumnlayout.jsp) will look like

Listing 2 New Skeleton JSP

%@ page import="com.bea.netuix.servlets.util.RenderToolkit,
com.bea.netuix.servlets.controls.layout.LayoutPresentationContext,
java.util.List,
                com.bea.netuix.servlets.controls.layout.PlaceholderPresentationContext"
%>
<%@ taglib uri="render.tld" prefix="render" %>
<%
    RenderToolkit toolkit = RenderToolkit.htmlInstance();
    LayoutPresentationContext layout =
        LayoutPresentationContext.getLayoutPresentationContext(request);
%>

<render:beginRender>
    <table
        <% toolkit.writeId(out, layout.getPresentationId()); %>
        <% toolkit.writeAttribute(out, "class", layout.getPresentationClass(), "layout-custom"); %>
        cellspacing="0"
    >
        <tbody>
    <%
        List children = layout.getChildren("layout:placeholder");

        // Could get optional properties here to help with rendering
        // String property = layout.getProperty("myProperty");

        for (int i = 0; i < children.size(); i++)
        {
            PlaceholderPresentationContext placeholderPresentationContext =
                (PlaceholderPresentationContext)children.get(i);
            if (i == 0)
            {
     %>
                <tr>
                <td colspan="2" width="100%" valign="top" class="layout-placeholder-container">
                    <% toolkit.renderChild(placeholderPresentationContext, request); %>
                </td>
                </tr>
     <%
            }
            else if (i == 1)
            {
     %>
                <tr>
                <td width="30%" valign="top" class="layout-placeholder-container">
                    <% toolkit.renderChild(placeholderPresentationContext, request); %>
                </td>
    <%
            }
            else if (i == 2)
            {
    %>
                <td width="70%" valign="top" class="layout-placeholder-container">
                    <% toolkit.renderChild(placeholderPresentationContext, request); %>
                </td>
                </tr>
    <%
            }
        }
    %>
</render:beginRender>

<render:endRender>
         </tbody>
    </table>
</render:endRender>

Note: This example the widths are hard coded in the JSP. Instead, these widths should be specified in the layout file as an attribute to the placeholder. The widths can then be referenced in the skeleton as follows:

<render:writeAttribute name="width" value="<%= placeholderPresentationContext != null ? placeholderpresentationContext.getWidth() : null %>"/>

Also, other properties like "rowspan=2" can be passed as name/value pairs on the properties attribute and "endtop" to create a more generic row/column spanning layout.

The custom layout is now functionally complete. The html.txt file has not yet been created, but the layout can be tested. To do this, start WebLogic Workshop, open or create a portal file, select a page, and in the Property Editor window select the custom layout in the Layout field.

Note: if you change your .layout file after you have used it in the .portal file, changes won't be reflected in the .portal file. This happens because when you use a layout in the .portal it copies the markup from the layout. You will need to chooses another layout and then choose the original one back again to see the changes.

The html.txt File

The .html.txt is an HTML snippet strictly used by the WebLogic Administration Portal and Weblogic Workshop to give a visual representation of what the layout looks like, so the administrator can place the portlets in the correct placeholders. Typically this is the last file you will create, because it is not used by the rendering framework.

The last thing to do is create the html.txt file so the WebLogic Administration Portal can provide a visual representation of the layout. The /framework/markup/layout/spanningtwocolumn.html.txt should look something like this:

Listing 3 Sample html.txt Code

<table class="portalLayout" id="thePortalLayout" width="100%" height="100%">
<tbody>
<tr>
     <td class="placeholderTD" valign="top" width="100%" colspan="2"> 
            <placeholder number="0"></placeholder><br>


</tr>
<tr>
     <td class="placeholderTD" valign="top" width="30%"> 
            <placeholder number="1"></placeholder><br>
     </td>
     <td class="placeholderTD" valign="top" width="70%"> 
            <placeholder number="2"></placeholder><br>
     </td>
</tr>
</tbody>
</table>

Interacting With UI Controls

Since controls are not exposed directly to developers, developers need a way to directly interact with and affect the behavior of the controls. To accomplish this, WebLogic Portal exposes context, backing files, skeletons, and events. Developers should use these components when trying to alter the behavior of or interact with the portal framework.

Context

A context is nothing more then a delegate to the underlying control. This delegate only exposes the supported methods on the control.

Contexts are broken down into two types: backing context and presentation context. Backing contexts are available from the backing files, and presentation contexts are available from the JSPs.

Two types of context are required because certain methods apply at certain times in the lifecycle. For example, it doesn't make sense to have a setTitle() method on the Presentation context because the portal has already started to render and it would have no effect. Calling this method from a backing file, however, is appropriate.

Backing Context

BackingContext is available from backing files. A reference to a Backing context can be obtained in one of two ways:

The first way is to use the static method getXXXBackingContext on the context class. This method will return the active backing context for that type. To be more specific, if I call this method from portlet A's backing file, I will get the backing context for portlet A not portlet B.

Similarly, if I call getPageBackingContext(request) from portlet A, I will get the page backing context for the page portlet A is located on.

The second way to obtain a backing context is from another context. This can be useful when you want a context that is not the active context. Example would be, I want to obtain portlet Bs backing context from portlet A.

If portlet A is contained within the same page as Portlet B then one could use:
PortletBackingContext portletB = PageBackingContext.getPageBackingContext(request).PortletBackingContext getPortletBackingContextRecursive("Portlet Bs instance label");
If Portlet A does not know where portlet B is located then you can delegate to the DesktopBackingContext
PortletBackingContext portletB = DesktopBackingContext.getPageBackingContext(request).PortletBackingContext getPortletBackingContextRecursive("Portlet Bs instance label");

Refer to the javadoc on these and other backing context for more information.

com.bea.netuix.servlets.controls.page.PageBackingContext

com.bea.netuix.servlets.controls.application.backing.DesktopBackingContext

Presentation Context

PresentationContext are available from JSP files. A reference to a presentation context can be obtained in one of two ways:

The first way is to use the static method getXXXPresentationContext on the context class. This method will return the active presentation context for that type. To be more specific, if I call this method from portlet A's content JSP, I will get the presentation context for portlet A not portlet B. Similarly, if I call getPagePresentationContext(request) from portlet A, I will get the page Presentation context for the page portlet A is located on.
The second way to obtain a presentation context is from another context. This can be useful when you want a context that is not the active context. For example, I want to obtain portlet Bs presentation context from portlet A.

Backing Files

Backing files are simple Java classes that implement the com.bea.netuix.servlets.controls.content.backing.JspBacking interface or extend the com.bea.netuix.servlets.controls.content.backing.AbstractJspBacking abstract class (in retrospect it should have been called a backing class). The methods on the interface mimic the controls lifecycle methods and are invoked at the same time the controls lifecycle methods are invoked.

The controls as of this writing that support backing files are:

Books
Pages
Portlets
JspContent controls.

Note: Desktops also support backing files as of Service Pack 3

A new instance of a backing file is created per request, so you don't have to worry about thread safety issues. New Java VMs are specially tuned for short-lived objects, and this is not the performance issues it once was in the past. Also JspContent controls support a special type of backing file that allows you to specify if the backing file is thread safe. If this value is set to true, only one instance of the backing file is created and shared across all requests.

Skeletons

Skeletons are JSPs that are used during the render phase. The render phase is actually broken into two parts: begin render and end render. The parent control's begin render is called, followed by its children's begin render, their children's begin render, and so on. After the last begin render is called, the children's end renders are called, ending with the parent's end render. This allows the parent to provide a container, such as an HTML table, and the children to provide the table contents.

Each skeleton is actually called twice. There are special tags in the skeleton that only evaluate to true depending on which render phase you are in.

Events

There are four types of events in the system:

Window Mode
Window State
Page Change
Generic Portlet Events.

The Mode, State and Page Change Events are not exposed directly to the developer but can be configured through special methods on the Window backing files. Namely: setupModeChangeEvent, setupStateChangeEvent, and setupPageChangeEvent(). The methods must be called before the preRender method as events are fired just after handlePostbackData method. They will also only work if the handlePostbackData method returns true (see javadoc).

Note: When calling one of the setupxxevent methods, it must be done on the backing context that the backing file is tied to. If you do no do this the event may not get fired.

Portlet Events (not to be confused with page flow events) allow portlets to communicate. One portlet can create an event and other portlets can listen for that event. These Portlet events can also carry payloads.

Here is an example of one portlet firing and event from a backing file and other portlets listening for the event:

Listing 4 Sample Code for Portlet Firing and Event from a Backing File

/**
 * This is the implementation on the backing file of the portlet that wants to fire the event.
 */
public boolean handlePostbackData(HttpServletRequest request, HttpServletResponse response)
{
   // Create a new portlet event with the results in the paylod
    PortletEvent portletEvent = new PortletEvent(new MyPayload("Hello From portlet A"));
   
   // Get a hold of the portlet event manager and fire the event.
   PortletBackingContext portletBackingContext = 
        PortletBackingContext.getPortletBackingContext(request);
   PortletEvent.Manager portletEventManager = 
        PortletEvent.getEventManager(this, portletBackingContext);
   portletEventManager.fireEvent(portletEvent);

   // Needed for the event to fire.
    return true;
}


/**
 * This is the implementation of the portlet that wants to receive the event.
 */
public class ResultBacking extends AbstractJspBacking implements PortletEventListener
{
    MyPayload result;

    public void init(HttpServletRequest request, HttpServletResponse response)
    {
        result = null;

        // Register for Portlet Events
        PortletBackingContext portletBackingContext =
            PortletBackingContext.getPortletBackingContext(request);
        PortletEvent.addGlobalListener(portletBackingContext, this);
        CustomPortletEvent.Manager portletEventManager = 
            CustomPortletEvent.getEventManager(this, portletBackingContext);
    }

    public void handleEvent(Object source, AbstractEvent event)
    {
        // Can check the source of the event
        if (source instanceof PortletA)
        {
            result = (MyPayload)((PortletEvent)event).getPayload();

}
}

Note: The tutorial portal contains examples of portlets communicating via events.

Customization

Customization is the term used to describe Administrators and End Users making modifications to a desktop. Normally this is done through the Administration tools or the Visitor Tools web application. However, these API can be called directly from within the developer's code. For additional information on these API refer to the javadoc