Appendix E. Troubleshooting

This section provides troubleshooting information for common DocumentBurster difficulties.

If you are experiencing problems using DocumentBurster make sure that you have read and properly installed the software prerequisites, as described in DocumentBurster™ in 5 Minutes tutorial guide.

If on the console or log file there is an exception similar with

"java.lang.UnsupportedClassVersionError:test (unsupported major.minor version 49.0)

This is happening when the program runs with an ancient java version (<Java v1.6). Read DocumentBurster™ in 5 Minutes document and double check the version of java which is installed on your computer.

DocumentBurster requires Java v1.6 (or greater) version in order to run.

Sometimes the exception is still coming even after the latest Java is installed. This is happening because the old java is still installed and active on your computer.

The solution is to edit documentburster.bat and do the following change

java -Djava.endorsed.dirs=./lib/endorsed -cp ./lib/burst/ant-launcher.jar org.apache.tools.ant.launch.Launcher -buildfile ./config/burst/documentburster.xml -Darg1=%1 -Darg2=%2 -Darg3=%3 -Darg4=%4 -Darg5=%5 -Darg6=%6

Do the bold change

"C:/Program Files/Java/jre6/bin/java.exe" -Djava.endorsed.dirs=./lib/endorsed -cp ./lib/burst/ant-launcher.jar org.apache.tools.ant.launch.Launcher -buildfile ./config/burst/documentburster.xml -Darg1=%1 -Darg2=%2 -Darg3=%3 -Darg4=%4 -Darg5=%5 -Darg6=%6

The proper path to the location where the latest java is installed should be provided. This change will force DocumentBurster to run with the latest java.

Was GtkSharp prerequisite installed using the default values presented by the wizard, as per DocumentBurster™ in 5 Minutes guidelines?

GTK runtime should be properly exported and visible through the Windows %PATH% environment variable. If required, update %PATH% environment variable and change the position of GTK runtime location to be near the front.

Sometimes variables defined like <0>some value</0> and up to <9>some other value</9> might fail in getting parsed the proper values. Following is an example of the issue coming with Microsoft Access, while similar behavior might be observed with other report writers too.

The Problem - Example of the problem coming with Microsoft Access

I am using various MS Access reports to grab variable data using <0> text </0> . If I use a label for the text and key it into the text box as <0> report id 100 </0> it works fine but if I drop a field onto the report and then put the <0> and </0> in front and back of the field, it does not work.

The Solution - And here is the solution for the previous MS Access behavior

When you drop the fields into an MS Access report you need to define any field you use as a variable as a single field by concatenation. For example, let's say I have a field named "date" and place it on the report with a text box of <0> in front and then place a text box of </0> at the end. This will not work. You need to create one field (object) as follows: =" <0> "text" </0> ". Now it will work.

More Details

If the start and end tags (e.g. <0> and </0> ) are statically defined, while the content inside is a dynamic field /report formula (string value which can grow in length), the dynamic content will grow and will start to overlap with the static tags (e.g. <0> and </0>). This might cause problems when DocumentBurster is parsing the variable values. See the following screenshot in which "Tuesday" hidden text was generated by a date field/formula which expanded its length and started to overlap the start <1> tag. In this case the text which is extracted by DocumentBurster is a messy Tues<da1>y and as a result the variable value is not properly parsed. The solution to this problem was described in the previous paragraph.

When server/startServer.bat script is executed it is flashing up the cmd box and then it disappears.

Solution

  • Are all the prerequisites in place? Read DocumentBurster™ in 5 Minutes tutorial guide and check all the prerequisites required for running DocumentBurster™ .

  • DocumentBurster should run on Java version v1.6 or greater ( java -version MS-DOS command should return v1.6 or greater)
  • If required, start the server again. Did you shut the server properly from previous runs by using server/shutServer.bat script?

Solution

The link http://localhost:8080/burst is not working on the local machine. When web-console/startConsole.bat script is executed it is flashing up the cmd box then it disappears.

Solution

  • Are all the prerequisites in place? Read DocumentBurster™ in 5 Minutes tutorial guide and check all the required prerequisites.

  • DocumentBurster should run on Java version v1.6 or greater ( java -version MS-DOS command should return v1.6 or greater)
  • Was DocumentBurster™ Server console started before, using server/startServer.bat script? DocumentBurster™ Server console should be started before the web console is started.
  • Before starting the web console JRE_HOME environment variable should be properly defined on your system. The echo %JRE_HOME% command executed in the DOS command prompt should return an existing JRE 1.6 (or greater) installation path.

    If required, on Windows, JRE_HOME environment variable can be manually defined in Control PanelSystem Properties (WinKey + Pause) Advanced Environment Variables i.e. C:/Program Files/Java/jre6

The following problem is happening only on Windows Server 2003.

The system was tested and everything works fine on Windows Server 2008 or Windows 7.

The Problem - DocumentBurster™ Server service always stops when the system is logged off.

Solution

This is required only for Windows Server 2003.

Before doing any change make sure that

-Xrs switch should be added in two (2) places

Change 1 server/startServer.bat

java -DDOCUMENTBURSTER_HOME=%CD% -Djava.endorsed.dirs=lib/endorsed -cp lib/batch/ant-launcher.jar org.apache.tools.ant.launch.Launcher -buildfile config/burst/internal/startServer.xml –emacs

Do the bold change

java -Xrs -DDOCUMENTBURSTER_HOME=%CD% -Djava.endorsed.dirs=lib/endorsed -cp lib/batch/ant-launcher.jar org.apache.tools.ant.launch.Launcher -buildfile config/burst/internal/startServer.xml –emacs

Save the file.

Change 2 server/config/burst/internal/documentburster.properties

SERVER_JVM_OPTS=-XX:MaxPermSize=256m -Xms512m -Xmx512m

Do the bold change

SERVER_JVM_OPTS= -Xrs -XX:MaxPermSize=256m -Xms512m -Xmx512m

Save the file.

Restart both DocumentBurster Windows services and check that DocumentBurster works properly when the machine is logged off.

If on the console or log file there is an exception similar with

Caused by: javax.mail.MessagingException: Could not connect to SMTP host: host-here, port: port-here, response: 421

This represents Email SMTP Error 421 (see the SMTP error code 421 in the exception) and you will need to work together with your IT Network or Microsoft Exchange administrator which should further read and interpret the email server log entries (e.g. Microsoft Exchange logs).

Possible ISP limitation

In addition, you might need to let your ISP know that you have a legitimate reason for sending many emails.

More details about Email SMTP Error 421

SMTP Error 421: The Mail transfer service is unavailable because of a transient event. SMTP reply 421 can be caused by many things but generally indicates that the mail server which returns this status code is currently unavailable but may be available later. For example, the server administrator may have stopped the mail service to troubleshoot a problem, or the mail server is right in the middle of rebooting, or the mail server is currently processing too many incoming messages or incoming requests, etc.... Note : Mail Server in this case can be any of the mail servers on the message’s route – the sending server (your server), the ISP SMTP server, or the recipient’s mail server. Clearly, if you repeatedly receive an SMTP status 421 then the problem is no longer of a transient nature and you need to investigate or inform the relevant network administrator, ISP tech support, or the recipient.

SMTP Response 421 can also be received as a result of your message server sending an email where the total number of TO, CC, and BCC users results in a number of simultaneous SMTP connections that is in excess of the number of connections your ISP or SMTP service allows. A typical error message for this situation would be : 421 Too many concurrent SMTP connections from this IP address; please try again later. Typically, when this happens your server will have sent some of the messages (note that for all servers, each email sent by a user always gets broken down into individual separate emails to each of the recipients in the TO, CC, and BCC fields), and will automatically retry a little later to send the remaining messages.