Troubleshooting

In the event of problems running Expresso or any applications developed with Expresso, there are several courses of action that can help determine the cause of the problem. We suggest that you verify the following items, in the order that they appear:

  1. Servlet/JSP Engine
    1. Verify that your servlet server/servlet engine is running, and on which port. Often servlet engines do not use the default port of 80, but perhaps use port 8080, port 7602, etc. You should also ensure that your servlet engine can serve statis HTML files via this same port. You can check it's ability to serve static files by viewing a file such as http://yourservername:yourportnumber/components/expresso/doc/properties.html, substituting the servername and port number as appropriate.
    2. Servlet engines often come with example servlets and JSP pages - be sure that these examples are running correctly before you proceed with debugging Expresso.
  2. Properties file

    The next thing to check is that the properties file, which gives Expresso initial information and database connection information, is correct and being read correctly.

    1. Verify that you have at least a "default.properties" file in your configuration directory. While other properties files are allowed, this file at least must exist.
    2. There must be no files other than property files in the config directory. Delete any other files or move them elsewhere.
    3. Verify that your properties file is being read when your servlet engine is started. The way to tell the servlet engine to do this varies from one servlet engine to another, but you can check the following things to ensure it's happening correctly:
      1. View the standard output (usually written to a log file) from your servlet engine. You should see lines telling you that the properties file is being read, the database connection pool is being initialized, and so forth. If you don't see these messages, DefaultInit might not be running on startup.
      2. Run the InitServletProps servlet. (use the URL http://yourserver:yourportnumber/servlet/InitServletProps or the variation appropriate on your installation). It will display the properties that were read by the DefaultInit servlet during server startup.
      3. Run the Status servlet. (use the URL http://yourserver:yourportnumber/servlet/Status or the variation appropriate on your installation). It will give you information about the connection pool and the database type mappings being applied for your installation. If Status will not run, it probably indicates that DefaultInit is not starting properly, or that the information in your properties file is incorrect.
  3. Database Connection

    If Expresso is reading it's setup information but is still not operating properly, it could be unable to connect to your database correctly. Here are steps you can take to ensure your database is connecting properly.

    1. Run the Status servlet - you should see information about the current connection pool and database type mappings.
    2. Run JobHandler, redirecting messages into a file. JobHandler takes an argument configDir=xxx, where xxx is the same configuration directory as passed to the DefaultInit servlet. If JobHandler can connect, but your servlets cannot, then the problem is likely with the DefaultInit servlet or the classpath of your servlet engine. Keep in mind that JobHandler can be used to test database connections other than the default by supplying the db=xxx argument, where xxx in this case is the first part of the name of the file in the configDir directory - e.g. to use "oracle.properties", type db=oracle.
    3. Another JDBC-enabled Application: If you have any other application that can access the same database via JDBC, this can be used to isolate the problem further - if neither application can connect, it may be your JDBC driver or the database itself.
    4. SQL Utility - your database probably has an interactive SQL utility that can be used to connect and verify that the database you are trying to access exists and is accessible. For example, MySQL has the "mysql" utility, oracle has SQL Plus, etc. Make sure that the database name referred to in your property file already exists, or create it & try again if it does not.
    5. DBCreate Servlet: If you are not sure if all of the tables for your application exist, it is always safe to run the DBCreate servlet again - it will create any missing tables and will also tell you if your selected database is accessible.
    6. DBTool: The DBTool standalone program can be used (with the "verify") option, to check an existing database. Verify will check for referential integrity (that related records are not changed or deleted), and that all tables that are required do exist with all of the correct fields.
  4. Setup Values

    Errors can also be caused by Setup Values being incorrect. Setup Values are similar to property file values, but are specific to a particular application and database, and are stored in the database itself. The exact meaning of each setup value is dependant upon the application being configured - you should check the documentation for the application and ensure that each setup value is set properly.

  5. HTML/JSP Pages

    It is important to verify that the HTML/JSP pages for Expresso are correctly installed in an appropriate location. By default (e.g. unless you edit them) the pages are intended to be installed in a directory called "/components" within the web root directory of your web server/servlet engine. They should be served by the same engine on the same port: e.g. if you access the status servlet with http://yourserver:8080/servlet/Status, then the web page for Expresso's installation should be accessed by http://yourserver:8080/components/expresso/installation.html.

    Verify that JSP pages are operational on your system via the Login jsp page, accessible at http://yourserver:yourportnumber/expresso/jsp/login.jsp. If this page does not work correctly, make sure that JSP page processing is enabled on your servlet engine, and that JSP 1.0 support or higher is turned on (e.g. not JSP 0.9 spec, which is an option on some servlet servers).

  6. Application Setup

    Once you have verified all of Expresso's functionality, you must verify that any additional steps to get your application operational have been followed. These may include:

    1. Additional servlet registrations
    2. Listing the application in the Schema Listing function (on the Expresso "applications" page at http://yourserver:yourport/components/expresso/applications.jsp)
    3. Running the DBCreate servlet to create the application's tables and other setup values
    4. Setting up security for the applications functions
    5. Any Setup Values requiring configuration for this application

Servlet Errors

In the event of an error message from a servlet, the message is either an Expresso formatted message (a red heading reading "Servlet Error" and a table containing details) or it is from the underlying servlet server. Any other kind of error indicates an application specific problem or a configuration error with the servlet engine itself.

Expresso Servlet Errors

Expresso Servlet errors take a consistent form: The error box always reports three things:

  1. Object Reporting Error:

    Indicates the object name and method name of the object that initiated the error. This helps track down what actually created the error message.

  2. Message Number:

    If the particular error that occurred has a message number associated with it, then detailed information about the error can be referenced by clicking the link on the message number. If there is no message number, this link is not present.

  3. Error Message:

    The actual text of the message generated. This will include the error message generated by the database engine if this is an error relating to a database problem.

There is more information contained on an error page of this sort, for developers and system administrators: View the HTML source of the page with the error - if it is available, a full Java stack trace will appear embedded within a comment near the end of the HTML file. If this trace does not have line numbers, disable (temporarily) any JIT (Just-in-time compiler) that your Java Virtual Machine might be using in order to see line numbers. This information should be able to take you directly to the line of code reporting the error.

Servlet Server Errors

Error message that are not in the above format are likely generated by the servlet engine itself. They might indicate a problem with the configuration of the servlet server, or a problem with the properties files for the Expresso servlets.

A message of the form "Cannot load servlet: xxx" usually indicates that the line referring to this servlet is not present or is not indicating a valid path to the servlet .class file. See the installation instructions for more details.

Logging

When an error occurs, detailed information is also logged to the Expresso Log object. The Log object writes to several sources, depending on what is available to it:

  1. The HTML Log - the filename for this log is indicated in the Setup/Configuration Values as defined during installation. The database must be available for this log to be used.
  2. The servlet log: Most servlet engines provide a logfile where output from servlet "log" calls is written.
  3. Standard output: Most servlet engines also provide a logfile for data written to System.out to be logged. The log will also write to this file if possible.

When looking for log info, check each of these locations & any System.err log provided by the servlet engine.

It is often helpful to increase the detail level of the log temporarily while trying to resolve a problem.

Trace

Try setting a property in the config file called "trace" to "y". This will trace all DBConnectionPool and DBConnection operations to the standard error output at the server - this can be very helpful if you are getting results you don't expect & want to see exactly what SQL is being executed on the database.

If you've tried all of the above & still don't find an answer to a problem, you might check the forums onsite and the archives at opensource@javacorporate.com. I encourage you to post your question on the Expresso users forum, a service provided freely to registered users. To access the discussion forums use the Forums Link on left side of the Expresso project page. By using the community process your question is freely answered and also benefits other community members who may have the same question.


Copyright � 2001 Jcorporate Ltd. All rights reserved. Copyright Privacy

Last Modified: 19-Oct-01 2:09:17 PM