J2TablePrinter 1.2 Installation, Compatibility, Known Problems

Installation

Download the J2TablePrinter zip file and unzip.  This will create a J2TablePrinter folder containing both code and documentation.

To access the documentation, use your favorite browser to view the file J2TablePrinterREADME.html.  The J2TablePrinter folder also contains the following items:

1. com\wildcrest\j2tableprinter folder containing the J2TablePrinter classes
2. J2TablePrinter.jar, a jar file containing the same J2TablePrinter classes, suitable for installation and use as a JavaBeans component
3. javadoc folder containing the Javadoc documentation for the J2TablePrinter classes
4. J2TablePrinterTestApplication folder containing the J2TablePrinterTestApplication classes and source code files
5. J2TablePrinterSimpleTest folder containing the J2TablePrinterSimpleTest classes and source code files
6. Two runJ2TablePrinter[program].bat files, which are Windows batch files you can double-click to run the sample programs

Installing J2TablePrinter as classes

To use J2TablePrinter as an ordinary class in Java applications, since J2TablePrinter is in package com.wildcrest.j2tableprinter, the folder com\wildcrest\j2tableprinter needs to be accessible from your class path. You need to do one of the following things:

1. Modify your classpath to include the top-level J2TablePrinter folder
2. Modify your classpath to include J2TablePrinter.jar
3. Pick a folder in your current classpath that does not already have a com folder (one possibility for this is the folder that contains your application, which is always in your classpath). Copy the com folder from the J2TablePrinter folder into it.
4. Pick an existing com folder in your current classpath that does not have a wildcrest subfolder.  Copy the J2TablePrinter\com\wildcrest subfolder into your existing com folder
5. If you already have a com\wildcrest folder in your classpath, copy the J2TablePrinter\com\wildcrest\j2tableprinter subfolder into it

1. Create a com\wildcrest\j2tableprinter set of nested folders in the same folder as your applet (whether on your local system or across the network) containing the J2TablePrinter classes in the J2TablePrinter\com\wildcrest\j2tableprinter folder.
2. In the applet tag, set ARCHIVE="J2TablePrinter.jar" (or "C:\directory\J2TablePrinter.jar" if it is somewhere else)
3. In the applet tag, set CODEBASE="directory-containing-com\wildcrest\j2tableprinter\J2TablePrinter.class"

J2TablePrinter uses the Java 2 printing model, so you must both build and deploy your software using J2TablePrinter on JDK versions 1.2 or later.  J2TablePrinter will not work with JDK versions prior to 1.2, not even in combination with any release of Swing.  As JDK 1.2 has numerous performance and functionality problems (see below), it is strongly recommended you use JDK 1.3 to work with J2TablePrinter.
 

Installing J2TablePrinter as a jar

J2TablePrinter.jar is designed to be used as a JavaBeans component in visual builder environments.  Here's how to load J2TablePrinter.jar into various popular  development environments.
    Borland JBuilder 3.0 and 3.5: When in design mode, right click on the component palette, select "Properties", create a new Page if desired, then use "Add Components".  Under "Create Library", give your library a name like "J2TablePrinter" and "Add" to specify the path to your J2TablePrinter.jar or classes.  Then "Install..." this library into the desired palette page.
    IBM VisualAge for Java 3.02:  Use "Import" under the "File" menu to load J2TablePrinter.jar into your project.
    Symantec Visual Cafe 3.0, 4.0, and 4.0a:  As delivered, Visual Cafe cannot install visual components that require Java 2 classes, even though you have set up your development VM as JDK 1.2.2 or 1.3.  You will get the error message "This jar does not contain any valid beans".  To fix this, go to Tools, Environment Options, Internal VM and add your Java VM's rt.jar (e.g., C:\VisualCafe\Java2\lib\rt.jar) to the sc.ini classpath.  Now you will be able to "Add Component to Library" for J2TablePrinter.jar.  Unfortunately, you will get UnsatisfiedLinkErrors and other exceptions in the message window and none of the Property List values will be initialized (we are investigating how to solve this).  Nonetheless, you can wire up your bean visually and set values using the Property List and it will all work OK at run-time.  You do not need to make any of the above changes to work with J2TablePrinter programmatically.  You can simply use J2TablePrinter.jar or the J2TablePrinter classes in your Project: Options: Directory panel and access these from your program.
    Sun's BDK BeanBox 1.1 can load, instantiate, and modify the properties of J2TablePrinter.jar, but it appears to have problems wiring actions such as button press to the J2TablePrinter methods such as print().  We are investigating whether it has a problem similar to Visual Cafe in dealing with Java 2 components.

The J2TablePrinter class files in com\wildcrest\j2tableprinter are identical to the corresponding class files in the J2TablePrinter.jar archive.
 

Compatibility

J2TablePrinter 1.1 was developed on Windows 98 using JDK 1.3 (final).  Compatibility has been tested on different platforms as follows:
 

Windows 95/98/NT: Works successfully on:       JDK 1.3 on Windows 98 with an HP OfficeJet 600 printer and an Apple LaserWriter Select 360       JDK 1.3 on Windows NT with HP LaserJet 8100 & HP Color LaserJet 4500 printers Works but has problems (see below) on:       JDK 1.3 (beta) on Windows 95 with an HP OfficeJet 600 printer       JDK 1.2.2 on Windows 98 with an HP OfficeJet 600 printer  and an Apple LaserWriter Select 360       JDK 1.2.2 on Windows 95 with an HP OfficeJet 600 printer       JDK 1.2.2 on Windows NT with HP LaserJet 8100 & HP Color LaserJet 4500 printers

Macintosh: Testing is underway using the new Java 2-compatible MRJ.

Solaris: Testing underway for JDK 1.2.2 and JDK 1.3

 

Known Problems and Issues
 

Users should be aware of the following known printing problems and issues caused by outstanding bugs in Java. Most of these arise under JDK 1.2.2 and a number still occur under JDK 1.3beta but the great majority are fixed in JDK 1.3final.  For this reasons, the use of JDK 1.3 for J2TablePrinter is strongly recommended.
 

Printing is slow for tables with images (JDK 1.2)
The use of images in cells or custom cell renderers that use the Java drawImage() method will greatly slow things down.  This is due to major performance problems in JDK 1.2.2 (see Bug Parade 4185726) which makes printing of pages containing any images many times slower than normal, even if just one small image is present. Sun has addressed many of these performance problems in JDK 1.3 with plans for additional improvements in the future.  The J2TablePrinter background printing thread feature is a great help in overcoming this problem for interactive (client) applications.
 

JTable with an empty cell won't print (JDK 1.2)
Under JDK 1.2.2, if your JTable has an empty cell (a cell containing the empty string ""), Java will throw an exception at that point in printing your table.   This bug is described in Bug Parade 4138921.  While Sun claims (incredibly) that this is not a bug, this problem is fixed in JDK 1.3beta and 1.3final.  A workaround is to replace the empty strings with a single space.  If a single space has a meaning different than an empty string in your application, you can convert to spaces just prior to printing and convert back (or maintain a second JTable just for printing).
 

Printing of JCheckBox doesn't work (JDK 1.2 and JDK 1.3beta)
Due to a bug in JDK 1.2.2  (see Bug Parade 4202282), any JTable which uses a JCheckBox for rendering a boolean-valued cell will not print (even though it will display correctly in your application and in J2TablePrinter's print preview).  The Bug Parade bug reports contain some workarounds for this problem.  The J2TablePrinterTestApplication source code example includes code for two other workarounds, including 1) the use of images to display the true/false boolean values and 2) simply using text.  The problem is fixed in JDK 1.3.
 

Table row and column sizes different between JDK 1.3 and JDK 1.2
Beginning with JDK 1.3 beta (see Bug Parade 4303458), Sun changed the drawing size of JTable rows and columns.  In JDK 1.2, the width of each cell was drawn with the size getColumn().getWidth() + intercellSpacing().width, whereas in JDK 1.3, the drawing width is getColumn().getWidth() which includes the intercellSpacing().width.  Likewise, in JDK 1.2, the height of each cell was drawn with the size getRowHeight() + intercellSpacing().height, whereas in JDK 1.3, the drawing height is getRowHeight() which includes the intercellSpacing().height.  The result is that rows and columns are slightly smaller under JDK 1.3beta and JDK 1.3 than they were in JDK 1.2 for a given set of specified sizes.  J2TablePrinter 1.1 detects these differences and will print and paginate correctly on JDK 1.2.2, JDK 1.3beta, and JDK 1.3final.
 

Printing slow if JTable.setDoubleBuffering(true) (JDK 1.2)
Under JDK 1.2, setting your JTable double buffering property to true slows down printing by about 6X.  Under JDK 1.3 there is no appreciable effect, not to mention that JDK 1.3 printing is about 2X faster than JDK 1.2 printing even with JTable.setDoubleBuffering(false).
 

Gridlines may be dropped when scaling
The Java2D system fails to display some or all of the hairline gridlines when the scaling factors set to less than 1.0 (minification).  This occurs most often in the print preview dialog where the default printPreviewScaling is 0.5.  It may also happen in the printed output if the print scaling factor is set to less than 1.0, depending on the scaling factor and the resolution of the printer, but this occurs less often since the printer generally has higher resolution than the display.
 

Print Dialog doesn't show default printer (JDK 1.2 and JDK 1.3beta)
Under JDK 1.2, your default printer is not automatically chosen when the Print Dialog comes up, and you will need to select it manually, as Java does not provide an API for selecting the printer or determining the available list of printers (see Bug Parade 4236038 and Bug Parade 4137899).  However, if you print without the Print Dialog, printing will take place on your default printer.  Under JDK 1.3, your default printer is automatically chosen in the Print Dialog.
 

Number of copies is ignored (JDK 1.2 and JDK 1.3beta)
The J2TablePrinter setNumberOfCopies(int) method is ignored under JDK 1.2.2 and 1.3beta releases.  J2TablePrinter is designed to copy your current numberOfCopies setting into the Print Dialog, but the Print Dialog number of copies field always comes up as 1.  The user can change the number of copies in the Print Dialog, which will cause that specified number of copies to print, but this value is not provided back to J2TablePrinter, so your numberOfCopies property will be unchanged.  Your numberOfCopies setting is also ignored if you print without a Print Dialog.  This bug is fixed in JDK 1.3 final (see Bug Parade 4168555).
 

Some Print Dialog options can't be set or read
Various of the options in the Print Dialog work properly using J2TablePrinter including:
    a) Page range: all vs a range of pages
    b) Collate
    c) Print to file
However, none of the above settings are reported back to J2TablePrinter and at present there is no Java API that allows them to be set programmatically (see Bug Parade 4252109).

In addition, hitting "Properties" (along side the printer choice), brings up a printer driver-specific dialog that generally includes these options:
    a) Last page prints first
    b) Portrait vs. landscape
Depending upon the printer driver, many more settings may be made at the driver level, i.e., out from under Java.  The first of these works correctly on the printers we have tested.  The second of these doesn't work well, as it does not allow J2TablePrinter's pagination, page width, margins, and other layout recalculations to be invoked.  Use instead the J2TablePrinter orientation property.  The J2TablePrinter orientation property is displayed and can be changed in the standard Page Setup dialog and is known to Java and therefore J2TablePrinter, allowing it to reformat the orientation precisely.
 

Print job name is ignored (JDK 1.2 and JDK 1.3beta)
The J2TablePrinter setPrintJobName(String) method is ignored under JDK 1.2.2 and 1.3beta releases (see Bug Parade 4205601).  A default print job name is always used.  This bug is fixed in JDK 1.3 final.
 

Page Setup dialog comes up slow (JDK 1.2)
Under JDK 1.2, the Java Page Setup dialog (which brings up a standard OS page setup dialog) takes about 20 seconds to come up on Windows 95 and 98.  A bug report has been filed with Sun about this problem.  J2TablePrinter does display a watch cursor while the Page Setup dialog is coming up.  Under JDK 1.2, you might prefer to implement your own Page Setup dialog, which you will want to do anyway if there are other J2TablePrinter settings you would like your users to be able to specify.  The detailed J2TextPrinterPageSetupDialog provided as part of J2TextPrinterTestApplication comes up fast.
 

Page Setup margins always initialize to 1" (JDK 1.2 and JDK 1.3beta)
J2TablePrinter is designed to copy your current margin settings and portrait/landscape choice into the standard Page Setup dialog.  Unfortunately, a bug in JDK 1.2.2 and JDK 1.3 beta (see Bug Parade 4197377) causes the Page Setup dialog to ignore the margin values provided and to always display instead 1" margins on all four sides.  If you change these and click "OK", these new settings will be successfully copied back into your margin settings and used during printing.  The Page Setup 1" margin problem is fixed in JDK 1.3 final.

The minimum Page Setup margins you can enter are dependent on the current default printer choice.  On Windows, these minimum values give the unprintable margins for the current default printer, so you can try setting them all to 0 to see what the print driver regards as its minimum margins and use these for the "unprintable margin" values (see next).

Unlike the case for margins, the J2TablePrinter portrait/landscape property does display correctly in the JDK 1.2 Page Setup dialog.  Any change the user makes is copied back into the corresponding J2TablePrinter property, and printing does honor this setting.
 

Unprintable margins can't be automatically detected (JDK 1.2 and JDK 1.3beta)
Virtually all printers have some space around the four edges of the page that are unprintable. Some operating systems (e.g. Macintosh) use a printing coordinate system that corresponds to the printable area.  Other operating systems (e.g. Unix) cannot detect the printable area and use instead a printing coordinate system that corresponds to the entire physical page (and therefore will not print at some coordinate positions).  In addition, Sun has changed their Windows implementation from printable area coordinates (Mac-like) under JDK 1.2 to physical page coordinates (Unix-like) under JDK 1.3.  Like most end-user applications, J2TablePrinter defines its left, right, top, and bottom margins relative to the physical page, so that specifying a 1" margin results in a real 1" margin on the physical page.  For this to work, J2TablePrinter needs to know the size of the unprintable left, right, top, and bottom margins for the current printer and whether your OS is one of those that defines its coordinate system as the printable area.

J2TablePrinter provides properties you can use to control these values yourself.  In addition, Java 2 has a method validatePage that allows J2TablePrinter to determine the unprintable margins automatically.  This works correctly under JDK 1.3final, but it is unimplemented in JDK 1.2.2 and JDK 1.3 beta (see Bug Parade 4252108), so on these releases a set of values typical of HP ink jet printers is used.  In addition J2TablePrinter automatically detects your OS and Java release version and sets the value of the J2TablePrinter property printableAreaCoordinates to be true for Macintosh and Windows under JDK 1.2 and false for Unix and Windows under JDK 1.3.  For any other OS, you will need to set this value yourself (the default is false, i.e., Unix-like).

On Windows, you can use the Page Setup dialog to determine the unprintable margins for any given printer.  If you set the margins to 0, the Page Setup dialog will reset them to the actual unprintable margin values you want.  If you want to do this for some printer other than the default printer, first change the printer using the Page Setup "Printer" button (this choice is not remembered or displayed when the regular Print Dialog comes up).

On top of all this, some printers report minimum margins that are too close to the cut-off and not really enough in practice.  Setting your margins to a fraction of an inch more than these "unprintable" margins is often a good idea.
 

Reverse Landscape unimplemented (JDK 1.2 and JDK 1.3beta)
J2TablePrinter supports portrait and landscape printing orientations, but reverse landscape was not implemented in Java (see Bug Parade 4236095) under JDK 1.2 and  JDK 1.3beta.  This feature works correctly under JDK 1.3final.  Note that REVERSE_LANDSCAPE is simply a 180 degree rotation on the page relative to LANDSCAPE.  It is not a left-to-right reversal of the LANDSCAPE image, such as the option provided by some systems (notably Macintosh) to facilitate printing on the back side of transparencies to overcome printer paperpath "curl".
 

Printing transparent GIFs under Windows NT (JDK 1.2 and JDK 1.3beta)
Under Windows NT, GIF images with transparent backgrounds print incorrectly with black instead of transparent backgrounds due to a known Java bug (see Bug Parade 4175560), despite the fact that they display correctly.  Under Windows 95 and Solaris, transparent GIFs display and print correctly.  There are two workarounds for this: 1) make your GIFs with white non-transparent backgrounds or 2) make your GIFs with white backgrounds, specify white as your transparent color, and change non-transparent white pixels in your icon to near-white so they aren't transparent when displayed.  This problem is fixed in JDK 1.3 final.
 

Intermittent JVM.DLL crash under on Windows 98 (JDK 1.2.2 and JDK 1.3beta)
Sun reports in Bug Parade 4293262 that printing under JDK 1.2.2 on Windows 98 can intermittently cause an IOH exception in the Java JVM.DLL.  This problem has not been observed under Windows 95 or NT.  It appears to happen for some printers and not others.  Switching printers, rebooting, printing with other applications, or changing the content being printed often (but not always) clears it up.  This problem is fixed in JDK 1.3final.