Table of Contents

• Introduction
  • Overview
  • Security Hierarchy
• NetCharts Server Architecture
  • Application Server Structure
  • Project Structure
  • Chart Components
  • NetCharts Server Service/Daemon Parameters
• NetCharts Server Licensing
  • Evaluation Licenses
  • Upgrading an Evaluation License to a Registered License
• The Admin Console
  • Getting Started
  • Functional Overview
• Embedding NetCharts Server in an Application Server
  • Installing a Temporary NetCharts Server
  • Configuring an Embedded Server Working Directory
  • Creating an Embedded Server Distribution
  • Accessing an Embedded NetCharts Server
  • Oracle WebLogic 10 Configuration
  • IBM WebSphere 7.0 Configuration
  • JBoss Application Server Configuration
  • JBoss 6.1.0 FINAL Application Server Configuration
  • Apache Tomcat Configuration
• Troubleshooting
  • Debugging Tools
  • Resolving Common Administrative Issues
• NetCharts Server Caching
• Where can I go for additional resources and help?

Introduction

Overview

NetCharts Server is a specialized application server that enables technical people to deploy, manage, and share reports, score cards, dashboards and other business intelligence applications created using NetCharts Designer. Applications may be deployed and interacted with using NetCharts Server or Sever may simply serve visualization elements to another application.

Administration of the NetCharts Server is controlled via the Admin Console, a browser-based application that provides access to the Server’s administrative functions. The Admin Console provides access to NetCharts Server utilities specific to environment configuration and on-going maintenance.

Security Hierarchy

NetCharts Server provides a three-tier security hierarchy consisting of the Administrator, the Developer Group, and Users.

NetCharts Server Architecture

This section explains the physical layout and structure of NetCharts Server’s directories and files.

Application Server Structure

NetCharts Server’s HTTP and servlet processing functions leverage the Apache-Tomcat application server architecture.

Basic File Structure

During installation, NetCharts Server creates and populates a number of directories on the file system. A brief description of the most developer-relevant directories is provided below. Each directory is relative to the installation directory (e.g. c:\Program Files\Visual Mining\NetCharts Server)

Project Structure

Overview

The Project is the main NetCharts Server file structure. As NetCharts Server applications are deployed the contents are stored within the context of a Project. Each project may contain data files, data source files, chart definition files, table definition files, page files, and much more. The project structure makes it easy to identify, create, and manage these files.

Projects Directory/Development Homepage

Developers typically access the projects directory via the Development Console, at

http://yourserver:port/Developer/index.jsp

Each project is represented on disk as a file directory.

The project directories all reside under a parent directory called projects. This directory can be found in the installation at:

<install directory>/Server/root/projects

The contents of the projects directory can be manipulated manually through the operating system’s available file system tools, but this is not recommended.

Project and Project File URL Access

The projects directory is available by an HTTP URL in the form of:

http://yourserver:port/projects

Specific projects and project names are accessible in the form:

http://yourserver:port/projects/yourprojectname/yourprojectfile.jsp

Project Security

Access to each project’s files can be independently secured by the NetCharts Server Administrator. Project-level security controls which users, or groups of users, can access a given project.

Project Contents and Resource Files

Projects can contain any type of file, including images, HTML, data files, documents, spreadsheets, and more. In addition, projects usually contain one or more files that define a data request, a chart definition, a table definition, or a page definition. These files, known as resource files, have unique extensions that identify them to the NetCharts Server. These resource file extensions, and their meanings, are detailed in the table below:

Chart Components

There are 4 components that can be available to every chart template in a NetCharts Server project. Two of the components may have many duplicates, and another is optional. The components are:

The template file: Suffixed by .cdx or .cdl
The variables file: Suffixed by .variables (optional)
The image file: A binary encoded file suffixed by .png (or some other image file type)
The image map: Suffixed by .html

Basic Chart File Structure

The basic structure of a chart named “exampleChart” in a sample project directory is shown below:

projects/

myproject/

exampleChart.cdx

exampleChart.variables

exampleChart.variables is only created if there are cdx variables defined to the chart template, otherwise it does not appear.

If the NetCharts Server is called with the following URL’s three PNG images files will be created and cached in the Chart Image cache within the exampleChart.chart directory. The number of cached image files is configurable from the Performance panel in the Administration Console.
 

http://localhost:8001/projects/myproject/exampleChart.cdx?type=PNG

http://localhost:8001/projects/myproject/exampleChart.cdx?type=PNG&width=300&height=200

http://localhost:8001/projects/myproject/exampleChart.cdx?type=PNG&width=250&height=200

 
Additional files would be created under the following sub-directory structure (assuming the default chart image cache location on a Windows installation):
 

C:\Program Files
          \Visual Mining
                    \NetChart Server
                              \Server
                                      \Temp
                                             \imagecache
                                                      \projects
                                                               \myproject
                                                                         \examplechart.cdx
                                                                                   \1332358356.png
                                                                                   \1332358356.html

NetCharts Server ensures that unique names are created based on the data and the size of the chart. This provides a highly flexible and efficient caching mechanism. Please see NetCharts Server Caching for more information.

The .html files are created only when drilldown has been enabled.

The key feature of the architecture is the target sub-directory for the above shown files is configurable and under the control of the NetCharts Administrator. This optionally separates the static sub-directories of the NetCharts Server system from the dynamic sub-directories.

URL Mapping

By Default, a project in NetCharts Server exists under a sub-directory of the same name, itself subordinate to the root sub-directory under the NetCharts Server installation. For example:

C:\Program Files\Visual Mining\NetCharts Server\Server\root\projects\myproject\foo.cdx

…would return a chart to a request with the following URL path:

http://localhost:8001/projects/myproject/foo.cdx

The above results from the assignment of root to the “RootDir” configuration parameter. It is possible to assign another sub-directory to the “RootDir” configuration parameter under which project sub-directories are found. The “RootDirs” configuration parameter specifies an additional set of sub-directories through which NetCharts Server will search if a project cannot be found from the sub-directory identified by the “RootDir” configuration parameter.

NetCharts Server Service/Daemon Parameters

NetCharts Server uses several configurable parameters at startup time to initialize the service (in Windows environments) or daemon (in Unix environments). These parameters can be modified if required.

On Windows machines, the parameters can be changed via registry settings at:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\NetChartsServer\Parameters

With Unix machines, these parameters are found in the script:

<install directory>/Server/bin/NetChartsServerDebug

NetCharts Server Licensing

There are two types of NetCharts Server licenses: evaluation and registered. An evaluation license is a no-cost, time-based license that allows customers to “test drive” the application. The registered license is purchased from the Visual Mining sales department and enables full access to the NetCharts Server with no limit on the number of concurrent users.

At any point in the evaluation, the customer can upgrade their evaluation copy of the NetCharts Server to a registered licensed version without having to reinstall.

Evaluation Licenses

Evaluation licenses are provided to customers so that the administrator/developer can successfully gauge the effectiveness and fit of the NetCharts Server within their application environment.

Restrictions

When in NetCharts Server Evaluation mode, the following application conditions apply:

• The software will only function for a maximum 32 days after the download.
• The start page contains an “Evaluating NetCharts Server” block.
• The Admin Console shows the license expiration date.
• If past the expiration date, the server will not start.

Purchasing or Extending Evaluation Licenses
 
To purchase a license contact the Visual Mining sales department at sales@visualmining.com or 1-800-308-0731 (Option 3). Users wishing to extend an evaluation license should also contact Visual Mining Sales.
 
In order to update the evaluation license you will need to provide the product Authorization Key along with the license request.

Upgrading an Evaluation License to a Registered License

NetCharts Server licenses may be updated by sending the Authorization Key from an instance of NetCharts Server to Visual Mining with a request for a new license. The Authorization Key is available on the Admin Console.
 

 
Visual Mining will use the Authorization Key to generate and deliver an updated NetCharts license file. This license file can be installed from the Admin Console’s home page by selecting the Install License link from the License subpanel. A text box and browse button will appear where you can specify a license file and then click on the UPDATE LICENSE button.
 

 

The Admin Console

The Admin Console is a browser-based application that provides easy, centralized, and remote access to sophisticated NetCharts Server administrative functions, including:

• Server Restart – A Java applet that provides the ability to remotely restart the NetCharts Server
• Clear File Cache – Clears the chart image cache stored on disk for specific project(s) or for all projects.
• Clear Data Cache – Clears the data cache stored in memory for all projects currently running in NetCharts server.
• License Update – Allows easy updating of the NetCharts Server license
• Application Update – Provides a well-defined mechanism for tracking and performing NetCharts Server updates.
• Project Archive – Provides the ability to archive and upload entire projects.
• Import/Remove JAR Files – Provides the ability to import JARs into NetCharts Server
• System Reports – Provides information on load and data cache performance.
• Server Configuration – Provides a well defined mechanism for altering initialization, execution and performance oriented parameters.
• Debugging – Attribute-level debugging and other logs
• Task Scheduling – A powerful way to pre-generate or periodically email reports
• Security – Developer/User/Group level security attributes. Also the ability to limit access to the server from specific IP’s
• Web Services – Tools to set up NetCharts Server as a Web Service

The Admin Console is available in both Production and Complete installation modes.

Getting Started

The URL for the Admin Console is:

http://yourserver:8001/Administrator/index.jsp

On Windows machines, the Admin Console is also available off of the Start menu, or by links from the Start Page or Developer Console.

Logging In

The Admin Console is password protected to prevent unauthorized access or reconfiguration. The default login and password for the Admin Console is “Admin” and is case-sensitive. The password may be changed using the Manage Users panel in the Admin Panel.
 

Administrator Home Page

The administrator home page consists of the Control Panel and the Admin Console. It provides easy, centralized access to all administration functions.
 

Functional Overview

This section describes each function available from the NetCharts Server’s Admin Console.
Install Update
This function provides the NetCharts Server administrator with a simple mechanism for updating the NetCharts Server application or reverting to an earlier state. Updates are provided by Visual Mining in the form of a compressed ZIP file and may include bug fixes and/or enhanced functionality. Each update file includes all previous updates.

The following steps will install an update:

1. Download the update ZIP file from the Visual Mining website
2. From the NetCharts Server Admin Console, Select the Install Update link from the Version subpanel
3. Browse and select the downloaded ZIP file from the local file system
4. When the proper ZIP file has been selected, select the UPLOAD button. This will upload the ZIP file to the server. Once the ZIP has been uploaded, the following message will appear:
5. Select the here link to install the update.
6. After the update is complete, the server will be restarted for the changes to take effect.
7. The Admin Console’s Version subpanel will then indicate the new update version.

Any existing files that are overwritten by files in the update ZIP file are saved in a backup ZIP file. This backup zip file is named the same as the update zip file, with “Backup” appended to the name prior to the .ZIP file extension. The backup file is saved into the server installation directory at:

webapps\Admin\update

Restoring a backup file works exactly as the same as installing an update. The administrator selects the backup file .ZIP and performs the installation.

License Update
 
The evaluation license may be extended or made permanent using a new serial number available from Visual Mining. NetCharts Server licenses may be updated from the Admin Console’s home page by selecting the Install License link from the License subpanel. Simply enter in a valid serial number and select Update License and Restart the NetCharts Server.
 
Restarting NetCharts Server
 
NetCharts Server can be restarted from the Admin Console by selecting Restart Server from the Admin Console’s control panel in the Utilities section. This function requires the use of a Java applet. The Confirm Restart panel will appear in the workspace as shown here:
 

 
Once the Confirm Restart panel is shown, select the RESTART button. The restart applet will then load, and a prompt for the Admin user id and password. Then the following message will be displayed:
 

 
Once the restart has completed, the applet will shutdown, and the browser will be redirected to the Restart Success page.
 

 
The NetCharts Server can also be stopped, started, and restarted through the Services menu on Windows:

1. Bring up the Control Panel from the Windows Start menu.
2. Select Administrative Tools from the Control Panel.
3. Select the Services entry, , from Administrative Tools.
4. There is an entry for NetCharts Server which you can stop, start or restart through Windows Services.

On Unix platforms, there are two scripts, NetChartsServerControl and NetChartsServer, that can be used to start and stop the NetCharts Server. They are located in:

$NCSINSTALL/Server/bin

NetChartsServerControl

NetChartsServerControl is the main script for running the server, and follows Unix standards for starting and stopping services.

To start the server:

$NCSINSTALL/Server/bin/NetChartsServerControl start

To stop the server:

$NCSINSTALL/Server/bin/NetChartsServerControl stop

NetCharts Server can be configured to automatically start at boot time by creating symbolic links to the script:

$NCSINSTALL/Server/bin/NetChartsServerControl

this requires root permission. The location of the links depends on the host system:

Solaris:

/etc/init.d/netchartsserver

/etc/rc2.d/S99NetChartsServer

Linux:

/etc/rc.d/init.d/netchartsserver

/etc/rc.d/rc2.d/S99NetChartsServer

HP-UX:

/sbin/init.d/netchartsserver

/sbin/rc2.d/S99NetChartsServer

NetChartsServer

NetChartsServer starts a NetCharts Server by setting the environment variables for Java and calling a C program, ESStart, to launch the server.

Clear Image Cache

The Clear Image Cache selection clears the chart image cache stored on disk. The image cache may be cleared for specific project(s) or for all projects.
 

 
Select the list of project(s) to clear the file cache for and then press the Clear Cache button.
Clear Data Cache

The Clear Data Cache selection clears the in-memory data cache used by charts and tables for all projects.
 

 
Archiving Projects and Uploading Project Archives

Entire projects can be saved in archive zip files within NetCharts Server. The NetCharts Server archive files can also be uploaded to remote computers running NetCharts Server. Once uploaded, NetCharts Server unzips the archive and creates a new project from its contents. The project archive function is available by selecting the Project Archive link from the Admin Console’s control panel in the Utilities section.
 

 
Selecting the NEW button allows the administrator to create a project archive from a list of the projects currently on NetCharts Server. The archive is saved in the NetCharts Server directory structure at:

Server\webapps\Admin\archive\ArchiveCache\archivefile

The archive filename is in the format:

<ProjectName>MMDDYYHHMM.zip

with the MMDDYYHHMM portion of the name providing the date/time that the archive was created. After an archive has been created, the administrator can download or delete the project archive.
 

 
Selecting the UPLOAD button allows the administrator to upload a NetCharts Server project archive file to a remote computer running NetCharts Server from the local file system.
 
If it is a new project the user will be presented with the following text and will be asked to click on the here hyperlink in order to complete installation.
 

 
If a project already exists with the same name as the project in the archive file, the user is presented with the following options.
 

 
Uploading JARs to NetCharts Server
 
NetCharts Server provides a utility for uploading JAR files to the server. This is a convenient way to upload new JDBC drivers, Process Modules, or other libraries that a user may want NetCharts Server applications to have access to. The import JAR file utility is available by selecting the Import Jar Files link from the Admin Console’s control panel in the Utilities section.
 
To upload a JAR file, browse to the file on the local file system and then click on the UPLOAD button.
 

 
After the file is uploaded, the user is presented with the following screen. (Note: NetCharts Server must be restarted in order to be able to use the new jar file.)
 

 
Files that have been uploaded through the above utility can also be removed via the Remove Jar Files Utility also located on the Utilities section. To remove a jar file, click on the X next to the file you wish to remove. (Note: NetCharts Server must be restarted in order to completely remove the new file.)
 

 
Displaying System Reports
 
NetCharts Server provides a built-in capability to display basic system load information. System reports are available by selecting the System Reports link from the Admin Console’s control panel in the Utilities section.
 

 
J2EE Integration
 
Utility used for creating embedded installations of NetCharts Server in other application servers such as Websphere, Weblogic, and JBoss. Please see the section Creating an Embedded Installation for more information
 
Configuration Panels
 
There are five configuration panels that allow customization of various attributes:

• General – Basic system parameters
• Security – Parameters to control global server access and functionality
• Image Encoding – Parameters to control the quality/compression of the various image encoders.
• Performance – Parameters related to performance
• File Management – Location of system files

Configuration panels are shown by selecting the appropriate link from the Admin Console’s control panel in the Server Configuration section.
 
Each configuration panel lists the name of the parameter and a value field. When submitted, the value is verified and then written to the server.xml file in:

<installdirectory>/Server/conf

A description of each individual parameter’s purpose is available by selecting the HELP button.
 

 
Setting Chart Engine Runtime Properties
 
The NetCharts Server’s chart engine has several features that are controlled by a set of properties that are configured at runtime. The values for these properties are specified as Chart Engine Properties on the General System Configuration page of the Administrator’s console. The current set of runtime properties includes among others:

• DateFormats – the date formats that should be considered legal when specifying dates to a chart. The default is the standard Java SimpleDate format.
• MaxAxes – the maximum number of axes a chart can have. The default is 10.
• MaxDataSets – the maximum number of data sets a chart can have. The default is 50.
• NetscapePrintFix – activates code that works around printing chart applets from Netscape 4.x browsers. The default is false.
• MaxResultSets – the maximum number of SQL result sets. The default is 50

Task Scheduling
 
A NetCharts Server task is the periodic execution of a file in a NetCharts Server project. The output of the execution may be emailed to one or more clients. Tasks may be defined by selecting the Define Task link from the Admin Console’s control panel in the Task Scheduling section. The URL defined in a task must be a relative URL. Generally, the URL will look something like:

/projects/myproject/myscheduledtask.jsp

 

 
Viewing Tasks
 
Defined tasks may easily be viewed, edited, or deleted by selecting the Show Tasks link from the Admin Console’s control panel in the Task Scheduling section.
 

 
Debugging And Logging
 
The debugging and logging functions are described in the Troubleshooting section below.
 
Managing NetCharts Server Users
 
In most environments, NetCharts Server Users need not be explicitly defined or imported. There are two situations when specifying users is appropriate:

• When the Administrator intends to apply Project or Developer level security
• When the Administrator intends to define users for scheduled task email purposes.

To import or define a NetCharts User select the Manage Users link from the Admin Console’s control panel in the Security section.
 

 
Selecting the IMPORT button retrieves a list of native users for use within the NetCharts Server. To configure the native domain:

1. Stop NetCharts Server.
2. Navigate to \Visual Mining\NetCharts Server X.X\Server\conf.
3. Copy server.xml to server.xml. to make a backup copy.
4. Open server.xml with a plain text editor.
5. Locate the attribute: .
6. Change the value of the Value attribute to the name of the domain (e.g. Linux, Windows domain, Active Directory, etc.) containing the users to authenticate against.
7. Save server.xml and exit the editor.
8. Start NetCharts Server.

Once the server is restarted, within the Admin Console you can “import” native users.
 
Selecting the NEW button allows the administrator to define a user using the Edit User panel.
 

 
Managing NetCharts Server Groups
 
NetCharts Server allows defined or imported users to be organized into groups. In many environments, NetCharts Server groups need not be explicitly defined. There are two situations when specifying groups is appropriate:

• When the administrator intends to apply Project security and desires to group the users.
• When the administrator intends to apply Developer security and needs to identify those users in the Developer Group.

To define or edit a NetCharts User Group select the Manage Groups link from the Admin Console’s control panel in the Security section.
 

 
When the NEW button is selected, or a particular group is edited, the administrator can specify the users that are members of that group.
 
Enabling Developer-Level Security
 
To restrict Developer Console access to members of the Developer Group, select the Manage ACLs link from the Admin Console’s control panel in the Security section.
 

 
Then select the Security restrictions on Developer Console button in the Security Toggles subpanel. The button will appear green when enabled
 

 
Enabling Project-Level Security
 
To restrict access to all projects to a user or groups of users, select the Manage ACLs link from the Admin Console’s control panel in the Security section. Then, if not already enabled, enable project security by selecting the Security restrictions on Projects button in the Security Toggles subpanel. The button will appear green when enabled.
 

 
When you select to enable security restrictions on Root it places restrictions on the root NetCharts Server folder (/) so only read based HTTP methods like GET and POST are allowed. Write based HTTP methods like PUT and DELETE are disabled.
To enable security for an individual project, select the edit icon on a project and click on the Enable Security link.
 

 
On the following page, configure the security parameters for the project.
 

 
After clicking save, security will be enabled for the individual project.
 

 
Web Services
 

NetCharts Server has built in support for the deployment and servicing of Web Services. Web Services allow for the exposing of application logic and functions to clients via the web. Through the use of XML messaging, Web Services can be utilized by a wide range of clients, allowing for near-universal access to the functions and applications being exposed by the Web Service. By deploying Web Services within NetCharts Server, users can make available NetCharts Server based applications and resources to trading partners, clients and customers, internal staff, etc. These Web Services can be standalone applications or act as individual components that can be utilized by other services.
To set up NetCharts Server as a Web Service, select the Web Services link and follow the installation directions.

Embedding NetCharts Server in an Application Server

NetCharts Server is comprised of a set of web applications and can run in its own dedicated application server or can be embedded into some other existing application server. By default, the NetCharts Server is installed with its own web application server allowing users to quickly configure and run NetCharts Server as a self-contained, standalone service.
 
Running NetCharts Server in embedded mode allows web application developers to simplify their runtime environment by eliminating the separate NetCharts Server process. In embedded mode, users have access to the NetCharts Server runtime environment via the server’s Java/JSP toolkit. The toolkit can be downloaded from the API Toolkits section of the Developer’s Console.
 
In embedded mode, any and all web applications that run in the application server will have access to a single instance of a NetCharts Server runtime. NetCharts Server can currently be embedded into BEA WebLogic, IBM WebSphere, JBoss Application Server and Apache Tomcat. Note however, that the NetCharts Server Developer’s console and Administrator’s console are not accessible in embedded mode.

One common approach is to install NetCharts Server as a standalone service for initial development and testing, and then move to an embedded configuration for production.
 
The embedding process varies from application server to application server and also from version to version of a particular application server. Visit our customer support portal for up-to-date information on embedding NetCharts Server.
 
In general, the embedding process has the following steps

1. Install a temporary standalone instance of NetCharts Server
2. Configure an Embedded Server working directory
3. Install NCS into the host Web Application server
4. Enable a client application to use the embedded NCS.

Installing a Temporary NetCharts Server

It is necessary to have access to a standalone NetCharts Server installation temporarily in order to configure an embedded installation. If you already have a standalone NetCharts Server installed and running, skip this step.
 
Install NetCharts Server into some temporary working space and start it.
 
If you have a registered license for your embedded NetCharts Server, update the temporary NetCharts Server using the Administration Console to use this license. See the Upgrading an Evaluation License to a Registered License section for details. Note that NetCharts Server Licenses may be locked to particular machines or machine configurations, so care must be taken to ensure the license will be valid on the machine where the target application server is running.
 

Configuring an Embedded Server Working Directory

 
NetCharts Server requires access to a working directory at runtime. This directory serves a number of purposes. It holds configuration files that contain runtime properties for the embedded NetCharts Server.
 
It holds the NetCharts Server project files for all web applications hosted on this server. It also contains security and authentication databases.
 
Configure the working directory as follows:

1. Identify a location for the working directory that will be accessible to the application server.
2. Create the working directory, giving it some meaningful name (e.g. d:\NCSwork).
3. Copy the NetCharts Server’s license file, NetChartsServer.license, into the top level of this working directory (e.g. put NetChartsServer.license in D:\NCSWork).
4. Copy the NetCharts Server’s conf directory and contents to this working directory.
5. Copy the NetCharts Server’s html directory and contents to this working directory.
6. Create a subdirectory called root in this working directory.
7. Copy the NetCharts Server’s root/projects directory into the working directory’s root subdirectory created in the prior step.

Creating an Embedded Server Distribution

 
In most application servers, Apache Tomcat being the notable exception, NetCharts Server is embedded by deploying NetChartsServer.ear as a J2EE application. This EAR file must be created and configured using tools available in a standalone NetCharts Server Administrators console.
 
To create a configured EAR file for distribution, select the J2EE Integration link from the Utilities sub-panel on the Admin Console’s home page. Enter the following data on the form and click Save:

• Embedded Server Working Directory – The full path of the NetCharts Server working directory created in the previous step. This directory must reside on or be directly accessible to the machine on which the Application Server resides.
• Application Server Base URL – The base part of the URL used to access the Application Server. For example, http://mymachine:7001
• Additional Jars – Additional jars that should be included in NetChartsServer.ear. This listbox contains a list of jars that can optionally be included in the ear file. The list contains jars that have been added to the standalone NetCharts Server that is being used to create NetChartsServer.ear. These jars are most commonly data base drivers and NetCharts Server Process Modules that extend or customize the behavior of NetCharts Server. Click on and highlight the names of the jars to be included in the ear file.You will be prompted to download the EAR file that was created. Save it to disk in some temporary location, and follow the application server specific installation instructions below.

Accessing an Embedded NetCharts Server

 
Client applications access an embedded NetCharts Server by using the NetCharts Server Java/JSP toolkit. The toolkit can be downloaded from the API Toolkits section of the NetCharts Server Developer’s Console. The process of creating an application that accesses an embedded NetCharts Server is application server specific, but has these general steps.

1. Download the NetCharts Server Java/JSP toolkit from the Developer’s Console of a standalone NetCharts Server.
2. Unpack the toolkit into some temporary working directory, $NCSTOOLKIT.
3. Copy $NCSTOOLKIT/WEB-INF/ncstaglib.tld to $WEBAPP/WEB-INF.
4. Copy $NCSTOOLKIT/WEB-INF/lib/ncstoolkit.jar to $WEBAPP/WEB-INF/lib.
5. Copy additional jars from NetCharts Server into $WEBAPP/WEB-INF/lib. Requirements vary between application servers. The additional files are typically commons-httpclient.jar, commons-logging.jar and commons-codec.jar.
6. Modify the web.xml file for the client web application to include the following servlet declarations and EJB reference. The Java/JSP toolkit includes a JSP tag library and a servlet that performs image retrieval, which must be configured with the following web.xml deployment file elements:
   <servlet>
     <servlet-name>ResourceServlet</servlet-name>
      <servlet-class>netcharts.server.imagewriter.ResourceServlet</servlet-class>
      <init-param>
        <param-name>RetainImageInSession</param-name>
        <param-value>false</param-value>
      </init-param>
      <init-param>
        <param-name>NoCacheExtensions</param-name>
        <param-value>.swf</param-value>
      </init-param>
      <load-on-startup>1</load-on-startup>
   </servlet>
   <servlet-mapping>
      <servlet-name>ResourceServlet</servlet-name>
      <url-pattern>/getimage</url-pattern>
   </servlet-mapping>
   <servlet-mapping>
      <servlet-name>ResourceServlet</servlet-name>
      <url-pattern>/getresource</url-pattern>
   </servlet-mapping>
   <taglib>
      <taglib-uri>https://visualmining.com/taglibs/ncstaglib-1.0</taglib-uri>
      <taglib-location>/WEB-INF/tld/ncstaglib.tld</taglib-location>
   </taglib>
    
   <ejb-ref>
      <description>NetChartsServer EJB</description>
      <ejb-ref-name>NetChartsServerEJB</ejb-ref-name>
      <ejb-ref-type>Session</ejb-ref-type>
      <home>netcharts.server.ejb.NetChartsServerHome</home>
      <remote>netcharts.server.ejb.NetChartsServerRemote</remote>
   </ejb-ref>
7. Add the following directive to all JSP files that will reference the JSP Tag Library:<%@taglib uri=”https://visualmining.com/taglibs/ncstaglib-1.0″ prefix=”ncs”>
8. Create JSP files that make API calls to the embedded NetCharts Server. The following JSP files can be used to test for the correct deployment and configuration of an embedded NetCharts Server. These files can be inserted into a new or existing web application
   <%@ page import=”netcharts.server.api.NSWebToolKit” %>
   <%@ page import=”java.util.Hashtable” %>
   <%
   String chart = null;
   try {
   // Create a toolkit object.
   NSWebToolKit toolKit = new NSWebToolKit(“Examples/ToolkitExamples”);// Create the Hashtable to hold the chart request variables.
   // (NOTE: If the Hashtable == null, type=PNG is the default)
   Hashtable variables = new Hashtable();variables.put(“type”,”PNG”);
   variables.put(“THETITLE”, “Ticket Sales”);
   variables.put(“LINESETDATA”,”10,100,50,75″);chart=toolKit.getChartAsImageTag(“simpleline.cdx”, variables, request);
   } catch (Exception e) {
   chart=new String(“Chart generation failed: ” + e.toString());
   }
   %>
   <HTML>
   <BODY>
   <%=chart%>
   </BODY>
   </HTML><%@ taglib uri=”https://visualmining.com/taglibs/ncstaglib-1.0″ prefix=”ncs” %>
   <html>
   <body>
   <ncs:chart project=”Examples/ToolkitExamples” chart=”simpleline.cdx” drilldown=”false”>
   <ncs:variable name=”THETITLE” value=”Ticket Sales”/>
   <ncs:variable name=”LINESETDATA” value=”100,200,450,150″/>
   </ncs:chart>
   </body>
   </html>

Oracle WebLogic 10.3.4 Configuration

NetCharts Server can be embedded into WebLogic using the following process:

1. Install a standalone instance of NetCharts Server as described above
2. Create a NetCharts Server working directory as described above
3. Create NetChartsServer.ear as described above.
4. Start the WebLogic Administration Console.
5. Deploy NetChartsServer.ear as a J2EE Enterprise Application.
6. Start the NetCharts Server application.
7. Create an application that accesses NetCharts Server as described above.
8. a. In addition, add a reference to the embedded NetCharts Server EJB in the client application web.xml:<ejb-ref>
   <description>NetChartsServer EJB</description>
   <ejb-ref-name>NetChartsServerEJB</ejb-ref-name>
   <ejb-ref-type>Session</ejb-ref-type>
   <home>netcharts.server.ejb.NetChartsServerHome</home>
   <remote>netcharts.server.ejb.NetChartsServerRemote</remote>
   </ejb-ref>
   also with WebLogic, the taglib needs to be wrapped in jsp-config tags as such:
   <jsp-config>
   <taglib>
   <taglib-uri>https://visualmining.com/taglibs/ncstaglib-1.0</taglib-uri>
   <taglib-location>/WEB-INF/ncstaglib.tld</taglib-location>
   </taglib>
   </jsp-config>
   b. Add an EJB reference descriptor to the client applications weblogic.xml file.
   <weblogic-web-app xmlns=”http://www.bea.com/ns/weblogic/90″>
      <ejb-reference-description>
      <ejb-ref-name>NetChartsServerEJB</ejb-ref-name>
      <jndi-name>NetChartsServerEJB</jndi-name>
      </ejb-reference-description>
   </weblogic-web-app>
9. Deploy and run the test application.

IBM WebSphere 7.0 Configuration

NetCharts Server can be embedded into WebSphere using the following process:

1. Install a standalone instance of NetCharts Server as described above.
2. Create a NetCharts Server working directory as described above.
3. Create NetChartsServer.ear as described above.
4. Start the WebSphere Administration Console
5. Deploy NetChartsServer.ear as a J2EE Enterprise Application. Specify the JNDI lookup nameNetChartsServerEJB.
6. Start the NetCharts Server application.
7. Create an application that accesses NetCharts Server as described above.a. Ensure commons-logging.jar, commons-httpclient.jar and commons-codec.jar are copies from the common/lib subdirectory of the standalone instance of NetCharts Server into the client applications WEB-INF/lib directory
    
   b. WebSphere does not automatically configure client application access to the NetCharts Server EJB stubs, so this access must be configured explicitly. Copy the file ncs-ejb.jar from the embedded NetCharts Server deployment directory into the client application’s WEB-INF/libdirectory. Note this ncs-ejb.jar must be copied from the deployment directory within WebSphere where NetCharts Server was deployed. If the NetCharts Server ear is subsequently re-deployed, a new copy of ncs-ejb.jar must be copied into each client application.
    
   c. WebSphere requires a context root be specified when installing a client application. The value used for this context root must be reflected in the ImageWriter servet mapping in the web.xml file.
   <servlet-mapping>
      <servlet-name>getimage</servlet-name>
      <url-pattern>your_application_context_root/getimage</url-pattern>
   </servlet-mapping>
   d. Specify NetChartsServerEJB as the JNDI lookup name for the embedded NetCharts Server.
8. Deploy and run the test application.

JBoss 5 and 6.0 Application Server

NetCharts Server can be embedded into JBoss using the following process.

1. Install a standalone instance of NetCharts Server as described above.
2. Create a NetCharts Server working directory as described above.
3. Create NetChartsServer.ear as described above
4. Deploy NetChartsServer.ear as a J2EE Enterprise Application
5. Create an application that accesses NetCharts Server as described above.
   a. Ensure commons-logging.jar, commons-httpclient.jar and commons-codec.jar are copies from the common/lib subdirectory of the standalone instance of NetCharts Server into the client applications WEB-INF/lib directory.
   b. Add an EJB reference descriptor to the client applications jboss-web.xml file.
   
   <class-loading>
      <loader-repository>visualmining.com:archive=NetChartsServer.ear</loader-repository>
   </class-loading>

   <!– A reference to an EJB in the same server with custom EJB binding –>
   <ejb-ref>
      <ejb-ref-name>NetChartsServerEJB</ejb-ref-name>
      <jndi-name>NetChartsServer/NetChartsServerEJB</jndi-name>
   </ejb-ref>

6. Deploy and run the test application.

Some JBoss version class loading works somewhat differently than other market leading application containers. The configuration changes we are suggesting to run NetCharts Server as an EAR may have effects upon other applications running in your JBoss environment. Please be sure to test thoroughly.
 
Ensure that the following configuration files on JBOSS have these settings:

• $JBOSS/server/default/conf/jboss-service.xml: NamingService CallByValue set to true:
  
  <mbean code=”org.jboss.naming.NamingService”
  …
  <attribute name=”CallByValue”>true</attribute>
  …
  </mbean>
• $JBOSS/server/default/deploy/ear-deployer.xml: Isolated and CallByValue attributes set to true:
  
  <server>
  <!– EAR deployer, remove if you are not using ear deployments –>
  <mbean code=”org.jboss.deployment.EARDeployer” name=”jboss.j2ee:service=EARDeployer”>
  …
  <attribute name=”Isolated”>true</attribute>
  …
  <attribute name=”CallByValue”>true</attribute>
  </mbean>
  </server>
• $JBOSS/default/deploy/jbossweb-tomcat50.sar/META-INF/jboss-service.xml: the Java2ClassLoadingCompliance attribute set to true and UseJBossWebLoader attribute to false:
  
  <server>
  <mbean code=”org.jboss.web.tomcat.tc5.Tomcat5″ name=”jboss.web:service=WebServer”>
  <attribute name=”Java2ClassLoadingCompliance”>true</attribute>
  ….
  <attribute name=”UseJBossWebLoader”>false</attribute>

JBoss 6.1.0 FINAL Application Server

NetCharts Server can be embedded into JBoss 6.1.0 FINAL using the following process:

1. Install a standalone instance of NetCharts Server as described above.
2. Create a NetCharts Server working directory as described above.
3. Create NetChartsServer.ear as described above
4. Modify the META-INF\jboss-app.xml file within NetChartsServer.ear.
   a. Open NetChartsServer.ear using an application that can read and edit compressed files (e.g. WinZip, 7Zip, etc.).
   b. Browse to the META-INF\jboss-app.xml file. Highlight the file and select Edit.
   c. Uncomment theloader-repository element, changing:
   <!–
     <loader-repository>visualmining.com:loader=NetChartsServer.ear</loader-repository>
   –>
   to
   <loader-repository>visualmining.com:loader=NetChartsServer.ear</loader-repository>
   d. Save the file and allow the application to update the file within NetChartsServer.ear.
5. If you have chosen to include additional jar files into the EAR as part of step #3, these jars must be added to the classpath of the EJB in order to be usable. Modify the META-INF/MANIFEST.MF file within the ncs-ejb.jar file, which itself is within the NetChartsServer.ear file, using a plain text editor or the built-in editor of your compressed file application.
   a. Open NetChartsServer.ear using an application that can read and edit compressed files (e.g. WinZip, 7Zip, etc.).
   b. Browse to the ncs-ejb.jar file and select Open, making sure to open it within a new instance of the application that currently has NetChartsServer.ear open (e.g. WinZip, 7Zip, etc.)
   c. Browse to the META-INF\MANIFEST.MF file. Highlight the file and select Edit.
   d. Locate the Class-Path section in the file. It will occupy multiple lines. The section should look something like this:
   Class-Path: avalon-framework-4.2.0.jar batik-all-1.7.jar commons-httpc
    lient.jar commons-codec.jar commons-logging-1.0.4.jar commons-io-1.3.
    1.jar conditionalcolorspm.jar fop.jar hsqldb.jar jai_codec.jar jai_co
    re.jar JimiProClasses.jar mlibwrapper_jai.jar ncp-api.jar ncp-image.j
    ar ncs.jar ncs-pms.jar ncs-css.jar nekohtml.jar netcharts.jar netchar
    ts-common.jar pngencoder.jar xalan-2.7.0.jar resolver.jar serializer-
    2.7.0.jar xercesImpl-2.7.1.jar xml-apis-1.3.04.jar xml-apis-ext-1.3.0
    4.jar xmlgraphics-commons-1.4.jar
   e. Add the filenames of the additional jars you selected as part of step #3 to the end of this section. It is important to retain the same spacing and line size structure when editing this section. For instance, if you included the sqljdbc4.jar file in step #3, then the modified section should look like this:
   Class-Path: avalon-framework-4.2.0.jar batik-all-1.7.jar commons-httpc
    lient.jar commons-codec.jar commons-logging-1.0.4.jar commons-io-1.3.
    1.jar conditionalcolorspm.jar fop.jar hsqldb.jar jai_codec.jar jai_co
    re.jar JimiProClasses.jar mlibwrapper_jai.jar ncp-api.jar ncp-image.j
    ar ncs.jar ncs-pms.jar ncs-css.jar nekohtml.jar netcharts.jar netchar
    ts-common.jar pngencoder.jar xalan-2.7.0.jar resolver.jar serializer-
    2.7.0.jar xercesImpl-2.7.1.jar xml-apis-1.3.04.jar xml-apis-ext-1.3.0
    4.jar xmlgraphics-commons-1.4.jar sqljdbc4.jar
   f. Save the file and allow the application to update the file within ncs-ejb.jar.
   g. Close the instance of the application that has ncs-ejb.jar open. Allow the application to update the ncs-ejb.jar file within NetChartsServer.ear.
   h. Close the application that has NetChartsServer.ear open.
6. Deploy NetChartsServer.ear as an Enterprise Application either through the Admin Console or by placing NetChartsServer.ear in the deploy folder.
7. Create an application that accesses NetCharts Server as described above.
   a. Ensure commons-logging.jar, commons-httpclient.jar and commons-codec.jar are copies from the common/lib subdirectory of the standalone instance of NetCharts Server into the client applications WEB-INF/lib directory.
   b. Reference the proper classloader and add an EJB reference descriptor to the client application jboss-web.xml file.
   <jboss-web>
     <class-loading>
      <loader-repository>visualmining.com:archive=NetChartsServer.ear</loader-repository>
     </class-loading>
     <ejb-ref>
      <ejb-ref-name>NetChartsServerEJB</ejb-ref-name>
      <jndi-name>NetChartsServer/NetChartsServerEJB</jndi-name>
     </ejb-ref>
   </jboss-web>
8. Deploy and run the test application.

Apache Tomcat 5.5

Because Tomcat does not support J2EE enterprise applications, NetCharts Server is embedded by copying jar files into Tomcat’s common library directories. Configure your Tomcat installation as follows:

1. Install a standalone instance of NetCharts Server as described above.
2. Create a NetCharts Server working directory as described above.
3. Copy the following jar files from the temporary NetChart Server’s common\lib directory to thecommon/lib directory of your Tomcat installation:avalon-framework-4.2.0.jar
   batik-all-1.7.jar
   commons-httpclient.jar
   commons-logging-1.0.4.jar
   commons-codec.jar
   conditionalcolorspm.jar
   fop.jar
   glf.jar
   hsqldb.jar (only needed for examples)
   jai_codec.jar
   jai_core.jar
   JimiProClasses.jar
   jug-asl-2.0.1.jar
   mlibwrapper_jai.jar
   ncp-api.jar
   ncp-image.jar
   ncs.jar
   ncs-pms.jar
   ncs-css.jar
   netcharts.jar
   netcharts-common.jar
   nekohtml.jar
   resolver.jar
   serializer-2.7.0.jar
   xalan-2.7.0.jar
   xercesImpl-2.7.1.jar
   xml-apis-1.3.04.jar
4. Create an application that accesses NetCharts Server as described above.a. There should be no NetCharts Server jars in the client application’s WEB-INF/lib directory. All required libraries must be accessed through Tomcat’s common/lib directoryb. Add the following <init-param> sections to the ImageWriter servlet section of the web.xml in your client application Configure the <param-value> sections to your particular values but do not change the <param-name> values:<servlet>
   <servlet-name>ResourceServlet</servlet-name>
   <servlet-class>netcharts.server.imagewriter.ResourceServlet</servlet-class>
   <init-param>
   <param-name>RetainImageInSession</param-name>
   <param-value>false</param-value>
   </init-param>
   <init-param>
   <param-name>ncsworkingdir</param-name>
   <param-value>d:\NCSwork</param-value>
   </init-param>
   <init-param>
   <param-name>ncsbaseurl</param-name>
   <param-value>http://localhost:8080</param-value>
   </init-param>
   <load-on-startup>1</load-on-startup>
   </servlet><servlet-mapping>
   <servlet-name>ResourceServlet</servlet-name>
   <url-pattern>/getresource</url-pattern>
   </servlet-mapping><servlet>
   <servlet-name>getimage</servlet-name>
   <servlet-class>netcharts.server.imagewriter.ImageWriter</servlet-class>
   <init-param>
   <param-name>ncsworkingdir</param-name>
   <param-value>d:\NCSwork</param-value>
   </init-param>
   <init-param>
   <param-name>ncsbaseurl</param-name>
   <param-value>http://localhost:8080</param-value>
   </init-param>
   <load-on-startup>1</load-on-startup>
   </servlet>

   <servlet-mapping>
   <servlet-name>ImageWriter</servlet-name>
   <url-pattern>/getimage</url-pattern>
   </servlet-mapping>

5. Deploy and run the test application.

Troubleshooting

 
This section provides an overview of the NetCharts Server debugging functions as well as a description of potential trouble areas.

Debugging Tools

 
NetCharts Server provides three separate logs – the debug log, the message log, and the error log. These logs can be used to help identify and clarify development problems.
 
Debug Panel
 
The debug panel may be viewed by selecting the Debug link from the Administrator Console’s control panel. The debug panel controls the output into the debug log and provides links to the log.
 

 
The debug panel allows the developer to specify the type of debug information that is desired. To see debug information, the developer would select the debug attribute, run the function that requires debugging, and then view the results by selecting the Show Log or Show Log (New Window) link.
 
The table below describes the meaning of each of the debug attributes.

 
When any of the debug attributes is activated, both the attribute and the ALL attribute will show as “ON”.
 
Debugging incurs a fairly significant performance degradation. Debugging should be turned OFF in any production environment to maximize performance, and only used when a problem requires investigation.
 
The Error Log
 
The error log can be viewed by selecting the Error Log link in the Administrator Console’s control panel. The error log contains all messages written to “standard error”, a common reporting interface for programmatic errors. Since NetCharts Server is Java-based, many error messages may be the result of stack traces requested by the program when an error occurs.
 
The Message Log
 
The message log is very similar to the error log, and can be viewed by selecting the Message Log link in the Administrator Console’s control panel. The message log contains all messages written to “standard out”, a common reporting interface for routine programmatic information.

Resolving Common Administrative Issues

 
The following list describes some common administrative error conditions or issues. Administrators may also want to check the Release Notes available from the documentation homepage, (accessible thru the link on the top navigation panel), for other information.
 
java.util.zip.ZipException
 
The error log may show messages like: Error unable to create jar cache in /tmp directory : java.util.zip.ZipException: error in opening zip file. This report is being generated by the underlying Apache engine and has no adverse effect on the NetCharts Server.
 
Out Of Memory Exceptions
 
Some environments may run into Out Of Memory exceptions with large data sets, or high user load. This can be avoided by increasing the Java Virtual Machine (JVM) heap size. The heap size can be adjusted by increasing the MaxJavaHeapSize parameter in the Window’s registry, or if on Unix, changing the NetChartsServer script to use more than 128m. Changing the value to 512m will work fine for most environments. See the NetCharts Server Service/Daemon Parameters section.

NetCharts Server Caching

 
NetCharts Caching is a powerful ally in performance, but may cause some confusion and lead users to believe that there is something wrong when their charts do not update as expected.
 
NetCharts Server uses two caches, one for chart images and one for the data retrieved and used to populate charts, tables and other report elements. Cached items are stored and retrieved using cache keys. A cache key is an identifier that uniquely identifies a cached data object.
 
The data cache is stored in memory. All data objects in an instance of NetCharts Server are cached in a single data cache. The cache key is user definable and care must be taken to generate unique keys for each entry.

The chart cache is stored on disk in the file system. The cache is hierarchical, with directories for each project and subdirectories for each chart. The cache key for a chart image is used to name the associated image file on disk. The cache key for a chart is constructed from the request attributes that accompany a chart request – essentially what follows the “?” from a chart request URL and the chart’s dimensions. The location of the chart image cache on disk is configurable in the NetCharts Server Administrator’s console.
 
HTML Table objects are not cached in NetCharts Server, although their data is cached in the data cache.
 
When a user requests a chart from NetCharts Server the following logic takes place on NetCharts Server.
 

 

Chart Cache Administration

 
The chart cache behavior is governed by a set of configurable parameters defined in the Performance link in the Server Configuration group of the Admin Console. Server defaults for Chart Cache are set here by the following parameters:
 
Redraw Interval
 
This is the TTL (time to live) default for all charts on NetCharts Server. The value is set in milliseconds. By default it is set to -1 which means that cached images never expire. This means, that even if the underlying data changes, the chart will never change. Alter this parameter to set a global maximum lifespan for all chart images generated by NetCharts Server.
 
Images per Chart and Cache Purge Percentage collectively effect

1. the maximum and minimum number of chart images per template in the cache
2. the event that reduces the maximum to the minimum

Images per Chart
 
For every chart template (.cdx file) there may be one or more cached images generated from that template in the File Cache. Images per Chart specifies a common limit used for each template. An event is triggered when that limit is reached, and chart images are automatically deleted. By default, NetCharts Server will cache 50 images of a chart template.
 
Cache Purge Percentage
 
After the Images per Chart value is reached (see above), an event it triggered where NetCharts Server will delete from the cache the oldest items (images for a given chart template) by a percentage specified in Cache Purge Percentage of Images per Chart. By default, NetCharts Server will delete 50%, or ½ of the chart images in the cache.
 
This means that by default, NetCharts Server will create a maximum of 50 chart images per template. When the 50th chart image is requested, NetCharts Sever will delete the 25 oldest chart images from the cache. Alter Images per Chart and Chart Cache percentage to effect:

1. the total amount of storage required for cached images
2. the frequency with which charts are re-rendered
3. the frequency with which request are made to the database
4. the degree to which chart images are preserved and rendering overhead is prevented
5. the lifespan of cached charts based on the frequency of requests for unique images

Data Cache

 
Data Cache values are set in each .ndx template individually via the Lifespan edit box in the Data Object wizard under Data Cache (optional), or the CacheLifeSpan parameter. Additionally, cacheRefresh=true will disable data caching for that template.

Data Cache Keys

 
Every data object cached is identified by a cache key. The cache key is a text string of any format that must uniquely identify any object in the data cache. Every possible permutation of every data object cached must have a unique key. There are three attributes that uniquely distinguish a data cache item:

1. The project (or sub-directory within) from which the object comes
2. The name of the object itself
3. Request parameters (variables that alter the result of the object)

Project
 
Since a project corresponds to a sub-directory in the file system, objects in different projects can have the same name. Therefore the project name should be part of the cache key. NetCharts Server by default provides the project name as the first part of the cache key.

 
Object Name
 
The object name (the name of the file that contains the template parameters) itself is a necessary component of uniquely identifying an object in the cache. NetCharts Server, by default, provides the name of the object prefixed by a hyphen “-” in the cache key.
 
Request Parameters
 
Some elements of the request for data are dynamic. These are implemented as variables. Usually data variables are arguments to WHERE and/or ORDER BY clauses, but they can supply any portion of an ndx parameter. All variable processing in NetCharts Server is achieved by text replacement. Wherever, in the data template definition, the character string of the variable name exists, the character string of the variable value replaces it. Therefore, it is recommended that variables should be appended to the cache key, prefixed by a hyphen “-“.
 

Chart image, and image map hash values

 
All Chart images (and their optional associated html image maps if drilldown is enabled) are stored in files with names derived from a hash of the cache key value. The value is calculated from a text string created by concatenating the name of the chart, the dimensions of the chart, and the variable and value pairs from the URL request.
 
All chart images (and image maps) are located in a sub-directory named from the name of the chart template. This sub-directory is subordinate to another sub-directory named for the project.
 
So, requesting a chart from:

http://server:8001/projects/projectName/chart.cdx?type=png

results in a hash being created from the chart size and the character string type=png. If multiple variables are used, then the string processed used to create the hash value contains both keyword/value pairs:

http://server:8001/projects/projectName/chart.cdx?type=png&drilldown=true

would use the chart size and type=png&drilldown=true to generate the hash value.

A Caching Example: Asset Allocation Pie Chart

A project 401Kproject exists with one data connection object 401Kdata.ndx and one pie chart 401Kpie.cdx. 401Kdata.ndx has two variables; varEmployee and varPlan, and has the following SQL:

SELECT allocation_mix FROM allocation_mix_vw WHERE stock_user=varEmployee AND plan=varPlan

Consider the following 2 chart request URLs:

http://server- name:8001/projects/401Kproject/401Kpie.cdx?type=png&drilldown=true&varEmployee=jsmith&varPlan=merrill

http://server-name:8001/projects/401Kproject/401Kpie.cdx?type=png&drilldown=true&varEmployee=pjones&varPlan=merrill

2 data objects in the Data Cache in memory

1 sub-directory in the Chart Cache for the project

1 sub-directory subordinate to the above sub-directory containing

2 chart image files

2 image map files

For the first example, when NetCharts Server receives the request, it takes the entire character string following the ?, in the case type=png&drilldown=true&varEmployee=jsmith&varPlan=merril and calculates a hash value. The value of the hash value is 914109572.
 
NetCharts Server looks for cached images of the charts in the chart image cache on disk:

C:\Program Files\Visual Mining\NetCharts Server\Server\temp\imagecache\projects\401Kproject

and searches for two files; 914109572.html and 914109572.png.

Neither of the desired objects exist in the chart cache, so NetCharts Server will have to render them. NetCharts opens the 401Kpie.cdx chart template and locates the data references (aka the NDX references). The referenced NDX file contains database connection information and the SQL query template. Values for variables are substituted into the query template and the query is dispatched to the appropriate data source. In this example, wherever in the SQL string the variable names exist (WHERE stock_user=varEmployee AND plan=varPlan), varEmployee and varPlan are replaced with jsmith and merril respectively, so the WHERE clause reads (WHERE stock_user=jsmith AND plan=merrill) before submission to the database.
 
A result set is returned. In order to place the result set into the data cache, a key is required. The cache key for the data object follows the recommended pattern of projectname-ndxname-variable(s), and is coded: 401Kproject-401Kdata-varEmployee-varPlan. Everything required to generate a data cache entry exists. A Data Cache key of 401Kproject-401Kdata-jsmith-merrill is generated and both it and the result set are related to each other, and placed in memory resident Data Cache:
 

 
With the values from the data base available, it’s possible to resolve the remaining CDL parameters and provide the rendering engine exactly what it needs to create an image of the chart, and an image map.
 
The “ImageCacheRootDir” parameter is referenced to locate the high level sub-directory for the “image cache”, and a sub-directory named for the project “401Kproject” is allocated subordinate to it, and with that sub-directory, another sub-directory named for the chart “401Kpie.cdx” is allocated.
 
Both are generated and placed in the disk resident Chart Cache:
 

 
NetCharts Server then satisfies the request from the .png and .html files placed in the image cache. Any subsequent request for the same chart with the same URL, NetCharts Server satisfies the request from the entries in the Chart Cache. If a subsequent request is issued for “pjones” as per the URL specified above, the Data Cache and Chart Cache will appear as follows:
 

 

Managing Cache and Caching Strategies

 
So how do you manage caching? There are several strategies for managing caching in NetCharts Server, all of which revolve around the interval over which the chart will remain current. Therefore the primary consideration for choosing a caching strategy is the obsolescence of the data displayed in the chart image.

1. No Cache: If your charts must display up the instant data, then don’t bother caching them all. Specify redraw=true, either in the URL string, or in a hashtable when requesting the chart, e.g.:

   chart_N1002F.put(“redraw”,”true”);
   myChart = toolKit.getChartAsImageAndMap(“barChart.cdx”, chart_N1002F, …);

   The above can be effected globally for all charts, by setting the Redraw Interval under the Performance link in the Server Configuration group of the Admin Console to 0 milliseconds.

2. Global cache limit: If a predetermined interval of time is desired for each chart image, it is possible to establish that limit for all charts globally by setting the Redraw Interval under the Performance link in the Server Configuration group of the Admin Console to whatever time interval is desired. No chart in the Chart Cache can ever last longer than that limit, guaranteeing chart images will update, and display data no older than that time interval.
3. Explicit cache purge: NetCharts Sever has a mechanism that can purge all cached images for a specific project. This is available either via a link on the Admin Console, or through an API. Additionally a NetCharts Server Task can be initiated that can perform this function. For example, an ETL process may reload a data warehouse referenced by NetCharts Server once every night. A task can be scheduled to run after the ETL is done, erasing all chart images rendered with the obsolete data. The next request for any chart from the new data will cause NetCharts Server to render a new image. Any subsequent request for a chart image will be serviced from the Chart Cache until the next ETL.
4. Limit the number of Cached objects: Sometimes a limited number of charts must be maintained in the cache. For example, it may be desirable to have data for the current hour, and historical data for the previous 24 hours. A timestamp specifying the current hour, or an hour among the previous 24 must be supplied with the request for the image. In this case, an Images per Chart value of 25, and a Cache Purge Percentage of .04 (1/25th) would be set. In this way every 26th chart would cause the oldest chart image to be erased. The above example assumes a request for each new hour occurs every hour. Otherwise historical data beyond 24 hours old could intermittently be available.
   NOTE: A compliment to the above strategy is to define a task, or set of tasks to request all, or the most frequently requested charts immediately after the cache is purged. This “pre-caches” chart images and image maps before the first request is made, saving the overhead of doing so at execution time.
5. Individually controlled cache limit: This is by far the most versatile way of controlling cached images, but it’s also the most programmer intensive. If you want to individually control the cache time on each chart, you can introduce a “dummy date” variable to your NDX that does not need to be used in your SQL Query. Call it varDate. Then in your PGL you can include an Optional Code tag (or this can just be in your JSP code) that will push this value down to the chart at run time. Based on how you format the date you can control caching to varying degrees of time interval granularity. i.e. if you want to do it by hour, just set the date value format to be yyyymmddhh. Now every time this chart is requested, a time stamp is passed. If the chart was requested around 1 PM the cache key will be 2006071413. When it is requested again at 1:35 PM it will still have the same cache key and just return the same chart image. However, when the chart is requested at 2 PM the cache key will change to 2006071414 and a new chart will be drawn going all the way back to your database (if you use the default data cache of 3 seconds) to get your data.

Where can I go for additional resources and help?

In addition to the online help there are three additional places where you can obtain assistance:

• Visual Mining Customer Support Portal: Here you will find FAQS, tips and tricks and links to other resources that will help you create dashboards.
• Your Visual Mining Account Representative – send them an email, or call them. In case you’re not sure who your account rep is, send an email to sales@visualmining.com.
• Send us a question via Visual Mining support: support@visualmining.com or Phone 1.301.795.2200, or Toll-Free within the continental US: 800.308.0731