Symantec Visual Cafe for Java 2.5/symantec-visual-cafe-2.5-database-dev-edition.iso/VCafe/prosrc.bin/JDBCBean.java

Java Source | 1998-03-18 | 21.0 KB | 563 lines

/*
 * @(#)JDBCBean.java
 *
 * Copyright (c) 1997 Symantec Corporation. All Rights Reserved.
 *
 */


//package symantec.itools.db.beans;
package symantec.itools.db.beans.jdbc;
import java.io.*;
import java.beans.*;
import java.util.*;
import java.sql.SQLException ;


/**
 * <P>The base class for all Symantec JDBC Beans.
 * This class may be removed as hierarchy matures. Decision to change the hierarchy
 * should be made early into development cycle to avoid deserialization problems.
 *
 * Provides PropertyChange and VetoableChange event registration and processing,
 * validateObject, versioning, serialization, localization
 *
 * A protected handleException  method is provided. All exceptions should be routed
 * through this method. Beans should be real user friendly. Eating exceptions and taking
 * appropriate behavior is ideal for users. Note: Not sure if Exception specifications
 * should be removed from all methods.
 *
 * Since bean will be used in client GUI apps and applets now, and on application server
 * (non-GUI) later, JDBCBean implements the Visibility interface. Descendents can check
 * protected variable guiAvailable to see if a GUI is available to use.
 *
 * A ResourceBundle is loaded and stored for localized strings. Please place all strings
 * in symantec.itools.db.beans.res.StringResources.properties file. This is the default
 * version. Special Localized versions (StringResources_ja_JP.properties) should copy this
 * default and then localized the strings with a UNICODE editor. A method to get a string
 * from the resourcebundle is defined.
 *
 * Note: Description property could be provided by BeanInfo/BeanDescriptor class.
 * Added here for ease of use.
 *
 * Note: Name property provided because this is an invisible bean. This property
 * could be removed if JDBCBean changed to extend Component.
 *
 * Versioning should be check on each level of the hierarchy, allowing for maximum
 * flexibility of modifying objects. Please take care when modifying all serializable
 * objects to conform with java versioning guidelines.
 *
 * @see java.io.Serializable
 * @see java.beans.VetoableChangeListener
 * @see java.beans.PropertychangeListener
 * @see java.io.ObjectInputValidation
 * @see java.beans.Visibility
 * @see java.utils.ResourceBundle
 *
 */

public class JDBCBean implements Serializable,
                                 VetoableChangeListener,
                                 PropertyChangeListener,
                                 ObjectInputValidation,
                                 Visibility {

//PUBLIC SECTION

//Static Declarations

//Constructors
    /**
     * Default constructor. Bean-aware IDE's and serialization require all beans
     * have a default constructor.
     */
    public JDBCBean () {
        name        = "" ;
        description = "" ;
        debug       = false ;
        autoStart   = false ;
    }

    /**
     * Constructor. Beans should provide a constructor with commonly-used properties
     * as parameters.  This allows the beans to be constructed programatically without
     * having to call the properties' setter methods.
     *
     * @param       name.           The user-defined label for the bean.
     * @param       description.    A string that provides a description of the bean
     * @param       debug.          A boolean indicating whether bean is under development
     * @param       autoStart.      A boolean indicating whether the bean should be
     *                                  data-connected after de-serialization.
     */
    public JDBCBean (String name, String description,boolean debug,boolean autoStart) {
        setName(name);
        setDescription(description);
        setDebug(debug);
        setAutoStart(autoStart);
    }


//Methods
//Accessors/Modifiers
    /**
     * Sets the name property. The property is bound, so a PropertyChangeEvent will
     * be sent to registered ProperyChange listeners.
     *
     * @param       name. The user-defined label of the bean.
     *
     */
    public void setName (String name) {
        processPropertyChange(PROP_NAME,this.name,name);
        this.name = name ;
    }

    /**
     * Gets the name property.
     * @return      The user-defined label for the bean.
     */
    public String getName () {
        return name;
    }

    /**
     * Sets the desription property. The property is bound, so a PropertyChangeEvent will
     * be sent to registered ProperyChange listeners.
     *
     * @param       description. The user-defined description of the bean.
     *
     */
    public void setDescription (String description) {
        processPropertyChange(PROP_DESCRIPTION,this.description,description);
        this.description = description ;
    }

    /**
     * Gets the description property.
     *
     * @return      The user-defined description of the bean.
     */
    public String getDescription () {
        return description ;
    }

    /**
     * Sets the debug property. The property is bound, so a PropertyChangeEvent will
     * be sent to registered ProperyChange listeners.
     *
     * @param       debug.  A flag indicating whether the bean is under development.
     *                      If debug is true, special messages will be sent to system.out stream.
     *                      False suppresses these messages.
     *
     */
    public void setDebug (boolean debug) {
        processPropertyChange(PROP_DEBUG,new Boolean(this.debug),new Boolean(debug));
        this.debug = debug ;
    }

    /**
     * Gets the debug property.
     *
     * @return      The value of the debug property.
     */
    public boolean isDebug () {
        return debug ;
    }

    /**
     * Sets the autoStart property. The property is bound, so a PropertyChangeEvent will
     * be sent to registered ProperyChange listeners.
     *
     * @param       autoStart.  Due to the complexity of establishing database connections,
     *              JDBCBeans are not 'live' by default. When the autoStart property is true,
     *              JDBCBean will call doAutoStart() during the de-serialization process.
     *              Descendents of JDBCBean should override the doAutoStart() method if they
     *              want to be notified when to go 'live'.
     *
     */
    public void setAutoStart (boolean autoStart) {
        processPropertyChange(PROP_AUTOSTART,new Boolean(this.autoStart),new Boolean(autoStart));
        this.autoStart = autoStart ;
    }

    /**
     * Gets the autoStart property.
     * @return      The value of the autoStart property.
     */
    public boolean isAutoStart () {
        return autoStart ;
    }


//Visibility interface implementation
    /**
    * Implementation of the Visibility interface. This method should return true if
    * the bean absolutely needs a GUI available in order to get its work done.
    *
    * @return       False. We should not be dependent on a GUI to get our work done.
    *               JDBCBeans on a server may not have a GUI available.
    */
    public boolean needsGui() {
        return false ;
    }

    /**
    * Implementation of the Visibilty interface. This method instructs the bean
    * that it should not use the Gui. This method sets the guiAvailable protected member
    * to false. Descendents of JDBCBean can use the guiAvailable member
    * to determine if a GUI is available.
    */
    public void dontUseGui() {
        guiAvailable = false ;
    }

    /**
    * Implementation of the Visibilty interface. This method instructs the bean
    * that it is OK to use the Gui.  This method sets the guiAvailable protected member
    * to true. Descendents of JDBCBean can use the guiAvailable member
    * to determine if a GUI is available.
    */
    public void okToUseGui() {
        guiAvailable = true ;
    }

    /**
    * Implementation of the Visibilty interface.  This method returns true if the bean
    * is currently avoiding use of the Gui.  e.g. due to a call on dontUseGui().
    * @return       false. We should not be dependent on a GUI to get our work done.
    *               JDBCBeans on a server may not have a GUI available.
    */
    public boolean avoidingGui() {
        return false ;
    }



//Event sources
    /**
     * Adds PropertyChangeListeners to internal list so that they could be sent
     * PropertyChangeEvents when a bound property is changed.
     *
     * @param       l. An object implementing the PropertyChangeListener interface.
     *
     */
    public void addPropertyChangeListener (PropertyChangeListener l) {
        boundChanges.addPropertyChangeListener(l);
    }

    /**
     * Removes PropertChangeListeners from an internal list.  The object will no longer
     * be sent PropertyChangeEvents when a bound property changes.
     *
     * @param       l. The PropertyChangeListener to remove.
     *
     */
    public void removePropertyChangeListener (PropertyChangeListener l) {
        boundChanges.removePropertyChangeListener(l);
    }

    /**
     * Adds a VetoableChangeListener to an internal list so that they could be sent
     * VetoableChangeEvents when a constrained property is changed.
     *
     * @param       l. An object implementing the VetoableChangeListener interface.
     *
     */
    public void addVetoableChangeListener (VetoableChangeListener l) {
        vetoChanges.addVetoableChangeListener(l);
    }

    /**
     * Removes a VetoableChangeListener from an internal list. The object will no longer
     * be sent VetoableChangeEvents when a constrined property is changed.
     *
     * @param       l. The VetoableChangeListener to remove.
     *
     */
    public void removeVetoableChangeListener (VetoableChangeListener l) {
        vetoChanges.removeVetoableChangeListener(l);
    }

//Event listeners
    /**
     * Implementation of the VetoableChangeListener interface.  JDBCBeans can be registered
     * with objects that are a source of VetoableChangeEvents. The default behavior is to
     * allow the VetoableChange by not throwing a PropertyVetoException. Descendents of
     * JDBCBean should override this method to respond to VetoableChangeEvents.
     *
     * @param       evt. The PropertyChangeEvent describing the constrained property.
     *
     * @exception   PropertyVetoException.
     */
    public void vetoableChange (PropertyChangeEvent evt) throws PropertyVetoException {

    }

    /**
     * Implementation of the PropertyChangeListener interface.  JDBCBeans can be registered
     * with objects that are a source of PropertyChangeEvents. The default behavior is to do
     * nothing. Descendents of JDBCBean should override this method to respond to
     * PropertyChangeEvents,
     *
     * @param       evt. The PropertyChangeEvent describing the bound property.Describe params here
     *
     */
    public void propertyChange (PropertyChangeEvent evt) {

    }

//Serialization
    /**
     * Implementation of the ObjectInputValidation interface. During the de-serialization
     * process, registered ObjectInputValidation objects will have the validateObject method
     * called after the object and its graph are completely de-serialized. JDBCBeans
     * and their descendents should verify that the de-serialized object is of a version
     * that is compatible with the current implementation. Each level of the hierarchy should
     * provide their own versioning information. Descendents should check their version first
     * and then call their superclass's validateObject method. JDBCBean will verify its version
     * and then check the state of the property autoStart. If autoStart is true,
     * doAutoStart is called. Descendents can override doAutoStart() if they
     * want to be notified when to go 'live'. Any lengthy processing should be done
     * in a separate thread. Exceptions shouldn't be thrown back to ObjectInputStream.
     * Instead, do appropriate resetting of the object, so that the de-serialization process
     * can continue, allowing the user to change any properties in an IDE that may have
     * caused the Exception.
     *
     *
     * @see JDBCBean#setAutoStart
     * @see JDBCBean#doAutoStart
     *
     *
     * @exception   InvalidObjectException
     */
    public void validateObject () throws InvalidObjectException {
        if (!version.equals(JDBCBean.CURRENTVERSION))
            throw new InvalidObjectException ("Serialized version " +
                            version + "is not compatible with JDBCBean version " +
                            JDBCBean.CURRENTVERSION);

        //Object is completely deserialized. If autoStart, call doAutoStart method
        //Eat all Exceptions so that problem can be resolved in IDE. Remember that
        // validate object is called while deserializing. Don't want to crash now or
        //user won't ever be able to change object.
        try {
            if (isAutoStart())
                doAutoStart();
        }
        catch (Exception e) {
            printMessage ("Exception thrown during de-serialization: " + e.toString());
        }
    }

    /**
     * Convert the bean to a string object
     *
     * @return      A concatenation of the JDBCBean name and description properties.
     */
    public synchronized String toString () {
        return getName() + ":  " + getDescription();
    }

//PROTECTED SECTION
//Static Declarations
    //Programatic names of properties -- Not localizable
    protected static String PROP_NAME           = "name" ;
    protected static String PROP_DESCRIPTION    = "description" ;
    protected static String PROP_DEBUG          = "debug" ;
    protected static String PROP_AUTOSTART      = "autoStart" ;


//Constructors

//Methods
    /**
     * Exception handling method. All SQLExceptions are routed to this method to allow
     * for suppression or logging of Exceptions. The default behavior is to rethrow the
     * Exception. Descendents of JDBCBean can override this method to provide their own
     * exception logging.
     *
     * @param       The SQLException that was thrown
     *
     * @exception   SQLException.
     */
    protected void handleException (SQLException e) throws SQLException {
        if (isDebug()) {
            printMessage("Exception thrown: " + e.toString());
            printMessage("Stack Trace: " );
            e.printStackTrace();
        }
        throw e ;
    }

    /**
     * Message handling method. All printable messages should be routed through
     * this method. The default behavior is to send the string to system.out if
     * the debug property is true.
     *
     * @param       The message to print.
     *
     */
    protected void printMessage (String message ) {
        if (isDebug())
            System.out.println (message);
    }

    /**
     * This method will be called during the de-serialization process if the
     * autoStart property is true. Descendents can override this method if they want
     * to be notified when to go 'live'. Processing should be kept to a minimum or
     * done in a separate thread. Exceptions should be suppressed to allow
     * de-serialization to complete.
     *
     */
    protected void doAutoStart() {
    }


    /**
     * Retrieves a localized string from a ResourceBundle based on a key.
     * There should be no hard-coded strings within JDBCBeans. All strings should
     * be assigned a key and both the key and the string should be placed within
     * the symantec.itools.db.beans.res.StringResources.properties file.
     * This method will eat all exceptions.
     *
     * @param       key. A string key that is associated with desired resource string.
     *
     * @return      The string associated with the key.
     */
    protected String getResString (String key ) {
        //Eat Exceptions and return
        String str = "String Resource Error";
        try {
            str = getResourceBundle().getString(key);
        }
        catch (Exception e) {
            printMessage("Exception caught: " + e.toString());
        }

        return str ;
    }

    /**
     * Returns the ResourceBundle containing the localized set of strings.
     * Normally, calling getResString should be used to access a localized string.
     * This method is provided to get direct access to the ResourceBundle.
     *
     * @return      ResourceBundle
     * @exception   MissingResourceException
     */
    protected ResourceBundle getResourceBundle () throws MissingResourceException {
        //although ResourceBundle caches bundles, keep a reference for this object
        //this method may be called frequently
        if (stringResources == null)
            stringResources = ResourceBundle.getBundle("symantec.itools.db.beans.res.StringResources");

        return stringResources ;
    }

//Accessors/Modifiers
//Event sources
    /**
     * A helper method to fire PropertyChangedEvents for bound properties. JDBCBean class
     * handles the adding and removing of PropertyChangeListeners. This method is provided
     * for descendents to fire PropertyChangedEvents to registered listeners.
     *
     * @param       propertyName.   The name of the property that was changed.
     * @param       oldValue.       Object containing the old value
     * @param       newValue        Object containing the new value.
     *
     */
    protected void processPropertyChange(String propertyName, Object oldValue,Object newValue) {
        printMessage ("BOUND PROPERTY " + propertyName + " CHANGED FROM " + oldValue +
                      " TO " + newValue );
        boundChanges.firePropertyChange(propertyName,oldValue,newValue);
    }

    /**
     * A helper method to fire VetoableChangedEvents for constrained properties. JDBCBean class
     * handles the adding and removing of VetoableChangeListeners. This method is provided
     * for descendents to fire VetoableChangedEvents to registered listeners.
     *
     * @param       propertyName    The name of the property that was changed.
     * @param       oldValue        Object containing the old value.
     * @param       newValue        Object containing the new value
     *
     * @exception   PropertyVetoException
     */
    protected void processVetoableChange(String propertyName, Object oldValue,Object newValue)
                                         throws PropertyVetoException {
        printMessage ("ATTEMPTING TO CHANGE CONSTRAINED PROPERTY " + propertyName + " FROM " + oldValue +
                      " TO " + newValue );
        try {
            vetoChanges.fireVetoableChange(propertyName,oldValue,newValue);
        } catch (PropertyVetoException e) {
            printMessage ("ATTEMPT TO CHANGE CONSTRAINED PROPERTY " + propertyName + " FAILED");
            throw e ;
        }

        printMessage("ATTEMPT TO CHANGE CONSTRAINED PROPERTY " + propertyName + " SUCCEEDED");

    }



//Event listeners
//Serialization


//PRIVATE SECTION
//Static Declarations
    //The current version of JDBCBean
    static private String CURRENTVERSION = "0.01" ;

//Constructors
//Methods
//Accessors/Modifiers
//Event sources
//Event listeners
//Serialization
    /**
     * During the serialization process, ObjectOutputStream will call this method.
     * By default, ObjectOutputStream.defaultWriteObject is called.
     *
     * @param       stream      The ObjectOutputStream controlling the serialization.
     */
    private void writeObject (ObjectOutputStream stream) throws IOException {
        stream.defaultWriteObject();
    }

    /**
     * During the de-serialization process, ObjectInputStream will call this method.
     * JDBCBean will register this object for ObjectInputValidation and then call
     * ObjectInputStream.defaultReadObject.  When the entire object is de-serialized,
     * the validateObject method will be called.
     *
     * @param       stream      The ObjectInputStream controlling the de-serialization.
     *
     * @exception   ClassNotFoundException, IOException
     */
    private void readObject (ObjectInputStream stream) throws ClassNotFoundException,
                                                              IOException {
        stream.registerValidation(this,0);
        stream.defaultReadObject();
    }


//Members
    private String  version     = JDBCBean.CURRENTVERSION ;
    private String  name        = "";
    private String  description = "" ;
    private boolean debug       = false ;
    private boolean autoStart   = false ;

    //Support classes
    private PropertyChangeSupport boundChanges = new PropertyChangeSupport(this);
    private VetoableChangeSupport vetoChanges  = new VetoableChangeSupport(this);

    //Indicates whether a GUI is available.
    protected transient boolean guiAvailable  = false ;

    //Localized strings for Internationalization
    protected transient ResourceBundle stringResources = null ;

}