Novell is now a part of Micro Focus

How to Showcase Your Web Content Using Novell Portal Services

Articles and Tips: article

J. Jeffrey Hanson
Senior Architect
Financial Fusion
jhanson583@aol.com

01 Aug 2001


Novell Portal Services provides an easy-to-use, extensible framework for developing portal Web sites with powerful authentication, customization, and content serving. This AppNote discusses how you can showcase your Web content using Novell Portal Services.


Topics

Novell Portal Services (NPS), Web applications, Java, LDAP

Products

Novell Portal Services (NPS)

Audience

developers, Web designers

Level

intermediate

Prerequisite Skills

familiarity with Java and the servlet environment

Operating System

Windows 95/98/NT/2000

Tools

Novell Portal Services (NPS) SDK

Sample Code

yes

Overview

Today any conversation about Web applications always leads to discussions concerning content and how to expose the content in a portal. A portal is a Web page that is divided into smaller, autonomous areas of information. Portals provide users with the ability to customize areas of information to meet their specific needs or wants. Some of the popular portals are My AOL and My Yahoo, which present sites that are, indeed, customizable for the individual user. The portal generally presents the user with several sources of information to choose from, such as, stock portfolios, weather information, news, sports, and so on.

Portal sites are built on many different types of programming frameworks, using several programming languages. Novell offers a comprehensive Java-based framework for portal-site building known as Novell Portal Services (NPS). Since NPS is based on Java, it offers superior flexibility and platform independence. NPS is based on servlets and Java classes, which gives any programmer who is familiar with Java and the servlet environment the ability to build secure and powerful portal sites-and to do so with a very small learning curve. NPS runs in any servlet environment that supports the Java Servlet 2.2 specification.

Introducing Gadgets

NPS abstracts the smaller areas of information that provide specialized content in a portal as Java classes that are built around a design pattern called a gadget. A gadget resides on a page in the portal defined by a specific scheme. Schemes refer to how the page is formatted using headers, footers, hidden entities, and columns. Gadgets utilize an LDAP-compliant directory to handle authentication, user privileges, user preferences, and content propagation. Gadgets present the specialized information as HTML or as XML. XML data is formatted based on instructions contained in Extensible Stylesheet Language (XSL) pages.

Novell provides several pre-built gadgets that provide information and functionality for GroupWise mail, Internet mail, network file storage, Microsoft Exchange messaging, and others. Novell also supplies the NPS developer kit, which allows you to create your own gadgets, and a portal administration gadget that allows administrative access to directory services objects that contain configuration information for the NPS environment.

The NPS framework allows administrators to give users control of certain behaviors of their gadgets via buttons in the title bar of the gadgets. For example, the "personalize" button allows a user to customize the contents of the gadget when clicked; the "minimize" button prevents a gadget from retrieving data and only shows the title bar of the gadget when clicked; the "hide" button hides the gadget completely when clicked.

NPS Development

NPS development works within the HTTP protocol's request/response domain. The main entry point for an NPS, HTTP request is the main Portal servlet (com.novell.nps.PortalServlet). It filters a request, passes the request on to the session manager to retrieve a session, and then to the gadget manager for final processing.

The NPS SDK includes the Gadget Runner utility, which essentially starts the Tomcat HTTP server and servlet engine running on port 8080 and configures a servlet context at <Tomcat Home Directory>webapps/nps. Also provided is the file "GadgetRunner.properties". This file contains, among other things, four parameters that configure the gadget to be loaded and executed by the NPS portal. These parameters are:

  • GADGETCODE - specifies the full package name of the gadget to execute.

  • USERDN - specifies the LDAP formatted, distinguished name of the user requesting access to the gadget.

  • USERPASSWORD - specifies the password of the user requesting access to the gadget.

  • RENDER - specifies whether the NPS servlet should pass XML or HTML back as the response.

Once you have implemented and compiled your gadget, and added its parameters to the GadgetRunner.properties file, you can execute the GadgetRunner utility to test your gadget. When the GadgetRunner utility is executed, a Web browser will start and a Web page will appear with a default scheme and your gadget running inside of the page.

Gadgets are Java classes that implement the com.novell.nps.gadgetManager. GadgetInstance interface. You can implement this interface directly, or, simply extend one of the pre-defined adapter implementations. The pre-defined implementations include, com.novell.nps.gadgetManager.BaseGadgetInstance, which provides a complete implementation of all standard gadget functionality; com.novell.nps.gadgetManager.BaseSSGadgetInstance, which adds support to com.novell.nps.gadgetManager.BaseGadgetInstance for Secret Store functionality and thus, Single-Sign-On support; or com.novell.nps. gadgetManager.ShortcutableInstance, which adds functionality to com.novell.nps. gadgetManager.BaseGadgetInstance and makes the gadget available through the Shortcut gadget.

Once you have decided which mechanism to use to implement com.novell.nps. gadgetManager.BaseGadgetInstance you must implement the getData method and provide the appropriate XML or HTML data to be formatted by the gadget's stylesheet (in the case of XML) and returned to the browser, as in the following code taken from the HelloWorld gadget:

public void getData( HttpServletRequest req, BufferedWriter out,
    Document domTree )
{
    try
    {
        out.write("<HELLOWORLD>");  // start tag
        out.write("<HELLODATA>Hello World!</HELLODATA>");  // content
        out.write("</HELLOWORLD>");  // end tag
    }
    catch(IOException io)
    {
        System.err.println(io);
    }
}

If your gadget returns XML data, you must create an XSL file and override the getContainedGadgetInstanceStylesheets method to format the XML data returned from the getData method. If you choose not to supply your own XSL file, as in the case of the HelloWorld gadget, the portal loads the corresponding default stylesheet, named main.xsl. The default XSL stylesheet for HelloWorld uses only three lines to format the data:

<xsl:template match="HELLOWORLD">
<xsl:value-of select='HELLODATA'/>
</xsl:template>

If you choose to supply your own XSL file, you must override the getContainedGadgetInstanceStylesheets method and return a HashSet containing your stylesheet as follows:

public HashSet getContainedGadgetInstanceStylesheets(HttpServletRequest
    req)
{
    HashSet containedGadgetInstanceStylesheets = new HashSet();
    if (myStylesheet != null)
    {
        containedGadgetInstanceStylesheets.add(myStylesheet);
    }
    return containedGadgetInstanceStylesheets;
}

At this point, you must add your gadget's parameters to the GadgetRunner.properties file. For a basic HTML gadget, you can simply add a line similar to the following:

GADGETCODE=MyTestGadget

This line added to the GadgetRunner.properties file will enable the GadgetRunner utility to load the following gadget:

import com.novell.nps.gadgetManager.BaseGadgetInstance;
import javax.servlet.http.HttpServletRequest;
import java.io.BufferedWriter;
import java.io.IOException;
import org.w3c.dom.Document;

public class MyTestGadget
    extends com.novell.nps.gadgetManager.BaseGadgetInstance
{
    public void getData(HttpServletRequest req,
            BufferedWriter out,
            Document domTree)
    {
        try
        {
            out.write("<B>Howdy</B>");
        }
        catch(IOException io)
        {
            System.err.println(io);
        }
    }
}

Notice that the above gadget responds with simple HTML, so no XSL page is needed.

The NPS SDK contains a batch file, called BuildGadget, to easily compile your gadgets. This utility is used as follows to compile MyTestGadget:

run BuildGadget MyTestGadget.java

Once your gadget has compiled successfully and you have added its parameters to the GadgetRunner.properties file, execute the GadgetRunner utility to test your gadget.

After developing, compiling, and testing your gadget, you must package your gadget for deployment into an NPS environment using the Packager utility included with the NPS SDK. The Packager utility compresses a gadget's files into a single file, with a .npg extension, that can be installed in NPS using the Admin gadget.

Gadget Lifecycle, Identification, and Communication

This section summarizes the lifecycle, identification, and communication of NPS gadgets.

Portal Initialization

NPS will access the Portal Configuration Object in the directory and locate all installed gadgets and their corresponding implementation classes. The Portal will then create an instance of each of these classes and call each instance's onPortalInit method to allow the class to perform startup initialization procedures. The instance is then discarded.

Gadget Creation

On a scheme's first reference, the Portal creates a new session-specific GadgetInstance object for each gadget in the scheme and assigns it a unique ID. State and session information is stored in the GadgetInstance.

Gadget State and Session Initialization

Once a gadget is created, NPS calls the GadgetInstance's setGadgetAssignment, setSession, init, and setGadgetInstanceID methods to initialize its state. The GadgetInstance is required to store this information and return it when the getGadgetAssignment, getSession and getGadgetInstanceID methods are called.

Request Dispatching

NPS routes HTTP requests through the Portal Servlet, which then makes calls to the appropriate GadgetInstance to handle the request and format the response. This is accomplished by embedding the gadget's unique ID in the query string of the HTTP request. For example, to route a request to a gadget with a unique ID of 214, you would embed GI_ID=214 in the query string of the HTTP request URL.

Gadget State Maintenance

When NPS refreshes the display for a gadget, it first makes a call to the gadget's getState method. If the method returns null, NPS calls the standard getData method of the gadget. If something other than null is returned, such as the string "Inactive", NPS attempts to call the getInactiveData method on the gadget. The state of a gadget can be changed using the NPState parameter in the query string of the HTTP request URL. To override the getState method and set the state of a gadget with a unique ID of 214, to "Inactive", the following query string would be passed in the HTTP request URL: ?NPState=Inactive&GI_ID=214.

Processing User Requests

Once a request has been passed to NPS, with a gadget's unique ID embedded in the query string of the HTTP request URL, NPS locates the gadget and calls its processRequest method to allow the gadget to process the request. Normally, the call to processRequest is followed by a call to getData to get the formatted response. If a gadget needs complete control over the HTTP response that is sent back to the browser, the gadget can set the parameter CUSTOM_CONTENT_TYPE=yes in the query string of the HTTP request URL. This will cause NPS to call an alternate version of processRequest that takes HttpServletResponse as an additional argument and requires the gadget to generate the entire response. In this case, the getData method is not called.

Debug Logging

Gadgets can log messages asynchronously using the com.novell.nps.debug.Debug class. Debug messages can be logged to the screen, a file, or both. One of three levels of logging can be specified: low, medium, and high. Only messages with a priority level greater than or equal to the current level are logged. Those with a lower priority are discarded. Logging is controlled through the GadgetRunner.properties file for the SDK and PortalServlet.properties file for the NPS system.

To view XML output from a gadget, add the "render=off" parameter to the HTTP request URL. This will instruct NPS to send the XML data back to the browser without applying the stylesheet. In turn, this will cause the browser to display the XML in its raw form.

Examples

import com.novell.nps.gadgetManager.BaseGadgetInstance;
import com.novell.nps.sessionManager.PortalSession;
import com.novell.nps.configManager.GadgetConfig;
import com.novell.nps.configManager.ConfigSettings;
import javax.servlet.http.HttpServletRequest;
import java.io.BufferedWriter;
import java.io.IOException;
import org.w3c.dom.Document;

public class HelloWorld extends com.novell.nps.gadgetManager.
    BaseGadgetInstance
{
     final static String MESSAGE = "Message";

    private String message = "Hello World!";

    /**
    * Gadget Initalize Code called by NPS when instance of the
    *
    * gadget starts up @param gadgetConfig   Initial configuration
    *
    * data specific to the gadget
    */
public synchronized void onPortalInit(GadgetConfig gadgetConfig)
{
com.novell.nps.debug.Debug.log("HelloWorld.onPortalInit");

ConfigSettings settings = gadgetConfig.getConfigSettings();
          if (settings != null) {
            String tempMessage = settings.getSetting(MESSAGE );
if ((tempMessage != null) && (tempMessage.length() > 0)) {
message = tempMessage;
}
}
}

/**
* The getData method is called by NPS to retrieve the gadget's data.
*
* @param req    The current request coming from the browser
* @param out    The output buffer for returning the XML Data as a
*               Document
* @param domTree    This is used to return the data as a DOM
*/
public void getData(HttpServletRequest req,
BufferedWriter out,
Document domTree)
{
com.novell.nps.debug.Debug.log("HelloWorld.getData");

try {
out.write("<HELLOWORLD>");  // The gadget start tag
out.write("<HELLODATA>" +message +"</HELLODATA>");
out.write("</HELLOWORLD>");  // End Tag
} catch(IOException io) {
System.err.println(io);
}
}

/** The processRequest method allows the gadget to perform normal
* request handling.
*
* @param req    The HTTP Request received from the user's device.
* @throws GadgetInstanceException Thrown on error.
*/
public void processRequest(HttpServletRequest req)
throws GadgetInstanceException
{
com.novell.nps.debug.Debug.log("HelloWorld.processRequest(req)");

String aMessage = req.getParameter("MESSAGE");

if (aMessage != null)
{
message = aMessage;
}
}

/** This processRequest method allows the gadget to produce the entire
*  response.
*
* @param req The HTTP Request received from the user's device.
* @param resp The HTTP Response to be used to send the data back.
* @throws GadgetInstanceException Thrown on error.
*/
public void processRequest(HttpServletRequest req,
HttpServletResponse resp)
throws GadgetInstanceException
{
com.novell.nps.debug.Debug.log("HelloWorld.processRequest(req, resp)");

resp.setContentType("text/html");

PrintWriter   out = resp.getWriter();

out.writeln("<H1>Hello World Gadget Takes Over the World</H1>");
out.writeln("<HR>");
out.writeln("<B>" +message +"</B>");

out.close();
}

/**
* Returns a Vector of this gadget's stylesheet and
* all the Contained Gadget Instance stylesheets.
*/
public HashSet
        getContainedGadgetInstanceStylesheets(HttpServletRequest req)
    {
        HashSet containedGadgetInstanceStylesheets = new HashSet();

        containedGadgetInstanceStylesheets.add( "MyHelloWorld.xsl" );

        return containedGadgetInstanceStylesheets;
    }
}

Summary

Novell Portal Services provides an easy-to-use, extensible framework for developing portal Web sites with powerful authentication, customization, and content serving. Integrated closely with directory functionality, the NPS framework provides a mechanism for exposing an object's personality, privileges, and purpose in a Web application. Closely monitored by a Web administrator and by directory services' access controls, NPS makes a major step forward to personalizing the Web.

For more information see the following Web sites:

* Originally published in Novell AppNotes

Disclaimer

The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.

© Copyright Micro Focus or one of its affiliates