org.jSyncManager.API.Conduit
Class AbstractConduit

java.lang.Object
  org.jSyncManager.API.Conduit.AbstractConduit

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

AbstractInstaller, Alerter, DefaultConduit, Deleter, Email, FotoReader, NotepadViewer, TestConduit, TextDump

public abstract class AbstractConduit

extends java.lang.Object

implements java.io.Serializable

The abstract class representing a jConduit. All jConduits are derived from this class.

Version:

$Revision: 3.4 $

Author:

Brad BARCLAY <bbarclay@jsyncmanager.org>
Last modified by: $Author: yaztromo $ on $Date: 2004/07/14 04:31:14 $.

See Also:

Serialized Form

Field Summary

static int	CANCEL_BUTTON_PRESSED A useful constant to denote when the parent settings dialogs Cancel or Close buttons have been pressed.
protected javax.swing.JPanel	configurationPanel Used to hold a local handle to a conduit configuration panel.
static int	HELP_BUTTON_PRESSED A useful constant to denote when the parent settings dialogs Cancel or Close buttons have been pressed.
static byte	HIGH_PRIORITY A useful constant denoting high jConduit priority.
static byte	LOW_PRIORITY A useful constant denoting low jConduit priority.
static byte	NORMAL_PRIORITY A useful constant denoting normal jConduit priority.
static int	OK_BUTTON_PRESSED A useful constant to denote when the parent settings dialogs OK button has been pressed.
protected java.util.ResourceBundle	resources A field to hold a resource bundle for this conduit, if available.

Constructor Summary

AbstractConduit()
The constructor used to initialize new jConduits.

Method Summary

protected abstract javax.swing.JPanel	constructConfigPanel() Constructs a configuration panel for this jConduit.
protected void	doInitialization() Perform this jconduit's initialization tasks.
java.lang.String	getConduitDescription() Returns the description of this jConduit for display.
java.lang.String	getConduitName() Returns the name of this jConduit for display.
protected java.util.ResourceBundle	getConduitResourceBundle() Loads the resource bundle named by the getResourceBundleName method.
javax.swing.JPanel	getConfigurationPanel() Retrieves the configuration panel for this jConduit.
byte	getPriority() This method returns the jConduits priority byte.
protected abstract java.lang.String	getResourceBundleName() Retrieves the name of the class to use as the Conduits Resource Bundle.
void	initialize() Cause this conduit to be initialized.
void	jConduitDialogActionPerformed(int action) Informs the jConduit of when the jConduit dialogs action buttons were pressed.
abstract void	startSync(ConduitHandler conduitHandler, DLPUserInfo user) This method is called when this jConduit is given the opportunity to synchronize.
java.lang.String	toString() Returns the name of this jConduit.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

resources

protected transient java.util.ResourceBundle resources

A field to hold a resource bundle for this conduit, if available.

HIGH_PRIORITY

public static final byte HIGH_PRIORITY

A useful constant denoting high jConduit priority.

See Also:

Constant Field Values

NORMAL_PRIORITY

public static final byte NORMAL_PRIORITY

A useful constant denoting normal jConduit priority.

See Also:

Constant Field Values

LOW_PRIORITY

public static final byte LOW_PRIORITY

A useful constant denoting low jConduit priority.

See Also:

Constant Field Values

configurationPanel

protected transient javax.swing.JPanel configurationPanel

Used to hold a local handle to a conduit configuration panel.

CANCEL_BUTTON_PRESSED

public static final int CANCEL_BUTTON_PRESSED

A useful constant to denote when the parent settings dialogs Cancel or Close buttons have been pressed.

See Also:

Constant Field Values

OK_BUTTON_PRESSED

public static final int OK_BUTTON_PRESSED

A useful constant to denote when the parent settings dialogs OK button has been pressed.

See Also:

Constant Field Values

HELP_BUTTON_PRESSED

public static final int HELP_BUTTON_PRESSED

A useful constant to denote when the parent settings dialogs Cancel or Close buttons have been pressed.

See Also:

Constant Field Values

Constructor Detail

AbstractConduit

public AbstractConduit()

The constructor used to initialize new jConduits. The default implementation does nothing. You should ensure that if your jConduit requires initialization when it is first installed, that this constructor is overridden. Note that the default implementation of the jConduit loader will only call the no-parameter constructor. if you provide constructors that take parameters, they will not be called by the jConduit initializer.

Method Detail

getConduitName

public final java.lang.String getConduitName()
                                      throws java.util.MissingResourceException

Returns the name of this jConduit for display. The name should be a single line of text, with no breaks. The text will be used by GUI applications for menus, tab labels, etc. Hence, it should be short but descriptive. For a longer description, use getConduitDescription(). Note that this method will use the provided resource class to retreive the name, using the "conduit.name" key.

Returns:

the name of this jConduit.

Throws:

java.util.MissingResourceException - if the resource bundle can't be loaded.

See Also:

getConduitDescription()

getConduitDescription

public final java.lang.String getConduitDescription()
                                             throws java.util.MissingResourceException

Returns the description of this jConduit for display. The description should be a single line of text, with no breaks. It is up to the displaying application to provide proper word-wrapping.

Returns:

the description of this jConduit. Note that this method will use the jConduit provided resource class to retreive the description, using the "conduit.description" key.

Throws:

java.util.MissingResourceException - if the resource bundle can't be loaded.

getResourceBundleName

protected abstract java.lang.String getResourceBundleName()

Retrieves the name of the class to use as the Conduits Resource Bundle. This method should return a String containing the fully-qualified classname of the class to use for this jConduits textual resources. You may return null from this method, however if you do so you're expected to override the getConduitName and getConduitDescription methods to return suitable data. We suggest using Resource Bundles to ensure that your jConduits can be translated to other languages.

Returns:

the fully-qualified classname of the class to use as this jConduits resource bundle.

getConduitResourceBundle

protected final java.util.ResourceBundle getConduitResourceBundle()
                                                           throws java.util.MissingResourceException

Loads the resource bundle named by the getResourceBundleName method. If the getResourceBundleName method returns null, or if it can't be loaded, this method will throw a MissingResourceException.

Returns:

the ResourceBundle object for this conduits resources.

Throws:

java.util.MissingResourceException - thown if the ResourceBundle can't be loaded.

getPriority

public byte getPriority()

This method returns the jConduits priority byte. The priority byte is used to determine when a jConduit should be run during synchronization. The value is a signed byte, with 127 being highest priority, and -128 the lowest. jConduits with a higher priority will be run first. jConduits with the same priority are run in an undefined order. By default, jConduits will have priority 0. Conduits that are a part of a suite of conduits should implement descending priority values to ensure they are run in a predetermined ordes. Please resist the temptation to use priority 127 and -128. These should be reserved for core jSyncManager conduits which do maintenence tasks (such as Installer and Deleter). Using the maximum and minimum priorities may interfere with correct operation of these tools. For convienence, AbstractConduit defines constants HIGH_PRIORITY, NORMAL_PRIORITY, and LOW_PRIORITY.

Returns:

the jConduits priority ordering byte.

startSync

public abstract void startSync(ConduitHandler conduitHandler,
                               DLPUserInfo user)
                        throws NotConnectedException

This method is called when this jConduit is given the opportunity to synchronize. The contents of this method should use the provided ConduitHandler object to perform any necessary data IO between the host and the handheld. If necessary, you may use the passed DLPUserInfo object to distinguish between users.

Parameters:

conduitHandler - the handle to the active ConduitHandler to use for synchronization.

user - the user information object for the handhelds owner.

Throws:

NotConnectedException - thrown if the connection to the Palm is lost during sync.

toString

public java.lang.String toString()

Returns the name of this jConduit.

Returns:

the name of this jConduit.

See Also:

getConduitName()

getConfigurationPanel

public final javax.swing.JPanel getConfigurationPanel()

Retrieves the configuration panel for this jConduit. This configuration panel should be constructed by the constructConfigPanel method. This method will call constructConfigPanel if the configurationPanel field is null. This is done as configurationPanel is a transient field, so as to prevent it from being serialized. This will cause the constructConfigPanel method to be called every time this method is called if constructConfigPanel returns null, however this behaviour won't impact performance due to the very few instructions added to accomplish this. We'll save instructions in the long run for jConduits that do provide a configuration panel.

Returns:

a JPanel containing whatever configuration widgets your jConduit requires.

constructConfigPanel

protected abstract javax.swing.JPanel constructConfigPanel()

Constructs a configuration panel for this jConduit. If your jConduit requires user supplied configuration information, you may construct a JPanel here to be associated with your jConduit, which GUI applications can use to display to the user prior to synchronization. How this panel is accessed will be application specific. You may return null here to signify that no setting panel is required.

Returns:

a JPanel containing whatever configuration widgets your jConduit requires.

initialize

public final void initialize()

Cause this conduit to be initialized. Initialization is done when a jConduit is loaded after serialization, and gives the jConduit developer the opportunity to open files, prepare data sources, or perform other tasks prior to synchronization. Initialization is done just once per jConduit, either after it's been constructed, or after it's been deserialized.

doInitialization

protected void doInitialization()

Perform this jconduit's initialization tasks. Initialization is done when a jConduit is loaded after serialization, and gives the jConduit developer the opportunity to open files, prepare data sources, or perform other tasks prior to synchronization. Initialization is done just once per jConduit, either after it's been constructed, or after it's been deserialized. jConduit developers should override this method if they wish to perform any initialization tasks, otherwise the default is to do nothing.

jConduitDialogActionPerformed

public void jConduitDialogActionPerformed(int action)

Informs the jConduit of when the jConduit dialogs action buttons were pressed. By default, this method has a null implementation, but jConduit developers can override this in order to be informed of when one of the dialog buttons are pressed.

Parameters:

action - the action that was performed.

See Also:

OK_BUTTON_PRESSED, CANCEL_BUTTON_PRESSED