How to deploy the Windward Java Engine.
Installing Windward Java Engine
To install the files:
- On Windows: Run the SetupWindwardReportsSetup.msi install program. This program installs all files, and adds WindwardReports.jar and the third-party libraries to the classpath.
- On other operating systems, unzip the file SetupWindwardReports.zip in your system. Then add WindwardReports.jar and all files in the jars subdirectory (where you installed Windward Reports) to your classpath.
Congratulations— you now have Windward Java Engine installed on your system.
You now need to set your classpath.
Remember that if you ran the Windows Install program, the jar files are already in your classpath. However, if you have the same jar files already in your directory, remove duplicates.
Which third-party library?
You may already have some of these third-party libraries in your classpath (log4j seems to be used by almost everyone). Generally, Windward Java Engine runs with any recent version of these libraries so you can use the version already on your system.
It is important that you do not install two copies of a library in your classpath. Even if they are identical files, Java still views them as different classes with the same name, and it can cause a lot of heartache to find problems caused by this. We suggest that you first add to your environment the following entry.
In Windows, edit the environment by selecting Control Panel, (Performance and Maintenance if in Category View), System, Advanced tab and clicking Environment Variables.
WR_HOME=C:\Program Files (x86)\Windward Studios\Windward Java Engine
This allows you to move the files later and only change one entry. Once this is set, add the following to your classpath (all jar files, including WindwardReports.jar, in the \jars directory):
Windward Reports must be able to find the file WindwardReports.properties in order to run. Windward Reports looks for the properties file WindwardReports.properties in the default location. Note: WindwardReportsServer.jar must use the properties file.
The default location can be overridden with the following two mechanisms:
- Add to the Java command line: -DWindwardReports.properties.filename=MyWindwardReports.properties
- To set the value programmatically, add the following in your code (before calling Windward Reports):
The properties file can be either a file in a directory or a file in the WindwardReports.jar file. Windward Reports looks for the file in the following order:
- In the thread's class loader.
- In the class loader that loaded Windward Reports.
- Using the system class loader.
- As a file on the hard drive.
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 Windward Reports 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 Windward Reports was loaded from (typically WindwardReports.jar).
- Looks in the subdirectory(of the JVM's default directory) for the file ./net/windward/wr.prop.
Missing Properties File Exception
If Windward Reports cannot 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:
Exception in thread "main" net.windward.util.LicenseException: The properties file was not found java.io.FileNotFoundException: WindwardReports.properties(The system cannot find the file specified) C:\test\WindwardReports.properties at net.windward.xmlreport.ProcessReport._init(ProcessReport.java:322)at net.windward.xmlreport.ProcessReport.init(ProcessReport.java:170)at net.windward.xmlreport.RunReport.main(RunReport.java:47)
In the above case it was looking for C:\test\WindwardReports.properties.
Properties File Location
Depending on where you place the call to Windward Reports, your Windward Reports programmer may need to implement some code indicating where you have placed the properties file. For example, if Windward Reports is called from within an application server such as Tomcat, WebSphere or WebLogic, then you must tell Windward Reports 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 C:\\WindwardReports.properties.
If you are running Windward Reports on a single J2EE server, then it’s usually best to place the properties file in the WEB-INF directory. Then add this code to your program:
String propFile = actionServlet.getServletContext().getRealPath("/WEB-INF/WindwardReports.properties");
If you are placing Windward Reports in your J2EE library directory, then it’s usually best to place WindwardReports.properties in the same directory. Add this code (your J2EE server may have a slightly different directory structure):
String propFile = actionServlet.getServletContext().getRealPath../../../../lib/WindwardReports.properties");
Note that in the code samples above, the property is set before the unit is called.
The License Key
A license key is required to run Windward Reports. This key holds the information that allows Windward Reports to run on your computer, including:
- How many reports a day your system may run.
- If it is a development server (only one report at a time).
The license is a uuencoded string and is pointed to by 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 \ at the end of each line to continue it to the next line.
If your key is not a legitimate key, Windward Reports prints the key it loaded. Look to make sure it got all of the key and that there were no spaces in it.
Windward Reports uses log4j for its logging. Log4j must be configured both for the cases where the application using Windward also uses log4j and for the case where Windward is the only part using log4j. Note: WindwardReportsServer.jar must use the log4j configuration file.
Windward Reports cannot blindly turn logging off because that would cause problems for people using log4j. There is no way for Windward Reports to know if log4j is being used elsewhere.
Your three options are:
1. If you use log4j and you initialize it before calling Windward Reports, then delete the logging.filename= entry in WindwardReports.properties. In this case Windward Reports assumes that log4j is already initialized.
2. If you use log4j but do not initialize it before first calling Windward Reports, then set the logging.filename= entry in Windward Reports.properties to point at 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 logging.filename):
PropertyConfigurator.configure( new URL( logFile ));
And if that fails, then:
PropertyConfigurator.configure( logFile );
3. 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. The properties we suggest are:
log4j.appender.stdout.layout.ConversionPattern=%5p (%F:%L) - %m%n
log4j.appender.R.layout.ConversionPattern=%5p (%F:%L) - "%m"%n
log4j Settings to Log All Engine Components
The Windward engine makes use of several 3rd party libraries. To turn-on logging for all components you need to set log4j to log for all of the following classes.
versions 6 – 11 only:
If logging is slowing you down, please see the article from Apache to remove or disable https://logging.apache.org/log4net/r...roduction.html
Ready to Run
Windward Reports is now ready to run. You do not need to reboot your system, however, you may need to reopen your console windows to view the environment changes in a console window.
If you have updated Windward Reports (or any of 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.
Testing the Installation
Follow the instruction on the Java Getting Started page to test your installation.