uk.ac.starlink.table.gui
Class BasicTableLoadDialog

java.lang.Object
  |
  +--java.awt.Component
        |
        +--java.awt.Container
              |
              +--javax.swing.JComponent
                    |
                    +--javax.swing.JPanel
                          |
                          +--uk.ac.starlink.table.gui.BasicTableLoadDialog
All Implemented Interfaces:
Accessible, ImageObserver, MenuContainer, Serializable, TableLoadDialog
Direct Known Subclasses:
FilestoreTableLoadDialog

public abstract class BasicTableLoadDialog
extends JPanel
implements TableLoadDialog

Skeleton implementation of a TableLoadDialog. Concrete subclasses need to populate this panel with components forming the specific part of the query dialogue (presumably text fields, combo boxes and so on) and then implement the getTableSupplier() method which returns an object capable of trying to load a table based on the current state of the component. All the issues about threading are taken care of by the implementation of this class.

Subclasses are encouraged to override the JComponent.setEnabled(boolean) method to en/disable child components which ought not to be active while a load is actually taking place. The overriding implementation ought to call super.setEnabled.

Since:
23 Dec 2004
See Also:
Serialized Form

Nested Class Summary
 class BasicTableLoadDialog.DataSourceTableSupplier
          TableSupplier implementation based on a DataSource.
static interface BasicTableLoadDialog.TableSupplier
          Defines an object which can attempt to load a particular table.
 
Field Summary
 
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
 
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
 
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
 
Constructor Summary
BasicTableLoadDialog(String name, String description)
          Constructor.
 
Method Summary
static IOException asIOException(Throwable th)
          Converts an exception to an IOException, probably by wrapping it in one.
protected  JDialog createDialog(Component parent)
          Constructs a dialogue based on this component; this component forms the main part of the dialogue window, with an OK and Cancel button shown as well.
protected  Action getCancelAction()
          Returns the action associated with hitting the Cancel dialogue button.
 String getDescription()
          Description of this dialogue.
 String getName()
          Name of this dialogue.
protected  Action getOkAction()
          Returns the action associated with hitting the OK dialogue button.
protected abstract  BasicTableLoadDialog.TableSupplier getTableSupplier()
          Concrete subclasses should implement this method to supply a TableSupplier object which can attempt to load a table based on the current state (as filled in by the user) of this component.
protected  void setFormatModel(ComboBoxModel formatModel)
          Installs a table format selector intot this dialogue.
 boolean showLoadDialog(Component parent, StarTableFactory factory, ComboBoxModel formatModel, TableConsumer consumer)
          Presents the user with a dialogue which may be used to specify a table to load.
 
Methods inherited from class javax.swing.JPanel
getAccessibleContext, getUI, getUIClassID, paramString, setUI, updateUI
 
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getGraphics, getHeight, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPreferredSize, getPropertyChangeListeners, getPropertyChangeListeners, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isPreferredSizeSet, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFont, setForeground, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
 
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setFocusCycleRoot, setFocusTraversalKeys, setFocusTraversalPolicy, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
 
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMouseWheelListeners, getParent, getPeer, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface uk.ac.starlink.table.gui.TableLoadDialog
isAvailable
 

Constructor Detail

BasicTableLoadDialog

public BasicTableLoadDialog(String name,
                            String description)
Constructor.

Parameters:
name - dialogue name (typically used as text of a button)
description - dialogue description (typically used as tooltip text)
Method Detail

getName

public String getName()
Description copied from interface: TableLoadDialog
Name of this dialogue. This will typically be used as the text of a button (Action.NAME) which invokes showLoadDialog.

Specified by:
getName in interface TableLoadDialog
Overrides:
getName in class Component
Returns:
name

getDescription

public String getDescription()
Description copied from interface: TableLoadDialog
Description of this dialogue. This will typically be used as the tooltip text of a button (Action.SHORT_DESCRIPTION) which invokes showLoadDialog

Specified by:
getDescription in interface TableLoadDialog
Returns:
short description

showLoadDialog

public boolean showLoadDialog(Component parent,
                              StarTableFactory factory,
                              ComboBoxModel formatModel,
                              TableConsumer consumer)
Description copied from interface: TableLoadDialog
Presents the user with a dialogue which may be used to specify a table to load. This method should return true if an attempt will be made to load a table, and false if it will not (for instance if the user hit a Cancel button).

In the event that true is returned, the implementation of this method should ensure that notification of the table load attempt should be made to the consumer argument using the defined TableConsumer methods. The purpose of doing it like this (rather than just returning a StarTable from this method) is so that the table loading, which may be time-consuming, can be done in a thread other than the event dispatch thread on which this method will have been called. The LoadWorker class is provided to assist with this; the usual idiom for performing the load from the event dispatch thread within the implementation of this method looks like this:

     new LoadWorker( tableConsumer, tableId ) {
         protected StarTable attemptLoad() throws IOException {
             return tableFactory.makeStarTable( ... );
         }
     }.invoke();
 

Error conditions during the course of the user interaction by this method should in general be dealt with by informing the user (e.g. with a popup) and permitting another attempt. Some sort of cancel button should be provided which should trigger return with a false result.

The formatModel argument may be used to determine or set the format to be used for interpreting tables. Its entries are Strings, and in general the selected one should be passed as the handler argument to one of factory's makeStarTable methods. The dialogue may wish to allow the user to modify the selection by presenting a JComboBox based on this model. A suitable model can be obtained using TableLoadChooser.makeFormatBoxModel(uk.ac.starlink.table.StarTableFactory).

Specified by:
showLoadDialog in interface TableLoadDialog
Parameters:
parent - parent window
factory - factory which may be used for table creation
formatModel - comboBoxModel
consumer - object which can do something with the loaded table
Returns:
true if an attempt will be made to load a table

createDialog

protected JDialog createDialog(Component parent)
Constructs a dialogue based on this component; this component forms the main part of the dialogue window, with an OK and Cancel button shown as well. This method may be overridden by subclasses to customise the dialogue's appearance.

Parameters:
parent - component
Returns:
modal dialogue

setFormatModel

protected void setFormatModel(ComboBoxModel formatModel)
Installs a table format selector intot this dialogue. If it makes sense for a concrete dialogue implementation to display format selection, it should override this method in such a way as to present the format model to the user for selection (presumably by setting it as the model of a visible JComboBox).

The default implementation does nothing (suitable for classes which can't make sense of varying table formats).

Parameters:
formatModel - selector model to install

getTableSupplier

protected abstract BasicTableLoadDialog.TableSupplier getTableSupplier()
                                                                throws RuntimeException
Concrete subclasses should implement this method to supply a TableSupplier object which can attempt to load a table based on the current state (as filled in by the user) of this component. If the state is not suitable for an attempt at loading a table (e.g. some components are filled in in an obviously wrong way) then a runtime exception such as IllegalStateException or IllegalArgumentException should be thrown.

Returns:
table supplier corresponding to current state of this component
Throws:
RuntimeException - if validation fails

getOkAction

protected Action getOkAction()
Returns the action associated with hitting the OK dialogue button.

Returns:
OK action

getCancelAction

protected Action getCancelAction()
Returns the action associated with hitting the Cancel dialogue button.

Returns:
Cancel action

asIOException

public static IOException asIOException(Throwable th)
Converts an exception to an IOException, probably by wrapping it in one. This utility method can be used for wrapping up an exception of some other kind if it needs to be thrown in TableSupplier.getTable.

Parameters:
th - base throwable
Returns:
IOException based on th

Copyright © 2004 CLRC: Central Laboratory of the Research Councils. All rights reserved.