Data Visualization Plugins

From ARSWiki

Jump to: navigation, search

Contents

General Information

This section covers general information to assist is programming, testing, and debugging DV Plugins.

Accessing DV Plugins

There are two ways that DV Plugins can be accessed.

Data Visualization Field

Through a form within the user tool or mid-tier, a dv plugin can be using a DV Field. These are similar to flashboard and view fields. The session information from the user tool and mid-tier session are used to instantiate the dv plugin.

Mid-Tier/Browser Session

Creating a form with a dv field for each plugin is tedious when developing a dv plugin; one has to constantly close and reopen the form to see any changes to the plugin. It is possible to view your dv plugin using a browser session that access the Plugin servlet directly. The url to access the dv plugin uses this format: 

http://<MidtierServer>/<MidtierContext>/plugins/<PluginName>/params

When using this method, a hard refresh (CTRL+Shift+Refresh) will reinstantiate the plugin. To access the plugin initially, hit any part of the mid-tier that will authenticate you and create a session. The shortest URI possible is /arsys/home

There are also a number of parameters that can be passed to the dv plugin. There does not seem to be any documentation of the parameters that the plugin accepts, but these have been seen in use:

  • flashboard: behavior unknown, is null when a dv plugin is accessed using a dv field
  • name: behavior unknown, is null when a dv plugin is accessed using a dv field
  • server: the server that serves the dv module definition (jar)
    • The following methods rely on this parameter for correct operation. A NullPointerException is thrown if the server parameter is not provided one of the following methods is called.
      • com.remedy.arsys.plugincontainer.PageService.getPluginContextURL()
      • com.remedy.arsys.plugincontainer.PageService.getRelativeContextURL()
  • fieldid: if the dv plugin is used from a dv field, the fieldid of the dv field
  • width: the width used to render the dv plugin
  • height: the height used to render the dv plugin
  • native: behavior unknown, set to 1 when a dv plugin is accessed using a dv field

Utilities

This section provides some tools that may be of use when developing DV Plugins.

Data Visualization Plugin Framework (DVPFW)

This application is intended to address the following needs, in relation to the DV Plugin architecture:

  • Implemente helper methods to JOARSE for the purpose of exposing JOARSE as a tool for use in DV Plugins
  • Performs some of the functions that your typical J2EE architecture provides:
    • A WebContent folder to serve static content

Downloads

Special Scenarios

This section addresses some specific issues and workarounds that a dv plugin developer may encounter.

Third-party Classes and DV Plugins

If third-party classes are required for your plugin, there are several methods on how this can be approached. Each method has it's advantages and disadvantages. Your environment (level of effort required to alter midtier war or app server) and intent (internal use vs. external redistribution) of the plugin will be the main drivers in determining the method that is most appropriate.

Workarounds

Include the jars in the mid-tier WEB-INF/lib directory

  • This method requires customization to the mid-tier.war file
  • The changes are global for all mid-tier apps, meaning future dv plugins on your server will be capable of using the libraries
  • This is an appropriate method if using jni wrappers and you are not using the jars for anything outside the mid-tier on your app server

Update the application server class-loader to include the third-pary libraries

  • The changes are global for all web apps, meaning future dv plugins, custom servlets, etc. on your app server will be capable of using the libraries
  • This approach leaves the mid-tier.war file unmodified, making mid-tier upgrades and patches easier (modifications will not be required each time a new war is deployed)
  • This is the preferred method if the libraries are jni wrappers and you are using them for any servlets outside the mid-tier
  • The implementation is app server specific (JBoss, Tomcat, WebSphere, etc.)

Include the class files for the third-party library in your plugin jar

  • This approach only addresses a single dv plugin
  • This approach requires no change to the mid-tier war or app server configuration
  • Redistribution of dv plugins created using this method will be easier for other people to implement because they can import the jar into the Data Visualization Module form and go
  • This is not possible if using a jni wrapper

Serving Static Content (WebContent-images-css-js-etc)

DV Plugins do not act like regular web applications when it comes to serving static content. In J2EE web applications, typically a WebContent directory is available that can be used to serve static content; do not expect this of the dv plugin architecture. Instead the following steps must be taken to serve static content from your dv plugin:

  1. create a classloader object
  2. create an input stream to read from the class
  3. create a reader to read the input stream
  4. set the content type
  5. spool the stream from the reader to a writer

Logging to the Mid-Tier or Container Logs

How-to Series

This section and its subsections will take a how-to approach to developing dv plugins. The series is presented in a series of example dv plugins, where each example progressively implements additional functionality.

Simple Hello World Example

This is a simple 'Hello World' data visualization plugin. This plugin only implements the Plugin interface. This can be useful for people starting with data visualization fields because it has an ant build structure suitable for creating jar files in the format the Remedy data visualization module expects. This code was created using jdk1.5.0_09-b03. This code is released under the BSD license, so you can pretty much do whatever you wish with it.

Downloads

  • Source code for the HelloWorldPlugin is available in the arswiki Subversion repository. Use the Trac frontend to browse the source code, report problems, request enhancements, etc.

Javadoc

Code Review

The usual legal mumbo jumbo you see with software. This is the BSD license, which imho is the open source license with the least restrictions. 

/**
 * Copyright (C) 2006 Axton Grams
 * All rights reserved.
 * 
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 * 3. The name of the author may not be used to endorse or promote
 *    products derived from this software without specific prior
 *    written permission.
 * 
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR `AS IS'' AND ANY EXPRESS
 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
 * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

Here we define the java package name. 

package org.arswiki.dvplugin.helloworld;

Here we import the necessary packages required to compile the software. 

import com.remedy.arsys.plugincontainer.DefinitionFactory;
import com.remedy.arsys.plugincontainer.NoPermissionException;
import com.remedy.arsys.plugincontainer.Plugin;
import com.remedy.arsys.plugincontainer.PluginConfig;
import com.remedy.arsys.plugincontainer.PluginContext;
import java.io.IOException;
import java.io.PrintWriter;
import javax.servlet.http.HttpServletResponse;

The class HelloWorldPlugin is declared, which will implement the Plugin interface. The Plugin interface is the minimum required to allow a data visualization plugin to be written. There are other interfaces that allow a program to read configuration information on instantiation and handle events such as the user clicking on the dv plugin. 

public class HelloWorldPlugin implements Plugin {
	
	/*
	 * methods to implement Plugin interface 
	 */

The guts of the program define the abstract methods declared in the Plugin interface. In this case they are very simple. The processRequest method handles the request/response interaction between the client and the server. 

	public void init(PluginConfig config) {
	}

	public void processRequest (
			PluginContext pc) 
		throws IOException, NoPermissionException {
		HttpServletResponse response = pc.getResponse();
		response.setContentType("text/html;charset=UTF-8");
		PrintWriter writer = response.getWriter();
		writer.println("<html><head><title>Hello World Plugin Example</title></head>");
		writer.println("<body><h1>Hello World</h1></body></html>");
		}
	
	public String handleEvent (
			PluginContext pc, 
			String eventType, 
			String eventData) 
		throws IOException, NoPermissionException {
		return "alert(\"Got event data in Midtier as " + eventData + "\");";
	}
	
	public DefinitionFactory getDefinitionFactory() {
		return null;
	}
	
	public void cleanup() {
	}
}

Hello World Example Using JOARSE to Read Form Data

This example uses JOARSE to read some data from a form, which is then presented in the dv plugin.

Status: Release pending the incorporation of the changes to rtl/joarse for 7.x api support.

Serving Static Content From Within the DV Plugin Module Definition ('Data Visualization Module' form: jar)

Serving Content From a DV Plugin Definition ('Data Visualization Definition' form)

External Links

Retrieved from "http://arswiki.org/wiki/Data_Visualization_Plugins"
Personal tools