2.3. Starting EspressManager

Before ChartDesigner can be started, EspressManager must be running. In most installations, EspressManager should be started on the Web server machine. It is possible to use EspressChart on a stand-alone machine, by running both EspressManager and ChartDesigner locally. In this, the IP number assigned will be 127.0.0.1. This will create a log file, <EspressChartInstallDir>/EspressManager.log which may be useful in monitoring usage as well as in diagnosing problems. It is not necessary to install or start EspressManager on each ChartDesigner user machine.

To start EspressManager, run the EspressManager.bat or EspressManager.sh file in the EspressChart root directory (this file is generated automatically by the installation). For Windows installations you can use of the program shortcuts that were added to the start menu or desktop depending on the options that were specified during installation. EspressManager will then start automatically with default properties.

You can also configure EspressManager with your own settings using several arguments that have been provided. The argument assumes the format of a dash - followed by a command set. No space is needed in each argument, but at least one space is required to separate different arguments.

You can enter these arguments in the command line when starting EspressManager. You can also edit the espressmanager.bat/espressmanager.sh file to add arguments.

-help

When you type -help EspressManager provides information on available arguments and the meaning of each argument. -h or -? can also be used to get the same on-line help information.

-log

When you type the -log argument a log file is created and all the client/server network information is stored. An administrator may open the log file to evaluate the request of each user. The log is saved under the filename EspressManager.log.

-monitor:ON/OFF

When you specify the -monitor argument the EspressManager monitor appears as a graphic user interface that can be used to view the status as well as to modify the EspressManager settings.

EspressManager Monitor

-runInBackground:ON/OFF

This argument allows you to specify whether to run EspressManager as a background process or not. Running as a background process eliminates user input for shut down, and allows EspressManager to be run from a script. To work properly this option should be used in conjunction with the -monitor:OFF argument. When running EspressManager this way, the only way to shut it down is to end the process.

-recordLimit:nn

This argument allows you to set a maximum limit for the number of records EspressManager will retrieve from a database when executing a query. Once the maximum is reached, EspressManager will stop running the query. This feature prevents users from retrieving more records than can be stored in memory, and prevents crashes due to out of memory errors.

-queryTimeout:sss

This argument allows you to specify a timeout interval in seconds for chart queries. Once the query execution time passes the timeout argument EspressChart will abort the query. This feature prevents users from accidentally creating run-away queries.

-DBBuffer:nnn

If a database is being used as the data source for a chart you can choose to buffer both the database connection and the data used for the chart using this argument. The number of connections and queries that will be stored depends on the number specified in the DBBuffer argument from 1 to 999.

-DBCleanAll:ddhhmm

Data in the data source may be updated periodically. Therefore when the data buffer options is used (i.e., DBBuffer has a non-zero value), you may want to refresh the buffer to get the latest data. The -DBCleanAll argument can be used to indicate a time period after which data is cleared from the buffer and fetched from the data source. The value of ddhhmm means dd days, hh hours and mm minutes. EspressManager also supports the omitted format, meaning that is will translate the value with the assumption that the omitted digits are the higher digits. For example:

  • -DBCleanAll:101010 means clean the buffer every 10 days, 10 hours, and 10 minutes.

  • -DBCleanAll:1010 means clean the buffer every 10 hours and 10 minutes.

  • -DBCleanAll:10 means clean the buffer every 10 minutes.

This argument is invalid if the -DBCleanAll argument is set to 0 (i.e., always clean memory).

The refresh interval is printed when EspressManager is started.

-RequireLogin

This argument is used to apply security to ChartDesigner when it is launched via the API. Normally when ChartDesigner is called via the API there is no user authentication. This allows users to apply their own authentication to the programs, but can also allow unauthorized users access to the server. To prevent this users can turn on this argument (values are true/false) to force authentication for ChartDesigner when it is called from the API. With this argument turned on, every time a QbChartDesigner object is displayed a correct username and password (defined in the config.txt file) must also be supplied via API method calls. For more information about calling ChartDesigner from the API, see Section 10.5.6 - Calling Chart Designer from Chart API

-QbDesignerPassword

This argument allows you to set the password to use when the -RequireLogin argument is turned on. Instead of using a login from the config.txt file, you can set a specific password that must be supplied to the server via a method call when displaying a QbChartDesigner object. For more information about calling ChartDesigner from the API, see Section 10.5.6 - Calling Chart Designer from Chart API

-MaxRecordInMemory:nnn

This argument allows you to set the maximum number of records that should be allowed in memory. Unlike the record limit which stops the query, this feature it will begin paging the data to temporary files on the system when the threshold is reached. The viewing/exporting of the chart will continue, but the data will be read from the paging files. This feature prevents the system from running out of memory when running charts.

-MaxCharForRecordFile:nnn

This argument allows you to set the maximum characters allowed per field in the paging file that is generated when record file storage is invoked. Any characters in a record in the data that are longer than this argument will be truncated in the finished chart.

-FileRecordBufferSize:nnn

This argument allows you to set the number of records that should be paged at a time when the record file storage is invoked. The size of the buffer effects performance, the larger the buffer size, the faster the chart is generated.

-singleTableForDistinctParamValue

When you use -singleTableForDistinctParamValue argument, the parameter dialog for parameterized charts will be drawn differently. When you map the parameters to a database column the distinct list will be drawn be running a select distinct on only the mapped field. The default behavior (without this argument) will use the joins and conditions in the original query to constrain the distinct parameter list. For more information about parameterized queries, see Section 4.2.2.2 - Parameterized Queries

If you're running on Mac OS X and you elected to create aliases when installing, you will need to modify the espressmanager.app package to change the EspressManager settings. To do this, right-click (Ctrl+Click) on espressmanager.app and select Show Package Contents from the pop-up menu. Next, navigate to the Contents folder where you will see a file called Info.plist. Opening this file in a text editor adds the arguments to the lax.command.line.args under Java properties.

2.3.1. Starting EspressManager as a Servlet

In addition to running as an application process, EspressManager can be run as a servlet within an application server/servlet runner. In this environment EspressManager uses http to communicate with the client instead of sockets. The advantage to this configuration is that EspressManager can share the same port as the application server which makes it easier to deploy from behind firewalls. In addition, users can perform remote administration when running EspressManager this way.

To deploy EspressManager as a servlet, complete the following steps:

  1. Copy EspressManager.jsp, MenuError.jsp and /WebComponent/ directory under the application server root (or virtual directory) in such way that they are accessible via http.

  2. Copy the EspressChart/classes/ directory and make the classes available via servlet context.

  3. Copy the /html/ and /userdb/ directories from the EspressChart installation directory to the working directory of the application server(if not exist, create new empty folder). To find out the working directory, run whatIsMyWorkingDirectory from the servlet context where you copied the EspressManager servlet classes. The servlet will print the working directory path in your browser when it is called.

  4. Copy EspressManager.jar, qblicense.jar, encoder-1.2.2.jar and esapi-2.2.0.0.jar files(or corresponding versions) from <EspressChart Installation Directory>/lib to the application server's CLASSPATH. You may also want to add axercesImpl.jar and xml-apis.jar from /lib/ directory depending on the application server in use (for example, Tomcat already have XML parsers). In addition, you may also need to add the classes for your JDBC driver in order to make a connection from EspressManager to a database.

  5. Restart the application server.

Once all these steps have been completed you should be able to load the EspressManager page by pointing your Web browser to the EspressManager.jsp page that should be available in your application server as explained in step 1.

EspressManager JSP Monitor

With this page loaded, click the Start button to start EspressManager. Once it has started you can set/modify the buffer settings and shut it down again from this window. With EspressManager running, you can close this window. It will continue to run until you call the JSP again and shut it down.

When running EspressManager as a servlet all of the components that connect to EspressManager need to be modified to take this into account. This includes chart Designer, Scheduler, chart Viewer, Page Viewer, and any application/servlet/JSP using the chart API. For more information about EspressChart deployment, please see Chapter 12 - Deployment

2.3.1.1. Deploying EspressManager as a Servlet in Tomcat

The following section explains how to setup and run EspressManager as a servlet in Tomcat. The steps are same as in the previous section. This example assumes you are running Tomcat locally (IP 127.0.0.1) on port 8080. If your configuration is different, simply replace the IP and port in these instructions with the ones you use.

  1. Create a directory named EspressChart under your Tomcat root folder (<Tomcat installation directory>/webapps/ROOT) and copy there EspressManager.jsp, MenuError.jsp files, and /Web_Component/ directory from your EspressChart installation (<EspressChart Installation Directory>).

  2. Copy the <EspressChart Installation Directory>/classes directory to <Tomcat Installation Directory>/webapps/ROOT/WEB-INF/ directory.

  3. Copy EspressManager.jar, qblicense.jar, encoder-1.2.2.jar and esapi-2.2.0.0.jar files(or corresponding versions) from <EspressChart Installation Directory>/lib to <Tomcat Installation Directory>/lib . Alternatively, you can link this files with Tomcat by creating setenv.bat under <Tomcat Installation Directory>/bin directory and write in Tomcat's CLASSPATH with the value of EspressManager.jar, qblicense.jar and servlet-api.jar.

    Sample of setenv.bat:

    set CLASSPATH=C:\EspressChart66\lib\EspressManager.jar;C:\EspressChart66\lib\qblicense.jar;C:\tomcat\lib\servlet-api.jar

  4. Copy the /html/ and /userdb/ directories from the EspressChart installation directory to <Tomcat Installation Directory>/bin directory(if not exist, create new empty folder).

  5. Restart your Tomcat server.

Now EspressManager should be deployed correctly. To start the EspressManager, open your web browser and go to the following address: http://127.0.0.1:8080/EspressChart/EspressManager.jsp. The Monitor will load and you can start the EspressManager by clicking the Start button.