JTable : Java Glossary

Debugging

• Failing to fire the appropriate change events, such as fireTableRowsInserted, in your add and similar TableModel methods to let Swing know what needs to be repainted.
• When you modify the TableModel with a Thread other than the Swing Thread, you must do most of your JTable and TableModel calls with SwingUtilities, including firing changes via invokeLater from other Threads. You further need locks in the TableModel to deal with the problem of Swing accessing the model at the same time the app is changing it.

Classes to implement a JTable

• JTable : the visible component.
• TableModel : the part you write to manage the data. When data change, the TableModel fires events to let the GUI (Graphic User Interface) know to refresh portions of the displayed table. You do this with AbstractTableModel. fireTableCellUpdated, fireTableRowsUpdated, fireTableRowsDeleted, fireTableDataChanged or fireTableStructureChanged. Use the most specific method, e.g. fireTableCellUpdated in preference to fireTableRowsUpdated if you just updated a few cells. Don’t worry about what is currently visible. Just fire your events for all changes to the model. The GUI will figure out if any rendering is needed in response. Data are organised in rows and columns. Cells can contain nulls which will paint happily as blank.
• TableColumnModel : What order to display the various TableColumns. It controls how wide each column should be, with

  // get information about all columns.
  final TableColumnModel columnModel = jTable.getColumnModel();
  
  // setting column widths:
  columnModel.getColumn( col ).setPreferredWidth( widthInPixels );
  columnModel.getColumn( col ).setMinWidth( widthInPixels );
  columnModel.getColumn( col ).setMaxWidth( widthInPixels );
  
  // adding a bit of extra space between the columns.
  columnModel.setColumnMargin( 5 );

  Note there is only one TableColumnModel object that serves all the columns.
• TableColumn : the information about one column, e.g. what class of data it contains and what the header is. It also tracks which column in the TableModel where the data come from. TableColumn. setHeaderRenderer lets you configure a TableCellRenderer to produce a column header with special fonts and colours. TableColumn. setCellRenderer lets you configure a TableCellRenderer for the data cells of the column. Here is how to write a simple TableCellRenderer to render
• TableCellRenderer : takes data and converts them to some displayable Component to plug into the grid. Use or extend DefaultTableCellRenderer or implement TableCellRenderer from scratch. If you leave out the setBackground on your Component, DefaultTableCellRenderer. getTableCellRendererComponent will handle it for you, automatically picking the normal or selected background. Rendering is crawling with nasty gotchas.
• JTableHeader : deals mainly with the ability to drag columns around to new positions. Also knows the foreground and background colours for the usual headers.
• JScrollPane: usually encloses a JTable so that you can deal with a table bigger than will fit on screen. You can control what is visible with getVerticalScrollBar(). setValue().
• Watch out! Oracle’s table classes are inconsistently named. Sometimes they begin with a J and sometimes not.

Limitations

JTabless are tricky. It is not that anything is that difficult, it is just that there are so many classes and so many methods to master. JTables are more like the plans for a do-it-yourself table than a table-creating appliance. I strongly suggest buying a textbook that covers them rather than trying to figure it out all on your own from the Javadoc.

How JTables Work

Wide JTables

• Put them in a JScrollPane so that the whole table scrolls.
• Let the user change the width of the columns to squeeze the data into the available space, widening columns as needed.
• Give the users shortcuts to configure various column width constellations.
• It gets awkward if you try to use two or three rows per data item. You still need a perfect grid. You can’t have cells that span more than one column as you can in an HTML table or spreadsheet. Rendering is based on identical data format/type in each cell of a column.
• To delete a row, you can have an icon on each row to click, or you can select a row and right click to select delete off a menu. If the cell contents are immutable, you might allow the delete key on any cell.

Useful Classes and Interfaces

Strategy

1. Define your JTable and a ScrollPane to contain it.
2. Use the JTable constructor that takes only one parameter, the TableModel.
3. Define your custom TableModel class, perhaps making it an inner class. Have it extend AbstractTableModel or DefaultTableModel. Use AbstractTableModel if your rows are represented by a proper class and DefaultTableModel if they are represented by a Vector of fields. Don’t try to compose your model totally from scratch by implementing every method in TableModel.
4. Use your IDE (Integrated Development Environment) to provide skeletons for the methods you absolutely must override.
5. Look over the methods in your base class to see which ones need overriding and write the code.
6. Declare a RowOfCells class whose elements are the data for one row. Pick a more descriptive name than that, please. Write getters and setters for the fields.
7. Declare an ArrayListRowOfCells allRows to hold all the data for the table.
8. Define a set of constants to name each of the columns defining the 0-based column number.
9. Write add, set, remove etc. methods to let you change the rows in the model. Base them on the corresponding ArrayList methods. Make sure you call fireTableRowsInserted, fireTableRowsUpdated or fireTableRowsDeleted to notify Swing of the changes you made to the underlying data.
10. Write your Object getValueAt( int rowIndex, int columnIndex ). Don’t change the Object to something else, or you won’t override the correct method. It will need a switch to use a different getter depending on the column.
11. Write your setValueAt( Object aValue, int rowIndex, int columnIndex ). Don’t change the Object to something else, or you won’t override the correct method. You can leave this out or use a dummy if your table is not editable.
12. Test your data-model modifying methods by using them to put some dummy data into the table, rather than trying to handle keyboard input just yet. It may be easier to add one column at a time to your model and get that column completely working with custom renderers and editors. They you can clone that working, debugged code for the other columns, rather than your first cut buggy code.
13. Hookup buttons or menu items to call the add and remove row methods.
14. Set your column width with  JTable.getColumnModel and setPreferredWidth.
15. Write a TableCellRenderer to chose the fonts and colours of your heading. Install with TableColumn. setHeaderRenderer.
16. Add your persistence mechanism to load up allRows and save on exit. Make sure suitable event changes get fired. You might save to disk, to the registry via the Preferences mechanism or to a server.
17. Compose your custom TableCellRenderers for the data in each column. Hook them up with TableColumn. setCellRenderer.
18. Add sorts to your TableModel, remembering to fireTableDataChanged. You can trigger them with TableHeader. addMouseListener. In Java version 1.6 or later JTables have built-in javax.swing.table. TableRowSorters.
19. Add your editing and custom TableCellEditors. It can be as simple as:

    // attaching a TableCellEditor to a column
    tableColumn.setCellEditor( new DefaultCellEditor( comboBox ) );

    where comboBox is a JComboBox scratch component the user is allowed to edit. DefaultCellEditor will handle popping up the scratch edit component, initialising it and sending the new value to the TableModel. To do more elaborate edits, search for sample code on the web. If you apply colours and fonts to your scratch components, it will make it clearer to the user which cell he is editing. The crucial methods are:
    • getTableCellEditorComponent which converts an Object value taken from from the TableModel via getValueAt to a displayable GUI object, e.g. a JTextField.
    • getCellEditorValue which extracts a String from the GUI component and converts it to an Object suitable for storing in the TableModel via setValueAt. You can just throw an Exception if you don’t like the value, perhaps make a noise too. The value will revert to the previous if the user does not fix the problem.
20. Add calls to stopEdit just prior to any time you sort, insert, delete or replace rows. JTable does not do this by default. Without this code, a field being edited will be improperly left where it was, ending up on the wrong line.
21. Insert code to make sure a given row is visible in your scroll region like this:
22. Add threads so that the computation is on its own thread with the Swing thread free to keep the GUI up to date. Add synchronized to TableModel methods as needed. Make sure the model is not locked when you call the various fire methods because those events will need to get at the model via getValueAt to repaint the GUI. Pepper your code with Thread.yield () after you call methods that could change the GUI. This will give the Swing thread a bash at processing the generated GUI-changing events. Remember that all the JTable methods including fireTableCellUpdated and brethren must be invoked only from the Swing thread. This means the calls must often be wrapped in SwingUtilities. invokeLater. Normally you need to make your TableModel thread-safe because JTable will call its methods on the Swing thread to discover the data values and your app will call its methods on some other thread to set the data values.
23. Hook up Listeners to the ListSelectionModel if there is anything you want to when the selection changes. ListSelectionEvent. getFirstIndex and ListSelectionEvent. getLastIndex do not give you the bounds of selected rows. They give you the range of rows whose selection status may have changed.
24. Review the methods of JTable, ListSelectionModel, DefaultTableModel and DefaultTableCellRenderer reading the documentation and looking for methods to tweak the implementation. When you are looking for a method, scan all those classes. Often the method you are looking for is not where you expect and is not called what you might expect. Using a text search tool on the Javadoc can be a great help to find what you are looking for as can examining the source code.

TableCellRenderer Gotchas

• If you write a TableCellRenderer that extends DefaultTableCellRenderer, the underlying getTableCellRendererComponent method keeps returning the same recycled JLabel object. So if you add an icon to it for example, you will effectively add that icon to all the columns, unless you explicitly remove it for the columns that don’t need it.
• You hook up a TableCellRenderer with either TableColumn setCellRenderer to control rendering a specific column or  jTable.setDefaultRenderer to control rendering of all objects of a given class. You use TableColumn. setHeaderRenderer to control rendering of the header for a specific column. If you hook up two cell renderers to the same column, they cascade (the output of the first becomes the input to the second) and are both applied. The second does not replace the first.
• If you write a TableCellRenderer for headings, make sure you call jTable. setAutoCreateColumnsFromModel( false ); otherwise your renderer will be ignored, even though you called TableColumn. setHeaderRenderer.
• If in your TableCellRenderer you create your own JLabels to return, rather than using the one from DefaultTableCellRenderer, make sure you call JLabel. setOpaque( true ) or else your JLabel. setBackground will be ignored.
• You will probably also want to call JLabel.setBorder( new EmptyBorder(1, 1, 1, 1) ) to keep the division lines between columns and JLabel. setHorizontalAlignment( SwingConstants. CENTER ) to ensure the labels are centred. Make sure you always set the alignment explicitly if you ever set it or otherwise an alignment setting for one rendering will spill over into another.
• If you call JTable.showGrid( false ), you must also call  JTable.setIntercellSpacing ( new Dimension( 0, 0 ) ); to butt the cells right up against each other.
• An alternative approach is to override the prepareRenderer method.

TableRowSorter

• TableRowSorter is only available in  Java version 1.6 or later. Sun provides source for TableSorter you can cannibalise to sort JTables in earlier JDKs (Java Development Kits).
• TableRowSorter does not sort your model. It creates an auxiliary sorted index into it.
• TableRowSorter by default flips the sort from ascending to descending and back when the user clicks a column header. The logic to do this is handled elsewhere, not TableRowSorter. I have not yet found the code. However, it does not display any indicators as to the current column or whether it is sorted ascending or descending. I have not yet figured out a clean way to implement the indicators that can’t possibly get out of sync.

TZ: a Simple Example

VerCheck: a Real World Example

Learning More