netcharts.server.api
Class NSToolKit

java.lang.Object
  |
  +--netcharts.server.api.NSToolKit

Direct Known Subclasses:

NSPortletToolKit, NSWebToolKit

public class NSToolKit

extends java.lang.Object

Provides API to request data, tables, and charts and to store/retrieve cache elements.

Field Summary

static java.lang.String	PARAM_NODATA_MESSAGE
static java.lang.String	PROJECTS
static java.lang.String	TOOLKIT_USER_AGENT

Constructor Summary

NSToolKit()
Constructs a toolkit with no communication information and no security credentials.

NSToolKit(java.lang.String projectName)
Constructs a toolkit with no security credentials.

NSToolKit(java.lang.String serverName, int portNumber, java.lang.String projectName)
Constructs a toolkit with communication information and no security credentials.

NSToolKit(java.lang.String serverName, int portNumber, java.lang.String projectName, java.lang.String userName, java.lang.String userPassword)
Constructs a toolkit with communication information and security credentials.

NSToolKit(java.lang.String serverName, int portNumber, java.lang.String projectName, java.lang.String userName, java.lang.String userPassword, boolean secure)
Constructs a toolkit with communication information and security credentials.

NSToolKit(java.lang.String projectName, java.lang.String userName, java.lang.String userPassword)
Constructs a toolkit with security credentials.

Method Summary

boolean	getAccessibilityMode() Get the Accessibility Mode.
java.lang.String	getAMActiveLabelTextTemplate() Get the text template used to construct alt tags on the active regions of a drill down image (map area tags).
java.lang.String	getAMChartDescription() Get the description to be used in the alt tag on chart images.
ServerGeneratedImage	getChart(java.lang.String chartFile, java.util.Hashtable variables) Retrieves a chart and returns a ServerGeneratedImage representing the chart.
ServerGeneratedImage	getChart(java.lang.String chartFile, java.util.Hashtable variables, boolean createImageMap) Retrieves a chart and returns a ServerGeneratedImage representing the chart.
java.lang.String	getChartPage(java.lang.String chartFile, java.util.Hashtable variables, java.lang.String imageFileName, boolean overwriteImageFile, java.lang.String imageSource) Retrieves a chart, saves the generated chart image to a specified file on your local hard drive and returns the generated HTML page including the <img> tag and associated HTML image map.
java.lang.String	getChartPage(java.lang.String chartFile, java.util.Hashtable variables, java.lang.String imageFileName, boolean overwriteImageFile, java.lang.String imageSource, boolean createImageMap) Retrieves a chart, saves the generated chart image to a specified file on your local hard drive and returns the generated HTML page including the <img> tag and associated HTML image map if requested.
java.lang.Object[][]	getDataCacheEntry(java.lang.String cacheKey, boolean refreshCacheEntry) Return the data cached under the given cache key.
java.lang.String	getDataCacheEntryAsNCXML(java.lang.String cacheKey, boolean refreshCacheEntry) Return the data cached under the given cache key.
java.sql.ResultSet	getDataCacheEntryAsResultSet(java.lang.String cacheKey, boolean refreshCacheEntry, boolean useFirstRowAsColumnNames) Return the data cached under the given cache key as a ResultSet.
java.lang.String	getEncoding() Deprecated. Encoding is now determined from server replies and does not need to be set on the toolkit.
java.lang.Object[][]	getNDSData(java.lang.String ndsFile, java.util.Hashtable variables) Retrieves NDS data from NetCharts Server.
java.lang.String	getNDSDataAsCSV(java.lang.String ndsFile, java.util.Hashtable variables, char delimiter) Retrieves NDS data from NetCharts Server and puts it into a format easily imported into MS-Excel
java.lang.String	getNDSDataAsNCXML(java.lang.String ndsFile, java.util.Hashtable variables) Retrieves NDS data from NetCharts Server and puts it into the NCXML format.
java.sql.ResultSet	getNDSDataAsResultSet(java.lang.String ndsFile, java.util.Hashtable variables, boolean useFirstRowAsColumnNames) Retrieves NDS data from NetCharts Server and puts it into a java.sql.ResultSet.
java.util.Vector	getNDSDataAsVector(java.lang.String ndsFile, java.util.Hashtable variables) Retrieves a data set from NetCharts Server and puts it into a Vector.
byte[]	getPDFReport(java.lang.String pglFile, java.util.Hashtable variables) Retrieves a PDF report based on a PGL template from NetCharts Server.
byte[]	getPDFTable(java.lang.String tableName, java.util.Hashtable variables)
static java.lang.String	getRolloverJavaScript() Return the JavaScript and <div> tag used for chart interactivity.
ServerGeneratedTable	getServerGeneratedTable(java.lang.String tableFile, java.util.Hashtable variables) Retrieves a table.
ServerGeneratedTable	getServerGeneratedTable(java.lang.String tableFile, java.util.Hashtable variables, java.lang.Object[][] tableData) Retrieves a table.
chartworks.es.util.ServerReply	getServerReply(java.lang.String serverFile, java.util.Hashtable variables) Retrieves a response via HTTP.
java.lang.String	getTable(java.lang.String tableFile, java.util.Hashtable variables) Retrieves a table.
java.lang.String	getTable(java.lang.String tableFile, java.util.Hashtable variables, java.lang.Object[][] tableData) Retrieves a table.
java.lang.String	getUserAgent() Get the user agent type, which by default is NetChartsServer Java ToolKit (Remote)
void	putDataCacheEntry(java.lang.String cacheKey, java.lang.Object[][] data, int lifeSpan) Puts data element into the cache with the given cache key.
void	putDataCacheEntry(java.lang.String cacheKey, java.sql.ResultSet data, int lifeSpan) Puts data from a ResultSet into the cache with the given cache key.
void	putDataCacheEntry(java.lang.String cacheKey, java.lang.String ncxml, int lifeSpan) Puts data formatted as NetCharts XML (NCXML) into the cache with the given cache key.
void	putDataCacheEntry(java.lang.String cacheKey, java.lang.String xml, java.lang.String xmlParserClassName, int lifeSpan) Puts data formatted as XML into the cache with the given cache key.
void	removeDataCacheEntry(java.lang.String cacheKey) Removes the named data element from the data cache.
void	removeHeader(java.lang.String name)
void	setAccessibilityMode(boolean accessibilityMode) Enable or disable Accessibility Mode.
void	setAMActiveLabelTextTemplate(java.lang.String amActiveLabelTextTemplate) Set the text template used to construct alt tags on the active regions of a drill down image (map area tags).
void	setAMChartDescription(java.lang.String amChartDescription) Set the description to be used in the alt tag on chart images.
void	setEncoding(java.lang.String encoding) Deprecated. Encoding is now determined from server replies and does not need to be set on the toolkit.
void	setHeader(java.lang.String name, java.lang.String value)
void	setProject(java.lang.String projectName) Resets the project to consider the root directory of the server files.
void	setServerInfo(java.lang.String serverName, int portNumber) Resets the server communication information.
void	setUserAgent(java.lang.String userAgent) Set the user agent type, e.g.
void	setUserCredentials(java.lang.String userName, java.lang.String userPassword) Resets the security credentials of the toolkit.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PROJECTS

public static java.lang.String PROJECTS

TOOLKIT_USER_AGENT

public static final java.lang.String TOOLKIT_USER_AGENT

PARAM_NODATA_MESSAGE

public static final java.lang.String PARAM_NODATA_MESSAGE

Constructor Detail

NSToolKit

public NSToolKit()

Constructs a toolkit with no communication information and no security credentials.

NSToolKit

public NSToolKit(java.lang.String projectName)

Constructs a toolkit with no security credentials.

Parameters:

projectName - The project within NetCharts Server to access files.

NSToolKit

public NSToolKit(java.lang.String projectName,
                 java.lang.String userName,
                 java.lang.String userPassword)

Constructs a toolkit with security credentials.

Parameters:

projectName - The project within NetCharts Server to access files.

userName - The name of a NetCharts Server user with proper security credentials.

userPassword - The password of a NetCharts Server user with proper security credentials.

NSToolKit

public NSToolKit(java.lang.String serverName,
                 int portNumber,
                 java.lang.String projectName)

Constructs a toolkit with communication information and no security credentials.

Parameters:

serverName - The name of the server.

portNumber - The port of the server.

projectName - The project to consider the root directory of the server files.

NSToolKit

public NSToolKit(java.lang.String serverName,
                 int portNumber,
                 java.lang.String projectName,
                 java.lang.String userName,
                 java.lang.String userPassword)

Constructs a toolkit with communication information and security credentials.

Parameters:

serverName - The name of the server.

portNumber - The port of the server.

projectName - The project to consider the root directory of the server files.

userName - The name of a user with proper security credentials.

userPassword - The password of a user with proper security credentials.

NSToolKit

public NSToolKit(java.lang.String serverName,
                 int portNumber,
                 java.lang.String projectName,
                 java.lang.String userName,
                 java.lang.String userPassword,
                 boolean secure)

Constructs a toolkit with communication information and security credentials.

Parameters:

serverName - The name of the server.

portNumber - The port of the server.

projectName - The project to consider the root directory of the server files.

userName - The name of a user with proper security credentials.

userPassword - The password of a user with proper security credentials.

secure - Whether we are connected to a SSL based port.

Method Detail

setAccessibilityMode

public void setAccessibilityMode(boolean accessibilityMode)

Enable or disable Accessibility Mode. With Accessiblity Mode enabled the pages produced include accessibility features (such as alt tags) instead of the default javascript based popup labels.

getAccessibilityMode

public boolean getAccessibilityMode()

Get the Accessibility Mode.

setAMActiveLabelTextTemplate

public void setAMActiveLabelTextTemplate(java.lang.String amActiveLabelTextTemplate)

Set the text template used to construct alt tags on the active regions of a drill down image (map area tags). This template can include variable names from ImageMapCreator such as LABEL_REPLACE. This is only used when Accessibility Mode is enabled.

getAMActiveLabelTextTemplate

public java.lang.String getAMActiveLabelTextTemplate()

Get the text template used to construct alt tags on the active regions of a drill down image (map area tags).

setAMChartDescription

public void setAMChartDescription(java.lang.String amChartDescription)

Set the description to be used in the alt tag on chart images. This is only used when Accessibility Mode is enabled.

getAMChartDescription

public java.lang.String getAMChartDescription()

Get the description to be used in the alt tag on chart images.

getRolloverJavaScript

public static java.lang.String getRolloverJavaScript()

Return the JavaScript and <div> tag used for chart interactivity. This can be used to introduce the script code at any time during the page creation process. Commonly used when the final resultant page contains charts within tables.

Returns:

The JavaScript and <div> tag used for interactivity.

setUserCredentials

public void setUserCredentials(java.lang.String userName,
                               java.lang.String userPassword)

Resets the security credentials of the toolkit.

Parameters:

userName - The name of a user with proper security credentials.

userPassword - The password of a user with proper security credentials.

setServerInfo

public void setServerInfo(java.lang.String serverName,
                          int portNumber)

Resets the server communication information.

Parameters:

serverName - The name of the server.

portNumber - The port of the server.

setProject

public void setProject(java.lang.String projectName)

Resets the project to consider the root directory of the server files.

Parameters:

projectName - The project to consider the root directory of the server files.

setEncoding

public void setEncoding(java.lang.String encoding)

Deprecated. Encoding is now determined from server replies and does not need to be set on the toolkit.

Set the encoding used by the server we will connect to. This ensures that Strings created from the bytes returned from the server are constructed correctly.

getEncoding

public java.lang.String getEncoding()

Deprecated. Encoding is now determined from server replies and does not need to be set on the toolkit.

Get the encoding set on this toolkit.

getServerReply

public chartworks.es.util.ServerReply getServerReply(java.lang.String serverFile,
                                                     java.util.Hashtable variables)
                                              throws NSToolKitException

Retrieves a response via HTTP.

Parameters:

serverFile - The specified response from the server to retrieve.

variables - A HashTable contain variables to add to the request.

Returns:

ServerReply object containing the reply from NetCharts Server.

getTable

public java.lang.String getTable(java.lang.String tableFile,
                                 java.util.Hashtable variables)
                          throws NSToolKitException

Retrieves a table.

Parameters:

tableFile - The specified response from the server to retrieve.

variables - A HashTable contain variables to add to the request.

Returns:

String containing the HTML table.

getServerGeneratedTable

public ServerGeneratedTable getServerGeneratedTable(java.lang.String tableFile,
                                                    java.util.Hashtable variables)
                                             throws NSToolKitException

Retrieves a table.

Parameters:

tableFile - The specified response from the server to retrieve.

variables - A HashTable contain variables to add to the request.

Returns:

String containing the HTML table.

getTable

public java.lang.String getTable(java.lang.String tableFile,
                                 java.util.Hashtable variables,
                                 java.lang.Object[][] tableData)
                          throws NSToolKitException

Retrieves a table.

Parameters:

tableFile - The specified response from the server to retrieve.

variables - A HashTable contain variables to add to the request.

Returns:

String containing the HTML table.

getServerGeneratedTable

public ServerGeneratedTable getServerGeneratedTable(java.lang.String tableFile,
                                                    java.util.Hashtable variables,
                                                    java.lang.Object[][] tableData)
                                             throws NSToolKitException

Retrieves a table.

Parameters:

tableFile - The specified response from the server to retrieve.

variables - A HashTable contain variables to add to the request.

Returns:

ServerGeneratedTable object.

getChartPage

public java.lang.String getChartPage(java.lang.String chartFile,
                                     java.util.Hashtable variables,
                                     java.lang.String imageFileName,
                                     boolean overwriteImageFile,
                                     java.lang.String imageSource)
                              throws NSToolKitException

Retrieves a chart, saves the generated chart image to a specified file on your local hard drive and returns the generated HTML page including the <img> tag and associated HTML image map.

Parameters:

chartFile - The specified chart from the server to retrieve.

variables - A HashTable contain variables to add to the request.

imageFileName - The file on your local file system to save the chart to.

overwriteImageFile - Whether or not to overwrite the image file if it already exists.

imageSource - The value to placed within the src attibute of the <img> tag of the HTML page.

Returns:

The generated HTML page including the <img> tag, client-side JavaScript and associated HTML image map.

getChartPage

public java.lang.String getChartPage(java.lang.String chartFile,
                                     java.util.Hashtable variables,
                                     java.lang.String imageFileName,
                                     boolean overwriteImageFile,
                                     java.lang.String imageSource,
                                     boolean createImageMap)
                              throws java.lang.IllegalArgumentException,
                                     NSToolKitException

Retrieves a chart, saves the generated chart image to a specified file on your local hard drive and returns the generated HTML page including the <img> tag and associated HTML image map if requested.

Parameters:

chartFile - The specified chart from the server to retrieve.

variables - A HashTable contain variables to add to the request.

imageFileName - The file on your local file system to save the chart to.

overwriteImageFile - Whether or not to overwrite the image file if it already exists.

imageSource - The value to placed within the src attibute of the <img> tag of the HTML page.

createImageMap - Specifies whether or not to create the image map.

Returns:

The generated HTML page including the <img> tag, client-side JavaScript and associated HTML image map if generated..

getPDFReport

public byte[] getPDFReport(java.lang.String pglFile,
                           java.util.Hashtable variables)
                    throws java.lang.IllegalArgumentException,
                           NSToolKitException

Retrieves a PDF report based on a PGL template from NetCharts Server.

The following parameters are accepted when generating a PDF report. They may be passed by adding them to the Hashtable instance used when calling the getPDFReport API method.

Parameter	Description
page-height	Specifies the height of the pages. Consists of the number value and the value type. The valid types are in and cm. Example: 8.5in
page-width	Specifies the width of the pages. Consists of the number value and the value type. The valid types are in and cm. Example: 11in
margin-top	Specifies the top margin of the pages. Consists of the number value and the value type. The valid types are in and cm. Example: 1in
margin-right	Specifies the right margin of the pages. Consists of the number value and the value type. The valid types are in and cm. Example: 0.5in
margin-bottom	Specifies the bottom margin of the pages. Consists of the number value and the value type. The valid types are in and cm. Example: 0.75in
margin-left	Specifies the left margin of the pages. Consists of the number value and the value type. The valid types are in and cm. Example: 0.5in

Parameters:

pglFile - The PGL template within the NetCharts Server project.

variables - A HashTable containing variables to add to the request.

Returns:

The byte[] containing the PDF report to return.

Throws:

java.lang.IllegalArgumentException -

NSToolKitException -

getPDFTable

public byte[] getPDFTable(java.lang.String tableName,
                          java.util.Hashtable variables)
                   throws java.lang.IllegalArgumentException,
                          NSToolKitException

getChart

public ServerGeneratedImage getChart(java.lang.String chartFile,
                                     java.util.Hashtable variables)
                              throws java.lang.IllegalArgumentException,
                                     NSToolKitException

Retrieves a chart and returns a ServerGeneratedImage representing the chart.

Parameters:

chartFile - The specified chart template to retrieve.

variables - A HashTable containing variables to add to the request.

Returns:

ServerGeneratedImage representing the generated chart image.

getChart

public ServerGeneratedImage getChart(java.lang.String chartFile,
                                     java.util.Hashtable variables,
                                     boolean createImageMap)
                              throws java.lang.IllegalArgumentException,
                                     NSToolKitException

Retrieves a chart and returns a ServerGeneratedImage representing the chart.

Parameters:

chartFile - The specified chart template to retrieve.

variables - A HashTable containing variables to add to the request.

createImageMap - Specifies whether or not to create the image map.

Returns:

ServerGeneratedImage representing the generated chart image.

getNDSData

public java.lang.Object[][] getNDSData(java.lang.String ndsFile,
                                       java.util.Hashtable variables)
                                throws NSToolKitException

Retrieves NDS data from NetCharts Server.

Parameters:

ndsFile - The name of the NDS file representing this data set

variables - The set of key/value pairs to add to the query string.

Returns:

object array representing the data set.

getNDSDataAsCSV

public java.lang.String getNDSDataAsCSV(java.lang.String ndsFile,
                                        java.util.Hashtable variables,
                                        char delimiter)
                                 throws NSToolKitException

Retrieves NDS data from NetCharts Server and puts it into a format easily imported into MS-Excel

Parameters:

ndsFile - The name of the NDS file representing this data set.

variables - The set of key/value pairs to add to the query string.

delimiter - The delimiter used to separate the data values.

Returns:

String containing a CSV (Comma Separated Value) representation of the data. Each field is delimited with a comma, each row is delimited with a newline character.

getNDSDataAsNCXML

public java.lang.String getNDSDataAsNCXML(java.lang.String ndsFile,
                                          java.util.Hashtable variables)
                                   throws NSToolKitException

Retrieves NDS data from NetCharts Server and puts it into the NCXML format.

Parameters:

ndsFile - The name of the NDS file representing this data set

variables - The set of key/value pairs to add to the query string.

Returns:

String containing a NCXML representation of the data.

getNDSDataAsVector

public java.util.Vector getNDSDataAsVector(java.lang.String ndsFile,
                                           java.util.Hashtable variables)
                                    throws NSToolKitException

Retrieves a data set from NetCharts Server and puts it into a Vector.

Parameters:

ndsFile - The name of the NDS file representing this data set

variables - The set of key/value pairs to add to the query string.

Returns:

A vector of data from the given NDS. Data will be arranged in row-major order

getNDSDataAsResultSet

public java.sql.ResultSet getNDSDataAsResultSet(java.lang.String ndsFile,
                                                java.util.Hashtable variables,
                                                boolean useFirstRowAsColumnNames)
                                         throws NSToolKitException

Retrieves NDS data from NetCharts Server and puts it into a java.sql.ResultSet.

Parameters:

ndsFile - The name of the NDS file representing this data set.

variables - The set of key/value pairs to add to the query string.

useFirstRowAsColumnNames - Whether the first row of data should be used as the ResultSet's list of column names.

Returns:

A ResultSet representation of the data. Note, all columns will have a VARCHAR type.

putDataCacheEntry

public void putDataCacheEntry(java.lang.String cacheKey,
                              java.sql.ResultSet data,
                              int lifeSpan)
                       throws NSToolKitException

Puts data from a ResultSet into the cache with the given cache key.

Parameters:

cacheKey - The name to assign the cache element.

data - The data to store in the cache.

lifeSpan - The amount of time, in seconds, that the data will live in the cache. Note, if this call is associated with an .ndx file on disk (e.g. manual data set), make sure to first remove the cacheLifeSpan attribute from the .ndx or it will always override this property.

putDataCacheEntry

public void putDataCacheEntry(java.lang.String cacheKey,
                              java.lang.String ncxml,
                              int lifeSpan)
                       throws NSToolKitException

Puts data formatted as NetCharts XML (NCXML) into the cache with the given cache key.

Parameters:

cacheKey - The name to assign the cache element.

ncxml - The data to store in the cache.

lifeSpan - The amount of time, in seconds, that the data will live in the cache. Note, if this call is associated with an .ndx file on disk (e.g. manual data set), make sure to first remove the cacheLifeSpan attribute from the .ndx or it will always override this property

putDataCacheEntry

public void putDataCacheEntry(java.lang.String cacheKey,
                              java.lang.String xml,
                              java.lang.String xmlParserClassName,
                              int lifeSpan)
                       throws NSToolKitException

Puts data formatted as XML into the cache with the given cache key.

Parameters:

cacheKey - The name to assign the cache element.

xml - The data to store in the cache.

xmlParserClassName - The name of a class that implements the chartworks.es.plugin.XMLParserInterface. This class will be used to get at the data.

lifeSpan - The amount of time, in seconds, that the data will live in the cache. Note, if this call is associated with an .ndx file on disk (e.g. manual data set), make sure to first remove the cacheLifeSpan attribute from the .ndx or it will always override this property

putDataCacheEntry

public void putDataCacheEntry(java.lang.String cacheKey,
                              java.lang.Object[][] data,
                              int lifeSpan)
                       throws NSToolKitException

Puts data element into the cache with the given cache key.

Parameters:

cacheKey - The name to assign the cache element.

data - The data objects to store in the cache.

lifeSpan - The amount of time, in seconds, that the data will live in the cache. Note, if this call is associated with an .ndx file on disk (e.g. manual data set), make sure to first remove the cacheLifeSpan attribute from the .ndx or it will always override this property

removeDataCacheEntry

public void removeDataCacheEntry(java.lang.String cacheKey)
                          throws NSToolKitException

Removes the named data element from the data cache.

Parameters:

cacheKey - The name to assign the cache element

getDataCacheEntry

public java.lang.Object[][] getDataCacheEntry(java.lang.String cacheKey,
                                              boolean refreshCacheEntry)
                                       throws NSToolKitException

Return the data cached under the given cache key. If refreshCacheEntry is set, the named data in the cached entry is removed.

Parameters:

cacheKey - The name to assign the cache element

refreshCacheEntry - Whether or not to null the cache entry data.

Returns:

Object[][] containing the data cache entries, or null if no cache entry was found.

getDataCacheEntryAsNCXML

public java.lang.String getDataCacheEntryAsNCXML(java.lang.String cacheKey,
                                                 boolean refreshCacheEntry)
                                          throws NSToolKitException

Return the data cached under the given cache key. If refreshCacheEntry is set, the named data in the cached entry is removed.

Parameters:

cacheKey - The name to assign the cache element

refreshCacheEntry - Whether or not to null the cache entry data.

Returns:

String containing the data cache entry, or null if no cache entry was found.

getDataCacheEntryAsResultSet

public java.sql.ResultSet getDataCacheEntryAsResultSet(java.lang.String cacheKey,
                                                       boolean refreshCacheEntry,
                                                       boolean useFirstRowAsColumnNames)
                                                throws NSToolKitException

Return the data cached under the given cache key as a ResultSet. If refreshCacheEntry is set, the named data in the cached entry is removed.

Parameters:

cacheKey - The name assigned to the cache element

refreshCacheEntry - Whether or not to null the cache entry data.

useFirstRowAsColumnNames - Whether the first row of data should be used as the ResultSet's list of column names.

Returns:

A ResultSet representation of the data. Note, all columns will have a VARCHAR type.

getUserAgent

public java.lang.String getUserAgent()

Get the user agent type, which by default is NetChartsServer Java ToolKit (Remote)

Returns:

User Agent property

setUserAgent

public void setUserAgent(java.lang.String userAgent)

Set the user agent type, e.g. set a URLEvent as a distinct user agent

Parameters:

userAgent -

setHeader

public void setHeader(java.lang.String name,
                      java.lang.String value)

removeHeader

public void removeHeader(java.lang.String name)