Fat-Client-Development - Base-Class for a Business Object

This is document contains the code for Class JSBS_BO.
For easy 'cut and paste' ;-)

For an overview of the idea of Business Objects please refer to Using Business Objects to handle data-storage and -retrieval .
For an explanation how the variables in this object contribute to produce a change-history, please refer to Common Attributes for all database-tables .

package js_base.bo;

import java.sql.*;

import js_base.dba.JSBS_DBA;

/**
 *
 * @author kurt@javascout.biz
 * @date 2006-06-22
 *
 * @description
 *  Base-Class for Business Objects.
 *  This class can be inherited by Business Objects designed for a specific project.
 *
 *  Preface:
 *  Usually a Business Object is associated with a leading database-table.
 *  E.g.: a Business Object with an 'Invoice' is associated with
 *  the database-table 'InvoiceHeader'.
 *  Therefore, the variables ObjectID, DataSetID, CreatedBy, CreatedAt,
 *  ChangedBy, ChangedAt, ValidFrom and ValidTill
 *  contain the values from the associated record of the leading database-table.
 *
 *  The differentiation between ObjectID and DataSetId allows to document the change of
 *  attributes in database-records.
 *  ObjectID contains a 'surrogate' that was the unique key (primary key) of the database-record
 *  at the time when a Business Object with a new 'user-key' was initially inserted.
 *  DataSetID contains the 'surrogate' of the database-record with the actually valid values.
 *
 *  The 'user-key' is a unique identifier which can be seen by a user.
 *  It has to be defined within the Business Objects designed for a specific application
 *  and usually consists of one or more task-specific variables.
 *
 * @change-log
 * when         who               why
 * --------------------------------------------------------
 *
 */
public class JSBS_BO {
/*
 * VARIABLES
 * ------------------- */
/*
 * ObjectID – see description at 'Preface' in the initial comment. */
    public double ObjectID;
/*
 * DataSetID – see description at 'Preface' in the initial comment. */
    public double DataSetID;
/*
 * CreatedBy – User-name (if available within the application) who inserted the
 * first Business Object with this 'user-key'. */
    public String CreatedBy = "";
/*
 * CreatedTS – Date/Time (down to 1/1000 second) when the first Business Object
 * with this 'user-key' was inserted into the database. */
    public Timestamp CreatedAt = new Timestamp(0);
/*
 * ChangedBy – User-name (if available within the application) who made
 * the last change of an attribute. */
    public String ChangedBy = "";
/*
 * ChangedTS – Date/Time (down to 1/1000 second) when the
 * last change of an attribute was written to the database. */
    public Timestamp ChangedAt = new Timestamp(0);
/*
 * ValidFrom – Date, from that on (at 00:00 h / midnight)
 * the data in this Business Object is valid. */
    public Date ValidFrom = new Date(0);
/*
 * ValidTill – Date, from until that (at 24:00 h / midnight)
 * the data in this Business Object is valid. */
    public Date ValidTill = new Date(0);
/*
 * Status code to signal results (see interface JSBS_BO_Constants)
 * of methods to the caller. */
    public int StatusCode = CONST_DB_UNKNOWN_ERROR;
/*
 * Status message; additional information for a returned StatusCode –
 * e.g. the error reported by the database-system together with a database-error. */
    public String StatusMsg = "";
/*
 * --------------------
 * CONSTANTS to signal the completion status to the calling method */
/*
 * OK: Method ended as expected */
    public static int CONST_OK = 0;
/*
 * NOTHING_TO_UPDATE: No attribute changed; updating of database tables skipped */
    public static int CONST_NOTHING_TO_UPDATE = 1;
/*
 * NOT_FOUND: No object with the specified criteria found */
    public static int CONST_NOT_FOUND = 2;
/*
 * DUPLICATE_KEY: When trying to insert an object with the unique object-identifier already exists */
    public static int CONST_DUPLICATE_KEY = 3;
/*
 * CHANGED_INBETWEEN: Another user has changed at least one attribute since the data of
 * the Business Object was fetched from the database. */
    public static int CONST_CHANGED_INBETWEEN = 4;
/*
 * DEADLOCK: A deadlock situation occured in the database system */
    public static int CONST_DEADLOCK = 8;
/*
 * DB_SYSTEM_ERROR: An error occured in the database system: exact reason is unknown.
 * (But there may be more information in the 'StatusText'). */
    public static int CONST_DB_SYSTEM_ERROR = 9;
/*
 * DB_UNKNOWN_ERROR: Something went wrong but exact reason is unknown */
    public static int CONST_DB_UNKNOWN_ERROR = 999;
/*
 * --------------------
 * Method to copy the values from another object into this object. */
    public void getJSBS_BO(JSBS_BO parmJSBS_BO) {
        ObjectID = parmJSBS_BO.ObjectID;
        DataSetID = parmJSBS_BO.DataSetID;
        CreatedBy = parmJSBS_BO.CreatedBy;
        CreatedAt = parmJSBS_BO.CreatedAt;
        ChangedBy = parmJSBS_BO.ChangedBy;
        ChangedAt = parmJSBS_BO.ChangedAt;
        ValidFrom = parmJSBS_BO.ValidFrom;
        ValidTill = parmJSBS_BO.ValidTill;
        StatusCode = parmJSBS_BO.StatusCode ;
        StatusMsg = parmJSBS_BO.StatusMsg ;
    }
/*
 * --------------------
 * Method to check if the attribute ValidTill was changed.
 * This method is used to determine if the record was changed
 * from another task between the SELECT to display it on the GUI
 * and the UPDATE after a change was made. */
    public boolean differentValidTill(Date parmValidTill) {
/*
 * The comparison is made over the String-form of the date.
 * The reason for this detour is, that the database-system might slightly
 * modify the internal representation by a few milliseconds.
 * If the comparison is made over the milliseconds representation
 * (using the .getTime()-method) then at the case, that a new Object is
 * entered and changed immediately, the following error occurs:
 * The reread record shows a slightly differnt representation of ValidTill compared
 * to the one that was generated when the object was entered for the first time.
 * So it would look like the database-record was changed by another task inbetween.
 * The string-representation is the same. */
        int intComparisonIndicator =
          (this.ValidTill.toString()).compareTo(parmValidTill.toString());
/* The comparison delivers 0 if both strings are equal. */
        return (intComparisonIndicator != 0);
    }
/* --------------------
 * The following two methods are used only by Server-Side Business Objects.
 * As Java does not allow Multi-Inheritance and the Server-Side Business Objects
 * inherits from the General Business Object (with the variables and methods for
 * a specific business-entity), the methods to set and get the common values from the
 * DBA (Data-Base-Access)-Objects are implemented in this class. */
/*
 * --------------------
 * Method to get the common attributes from the DBA Object. */
    public void getCommonDBAAttributes(JSBS_DBA parmJSBS_DBA) {
        ObjectID = parmJSBS_DBA.ObjectID;
        DataSetID = parmJSBS_DBA.DataSetID;
        CreatedBy = parmJSBS_DBA.CreatedBy;
        CreatedAt = parmJSBS_DBA.CreatedAt;
        ChangedBy = parmJSBS_DBA.ChangedBy;
        ChangedAt = parmJSBS_DBA.ChangedAt;
        ValidFrom = parmJSBS_DBA.ValidFrom;
        ValidTill = parmJSBS_DBA.ValidTill;
    }
/*
 * --------------------
 * Method to set the common attributes of the DBA Object from the variables of this object. */
    public void setCommonDBAAttributes(JSBS_DBA parmJSBS_DBA) {
        parmJSBS_DBA.ObjectID = ObjectID;
        parmJSBS_DBA.DataSetID = DataSetID;
        parmJSBS_DBA.CreatedBy = CreatedBy;
        parmJSBS_DBA.CreatedAt = CreatedAt;
        parmJSBS_DBA.ChangedBy = ChangedBy;
        parmJSBS_DBA.ChangedAt = ChangedAt;
        parmJSBS_DBA.ValidFrom = ValidFrom;
        parmJSBS_DBA.ValidTill = ValidTill;
    }
}