netcharts.server.api
Class NSToolKit

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

Direct Known Subclasses:

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	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

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() Get the encoding set on this 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.
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.
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	setEncoding(java.lang.String encoding) Set the encoding used by the server we will connect to.
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	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

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

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)

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()

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.

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.

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.

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 -

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.

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.

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.

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.

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:

Object[][] containing the data cache entries, 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.