Graph Servlet: A Dynamic Graph Generator for Portal Channels

Print-friendly Version

This program contains three key components:

• A Singleton structure class that resides in the system class loader (java.awt.ClassLoader) and that shares data between Sun ONE Portal Server and Graph Servlet
  
  
• Pages that are created with JavaServerPages (JSP) technology in both HTML and Java technology and that generate the channel content
  
  
• A Java servlet that dynamically renders a pie graph or bar graph

Figure 1: Request Flow

Figure 2: Architectural Structure

Users communicate with the channel, which contains a controller. The views incorporate the dynamic images with the standard HTML <img> tag. This design circumvents two major hurdles, as follows:

• Sun ONE Portal Server cannot aggregate Java servlets.
  
  
• JSP pages cannot generate dynamic images, which are a key requirement for a graphing utility. (The alternative of using HTML is only viable to an extent.) Time-sheet data, for example, change constantly and require continual updates.

JSPProvider provider =
(JSPProvider)pageContext.getAttribute "JSPProvider");
ProviderContext providerContext = provider.getProviderContext();

newNamesAndTimes =
providerContext.getCollectionProperty(channelName, "activities");

String activityName = (String)request.getParameter(channelName + "-activity");

Note -- Sun ONE Portal Server 6 sends the request parameters for a channel name to all the channels that are on display. Hence, be sure to adopt a naming convention of channel_name-parameter_name, for example, ActivityChannel-activity, so that each request applies to a single channel only, not to multiple channels.

session = request.getSession(true);
session.putValue("timesheet",elements);

DataFactory.setData(request, elements);

main.jsp displays data, that is, it outputs the data that were processed and sorted by controller.jsp, as follows:

• Activity names and durations in table format
• Checkboxes for selection and deletion of activities
• A form for inputting or editing the data for the current activities
• Thumbnails for the bar or pie graphs; see Code Example 6

<a href="<dtpc:getDesktopURL/>?<%=channelName%>-
view=graph.jsp&<%=channelName%>-style=Pie"><img
src="/graph/graphController?width=100&height=100&style=Pie"></a>

graph.jsp performs the following tasks:

1. Determines whether to display the bar or pie graph according to user input.
   
   
2. Converts color objects to Red-Green-Blue (RGB) hex strings for HTML presentation.
   
   
3. Displays the following:
   
   
   • A larger view of the graph according to user input (a click on either of the two graph thumbnails on main.jsp)
     
     
   • A color-coded table of the activities
     
     
   • An HTML link labeled Back to Main Page
     
     

GraphServlet, a Java servlet, extends the HttpServlet class and performs the following tasks:

1. Obtains from the URL, which is generated by controller.jsp, the parameters for drawing the graphs: height, width, and style
   
   
2. Creates a frame for the graph.
   
   
3. Obtains the pertinent data (ActivityElement array) from DataFactory and sends them to either the Pie or Bar object.
   
   
4. Encodes the graph image as a GIF file.
   
   
5. Deletes the Graphics and Frame objects.

public void doGet(HttpServletRequest req, HttpServletResponse res)
    throws ServletException, IOException{
    ServletOutputStream out = res.getOutputStream();
    String width = req.getParameter("width");
    String height = req.getParameter("height");
    String style = req.getParameter("style");
...}

Note -- On UNIX systems, you can start the Web container from any shell of your choice, so be sure to grant display access to users. See also the section, Troubleshooting. Alternatively, if the server on which your portal is running is executing in headless mode, you can start the Web container with the Xvfb server software.

The Pie object passes the information from controller.jsp to DataFactory and then to GraphServlet to render a pie graph that represents the durations of the activities. The Pie object performs two major tasks:

1. Calculates the durations of the activities.
   
   
2. By means of float conversions and divisions, scales the durations to add up to 360 degrees. Specifically, the Pie object does the following:
   
   
   1. Converts the durations to integers.
      
      
   2. Fixes integer rounding errors, if any, with a method.
      
      
   3. Fills the arcs with fixed degrees and different colors, the latter with the Graphics method in the Abstract Windowing Toolkit (java.awt.*).
      
      
   4. Scales and centers the pie graph.
      
      

Similarly, the Bar object passes information from controller.jsp to DataFactory and then to GraphServlet to render a bar graph that represents the durations of the activities. It performs two major tasks:

1. Determines the activity with the longest duration.
   
   
2. Scales the bars to fit within the height and width of the graph.
   
   
3. Fills the rectangles to render the bars of different colors with the Graphics method in java.awt.* and then creates the bar graph.

public static void setData(HttpServletRequest r, Object obj){
        String uniqueID = getUniqueID(r);
		
        if(h.get(uniqueID) == null){
            try{
                SSOTokenManager tokenManager =
SSOTokenManager.getInstance();
                SSOToken s = tokenManager.createSSOToken(r);
/*
 * If the user is logging in for the first time,
 * DataFactory adds a token listener to watch for session
 * logouts and timeouts.
 */
               s.addSSOTokenListener(factory);
           }catch(SSOException e){
               d.error("setData method could not get
SSOTokenManager", e);
            }
        }
        h.put(uniqueID, obj);
    }

public void ssoTokenChanged(SSOTokenEvent evt) {
    SSOToken token = evt.getToken();
    h.remove(token.getTokenID().toString());
}

The process flow is as follows:

1. The content returned from controller.jsp includes the image tags.
   
   
2. controller.jsp calls the data in the user profile and sends them to the DataFactory object.
   
   
3. The browser parses the tag data and requests the image from GraphServlet, that is, Sun ONE Portal Server calls controller.jsp and then the browser requests the image from GraphServlet.

The ActivityElement object serves as a storage location for the data and a color for a single activity. Each instance of ActivityElement contains mainly the set and get methods. ActivityElement performs only minimal data processing, as follows:

• The setDuration method takes either an integer or a string.
  
  
• controller.jsp passes an array of the ActivityElement instance to DataFactory, to GraphServlet, and finally to either Pie or Bar for graphing and output.

To install, do the following:

1. Unzip the zipped archive.
   
   
2. Change directory to graphing.
   
   
3. Import the portal archive (PAR) file by typing this command:
   % par import -p password -r uid -- TimeTracker.par dn channel
   
   where:
   
   
   • password is the password for logging in to your portal.
   • uid is the distinguished name of the administrator.
   • dn is the distinguished name of the target for the channel.

Table 1 explains how to derive the values for uid and dn and provides examples.

Table 1: Distinguished Names

Name Type

Value

Example

uid

The com.sun.identity.authentication .super.user setting in the install_dir/SUNWam/lib/ AMConfig.properties file

Sun ONE Portal Server 6.0: uid=amadmin,ou=people,o=sun.com,o=isp Sun ONE Portal Server 6.1: uid=amadmin,ou=people,dc=sun,dc=com

dn

The com.iplanet.am.defaultOrg setting in the install_dir/SUNWam/lib/ AMConfig.properties file

Sun ONE Portal Server 6.0: o=sun.com,o=isp Sun ONE Portal Server 6.1: dc=sun,dc=com

 

Note -- The user interface described in the following steps applies to Sun ONE Portal Server 6.0. The UI varies slightly in Sun ONE Portal Server 6.1 and 6.2.

4. Add the new channel to the portal desktop by following these steps:
   
   
   1. Log in to the Administration Console.
      
      
   2. Select the organization on the left panel, followed by Show: Services, and then click the arrow to the left of Desktop under Portal Server Configuration.
      
      
   3. Click Channel and Container Management under Display Profile on the right panel.
      
      
   4. In the scrolling list under Container Channels, click the container you would like to designate for the new channel.
      
      To place the new channel on the first tab of the sample desktop, select MyFrontPageTabPanelContainer.
      
      
   5. In the scrolling list for Existing Channels, select TimeTrackerChannel.
      
      
   6. Click Add to the left of the Available and Visible scrolling list.
      
      
   7. Click Save under Channel Management.
      
      
   8. Log out of the Administration Console.
      
      
5. Add the DataFactory classes to the system class loader. Do the following:
   
   
   1. Create a directory for the DataFactory classes:
      
      % mkdir /opt/DataFactory
      
      
   2. Copy the JAR file to that directory:
      
      % cp DataFactory.jar /opt/DataFactory
      
      
   3. Add the JAR file to the CLASSPATH attribute of the system class loader.
      
      If your portal is running on Sun ONE Web Server, append the jvm.classpath setting in the jvm12.conf file at install_dir/SUNWam/servers/https-hostname/config with this string:
      
      :/opt/DataFactory/DataFactory.jar

<a href="<dtpc:getDesktopURL/>?<%=channelName%>-
view=graph.jsp&<%=channelName%>-style=Pie">

Next comes this process:

1. main.jsp and graph.jsp determine which graph style the user has requested, for example, an enlargement or a new activity.
   
   
2. main.jsp and graph.jsp call the setData method in DataFactory and dispatch the request and the data to the system class loader, to be accessed later by DataFactory.
   
   
3. DataFactory pairs the request's SSOToken ID with the data and processes the data as a comprehensible object.
   
   
4. GraphServlet calls either Pie or Bar to render the graph.

The data passed to Graph Servlet are visible in the URL and include the key parameters, such as the width, height, and style of the graph.  

Note -- Parameters with null values cause errors. Be sure to set default values for the parameters.

You can find clues for troubleshooting in the system console or the Web server log. Alternatively, initiate the debug process by doing the following:

• Become root, and then edit the /opt/SUNWam/lib/AMConfig.properties file.
  
  
• Enable debugging by setting it to the level of your choice: error, warning, message, or all.
  
  
• Insert debug statements from the Debug class in the com.iplanet.am.util.* package. Save your changes.

Table 2 describes the common error conditions and the suggestions for resolving them.

Table 2: Error Conditions and Troubleshooting Tips
		Error				Troubleshooting Tips
		The images are not displayed.				See the Web server log for awt errors. If they are present, the DISPLAY environment variable setting is likely incorrect. Find out whether DISPLAY is set in the same shell or terminal in which you restarted the Web server. If not, at the prompt of a shell or terminal in which you launched the Web server, type: % setenv DISPLAY hostname:0.0 The X server default grants permissions for displaying images to the login user only. Ensure that root has that permission by typing at the prompt of a shell or terminal of your host: % xhost +hostname To test, type: % xterm If an external terminal is displayed, the permissions are correct. Verify that the URL and the images are correct. To test the images, open a new browser window and click the images there, not through Sun ONE Portal Server.
		The graph view corrupts the other portal channels.				You may have specified no channel names in the URL, in which case Sun ONE Portal Server 6 sends the request to all the channels. When defining the variables for the URL (for example, the view of your choice), ensure that the channel name is fully qualified. Here's an example of a correct URL: <a href="<dtpc:getDesktopURL/>?<%=channelName%>- view=graph.jsp">exampleLink</a>
		No data are displayed.				Verify that the code in the JSP pages sets the data into the DataFactory object.
		graph.jsp cannot access the required data.				Ensure that the class files are being deployed in the correct locations and that the Web application is pointing to the correct targets.