This article describes the Java Report Engine Configuration file WindwardReports.properties. It also describes the log4j logging facility used by the Java Report Engine, and how to configure it.
The WindwardReports.properties file is where developers set configuration properties for Java Report Engine. This is also where license keys are entered.
Java Report Engine looks for the properties file WindwardReports.properties in the default location. (Note that WindwardReportsServer.jar must use the properties file.)
The properties file can be either a file in a directory or a file in the WindwardReports.jar file. Java Report Engine looks for the file in the following locations in the following order:
- The thread's class loader
- The class loader that loaded Java Report Engine
- The system class loader
- A file on the hard drive
The default location can be overridden with the following two mechanisms:
- Add to the Java command line:
- To set the value programmatically, add the following to your code (before calling Java Report Engine):
Example #1: -DWindwardReports.properties.filename=wr.prop searches in the following order:
- Looks for the file wr.prop in the root of the jar file that Java Report Engine was loaded from (typically WindwardReports.jar).
- Looks in the JVM's default directory for the file wr.prop.
Example #2: -DWindwardReports.properties.filename=net/windward/wr.prop searches in the following order:
- Looks for the file wr.prop in the net/windward directory of the jar file that Java Report Engine was loaded from (typically WindwardReports.jar).
- Looks in the subdirectory (of the JVM's default directory) for the file net/windward/wr.prop.
Depending on where you place the call to Java Reports Engine, your Java Reports Engine programmer may need to implement code indicating where the WindwardReports.propertiesfile is located. For example, if Java Report Engine is called from within an application server such as Tomcat, WebSphere or WebLogic, then you must tell Java Report Engine where the WindwardReports.properties file resides.
Confer with your programmer and decide on the placement that works best for your system, and then implement the necessary code, as described below.
We recommend you place the properties file in one of the application server’s directories and not hard code it as
If you are running Java Report Engine on a single J2EE server, then it’s best practice to place the properties file in the WEB-INF directory, and add this code to your program:
If you are placing Java Report Engine in your J2EE library directory, then it’s best practice to place WindwardReports.properties in the same directory. Add this code (your J2EE server may have a slightly different directory structure):
Note that in the code samples above, the property is set before
ProcessReport.init() is called.
If Java Report Engine can't find the properties file, it throws an exception that lists the full path and filename of the properties file it looked for. The exception is:
In this case it was looking for
A license key is required to run Java Report Engine. This key enforces Java Report Engine licensing restrictions such as:
- How many reports a day your system may generate.
- If your system is a development server (only one report at a time). The license is an uuencoded string and is applied by editing the following line in your WindwardReports.properties file (this is not a valid key):
This can be entered as a single line, or it can be entered as shown here with a "\" (backslash) at the end of each line, except the last line.
If your key is not a legitimate key, Java Report Engine prints the key it loaded. Check the problem license key to ensure it wasn't truncated and there are no spaces in it.
Java Report Engine uses log4j for its logging. Log4j must be configured both for the cases where the embedding application using Java Report Engine also uses log4j, and for the case where Java Engine is the only component using log4j. (Note that WindwardReportsServer.jar must use the log4j configuration file.)
Java Report Engine can't just turn off logging because that would cause problems for embedding application components using log4j. There is no way for Java Report Engine to know if log4j is being used elsewhere.
Your three options are:
- If you use log4j and you initialize it before calling Java Report Engine, then delete the
logging.filename=...entry in WindwardReports.properties. In this case Java Report Engine assumes log4j is already initialized.
- If you use log4j but do not initialize it before first calling Java Report Engine, then set the
logging.filename=...entry in Windward Reports.properties to point to your log4j.properties file. This entry is first tried as a URL and if that fails, then as a filename. (Note that a filename is not a legitimate URL.)
For more information on log4j configuration, please refer to the log4j documentation. The filename you set for log4j is passed to log4j using the call (
logFile is the string from the property
And if that fails, then:
- To turn logging off (this is not recommended), set the entry to:
If you do not use log4j elsewhere, then set
logging.filename=log4j.properties (fully specify the file location) and create a log4j.properties file.
For standard logging, we suggest these properties:
For debug logging (when requested by Support), use these properties:
Java Report Engine makes use of several 3rd-party libraries. To turn on logging for all components you must set log4j to enable logging for all of the following classes:
If logging is slowing you down, please see this article from Apache to remove or disable unneeded loggers, appenders or layouts.
Java Report Engine is now ready to run. You do not need to reboot your system, however, you may need to reopen your console windows to refresh them with any environment changes.
If you have updated Java Report Engine (or any of its the third-party libraries), then you need to restart any JVMs that use them so they see the new libraries. In the case of a J2EE server, this usually means restarting it.