Code for Server-Side Business Object for a 'Project' - Fat-Client-Development

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

package js_errdb.bos;

import java.sql.*;
import java.util.Date;

import js_base.bo.JSBS_BO_Services;
import js_base.connections.JSBS_DB_ConnectionManager;
import js_base.structures.JSBS_MinimalParameters;

import js_errdb.bo.JS_ErrDB_Project_BO;
import js_errdb.dba.JS_ErrDB_Project_DBA;

/**
 *
 * @author kurt@javascout.biz
 * @date 2006-06-22
 *
 * @description
 *  Server-Side Derivation of the Business Object for the 'Project'.
 *
 *  This class has the following function:
 *  * Establish the connection to the database-system
 *    if a DB-Connection was not already passed by parameter at the construction of the object.
 *  * Implements the logic to break down the methods to handle persistant data of the
 *  * Business Object to the more simple methods (close to the SQL-statements of the DB-system)
 *    of the Data-Base-Access objects.
 *  * Logic to decide if a transaction was fulfilled completely and can be committed
      or failed at one step and has to be 'rolled back' to assure the data-integrity.
 *
 *  User-Key: ProjectCode & LanguageCode.
 *
 * @change-log
 * when         who               why
 * --------------------------------------------------------
 *
 */
public class JS_ErrDB_Project_BOS extends JS_ErrDB_Project_BO {
/*
 * Minimal Parameters containing user-, workstation- and date-information from
 * where the request for the database-operation originated.
 * Used is the user-name and the date the workstation is set to.
 * The date of the workstation might be different of the system-date. */
    private JSBS_MinimalParameters structJSBS_MinimalParameters = null;
/*
 * Flag if the DB-Connection is already established (either by a Constructor or by
 * another method of this class). */
    private boolean bol_structDBConEstablished = false;
/*
 * References to the ConnectionManager to establish connections to the database-system
 * and the Connection to the database.
 * One of them has to be passed by the calling method when this class was constructed. */
    private JSBS_DB_ConnectionManager structJSBS_DB_ConnectionManager = null;
    private Connection structDBCon = null;
/*
 * Reference to the DB-Connection administered by the ConnectionManager.
 * Provided from the ConnectionManager at the establishing of a DB-Connection and
 * needed to return the DB-Connection to the ConnectionManager when it is no longer needed. */
    private int intDBConReference = 0;
/*
 * Structure of the DBA object used to perform SQL-commands against the database-system. */
    private JS_ErrDB_Project_DBA structJS_ErrDB_Project_DBA = new JS_ErrDB_Project_DBA();
/*
 * --------------------
 * CONSTRUCTOR
 * when the Connection-Manager is passed and the database-connection has
 * to be establishe and closed within the individual method. */
    public JS_ErrDB_Project_BOS(JSBS_MinimalParameters parmMinParm,
                                JSBS_DB_ConnectionManager parmJSBS_DB_ConnectionManager) {
/* Call the method written to do the copying of the parameters and setting the flag. */
      constructionWithConnectionManager(parmMinParm, parmJSBS_DB_ConnectionManager);
    }
/*
 * --------------------
 * CONSTRUCTOR
 * when an existing (and open!) Connection to the database-system is passed. */
    public JS_ErrDB_Project_BOS(JSBS_MinimalParameters parmMinParm,
                                Connection parmDBCon) {
/* Call the method written to do the copying of the parameters and setting the flag. */
      constructionWithDBConnection(parmMinParm, parmDBCon);
    }
/*
 * --------------------
 * CONSTRUCTOR
 * when the Connection-Manager is passed and the database-connection has
 * to be establishe and closed within the individual method and
 * the values of the attributes have to taken from a Business Object passed as parameter. */
    public JS_ErrDB_Project_BOS(JSBS_MinimalParameters parmMinParm,
                                JSBS_DB_ConnectionManager parmJSBS_DB_ConnectionManager,
                                JS_ErrDB_Project_BO parmJS_ErrDB_Project_BO) {
/* Call the method written to do the copying of the parameters and setting the flag. */
      constructionWithConnectionManager(parmMinParm, parmJSBS_DB_ConnectionManager);
/* Call the method (in the General Class [superclass] for this Business Objject to
 * copy the values from the BO passed as parameter to the variables of this Business Objject. */
      getJS_ErrDB_Project_BO(parmJS_ErrDB_Project_BO);
    }
/*
 * --------------------
 * CONSTRUCTOR
 * when an existing (and open!) Connection to the database-system is passed and
 * the values of the attributes have to taken from a Business Object passed as parameter. */
    public JS_ErrDB_Project_BOS(JSBS_MinimalParameters parmMinParm,
                                Connection parmDBCon,
                                JS_ErrDB_Project_BO parmJS_ErrDB_Project_BO) {
/* Call the method written to do the copying of the parameters and setting the flag. */
      constructionWithDBConnection(parmMinParm, parmDBCon);
/* Call the method (in the General Class [superclass] for this Business Objject to
 * copy the values from the BO passed as parameter to the variables of this Business Objject. */
      getJS_ErrDB_Project_BO(parmJS_ErrDB_Project_BO);
    }
/*
 * --------------------
 * Method to copy the values of the passed parameters to the variables of this Object and
 * reflect in the appropriate flag that the ConnectionManager was passed -
 * and NOT an open connection to the database-system. */
    private void constructionWithConnectionManager(
                                JSBS_MinimalParameters parmMinParm,
                                JSBS_DB_ConnectionManager parmJSBS_DB_ConnectionManager) {
/* Copy the values of the parameters (passed during Construction of the object)
 * to the local variables. */
      structJSBS_MinimalParameters = new JSBS_MinimalParameters(parmMinParm);
      structJSBS_DB_ConnectionManager = parmJSBS_DB_ConnectionManager;
/* Set the flag to reflect that an established connection to the database-system
 * does not already exist.
 * This signals to the methods that a Connection has to be established within the method. */
      bol_structDBConEstablished = false;
    }
/*
 * --------------------
 * Method to copy the values of the passed parameters to the variables of this Object and
 * reflect in the appropriate flag that a connection to the database-system was passed. */
    private void constructionWithDBConnection(
                                JSBS_MinimalParameters parmMinParm,
                                Connection parmDBConnection) {
/* Copy the values of the parameters (passed during Construction of the object)
 * to the local variables. */
      structJSBS_MinimalParameters = new JSBS_MinimalParameters(parmMinParm);
      structDBCon = parmDBConnection;
/* Set the flag to reflect that a connection to the database-system exists.
 * This signals to the methods that a they do not habe to establish
 * a connection within the method. */
      bol_structDBConEstablished = true;
    }
/*
 * --------------------
 * Method to establish a connection to the database-system.
 * The parameter controls if the connection is set to 'autocommit'
 * (when the parameter is true [= ReadOnly]=).
 * Setting 'autocommit' increases the performance of the database-system
 * but prevents a user-controlled transaction-sequence to keep the integrity of
 * data-relations. */
    private boolean getDatabaseConnection(boolean parmReadOnly) {
/* Get a reference to the database-connection provided by the ConnectionManager. */
      intDBConReference =
        structJSBS_DB_ConnectionManager.reserveConnection(this, parmReadOnly);
/* Check if the database-connection is available (ConnectionReference >= 0);
 * otherwise return error. */
      if (intDBConReference < 0) {
        StatusCode = CONST_DB_SYSTEM_ERROR;
        StatusMsg = structJSBS_DB_ConnectionManager.StatusMsg;
        return false;
      }
/* Get the database-connection and store it in the variable within this class.
 * Set the flag to show, that the DB-Connection is now established. */
      structDBCon =
        structJSBS_DB_ConnectionManager.getReservedConnection(this, intDBConReference);
      bol_structDBConEstablished = true;
      return true;
    }
/*
 * --------------------
 * Method to commit the changes made with this database-connection and
 * return the established connection to the Connection-Manager.
 * This is only done if the connection was opened by the method (the flag is passed
 * as a parameter) to avoid closing the connection if it was passed as
 * a parameter when the class was constructed. */
    private void commitAndCloseDBConnection(boolean parmDBConOpenedInThisMethod) {
/* If the connection was not opened in the calling method: do nothing. */
      if (! parmDBConOpenedInThisMethod) return;
/* Run the 'commit' to have a integral state of all changes made with this db-connection. */
      try {structDBCon.commit();}
      catch (SQLException SQLExc) {
/* Error of the database-system during commit; report the error to the calling method. */
        StatusCode = CONST_DB_SYSTEM_ERROR;
        StatusMsg = SQLExc.getMessage();
/* To be on the sure side: perform a rollback. */
        rollbackAndCloseDBConnection(parmDBConOpenedInThisMethod);
      }
/* Return the connection to the ConnectionManager for re-use
 * and set the flag to show that a connection to the database-system is not established. */
      structJSBS_DB_ConnectionManager.returnReservedConnection(this, intDBConReference);
      bol_structDBConEstablished = false;
    }
/*
 * --------------------
 * Method to roll-back the changes made with this database-connection and
 * return the established connection to the Connection-Manager.
 * This is only done if the connection was opened by the method (the flag is passed
 * as a parameter) to avoid closing the connection if it was passed as
 * a parameter when the class was constructed. */
    private void rollbackAndCloseDBConnection(boolean parmDBConOpenedInThisMethod) {
/* If the connection was not opened in the calling method: do nothing. */
      if (! parmDBConOpenedInThisMethod) return;
/* Run the 'rollback' to cancel a all changes since opening the connection to avoid
 * a none integral state of relations of business-data. */
      try {structDBCon.rollback();}
      catch (SQLException SQLExc) {
/* Error of the database-system during rollback (shit – this might end up in disintegral data);
 * report the error to the calling method. */
        StatusCode = CONST_DB_SYSTEM_ERROR;
        StatusMsg = SQLExc.getMessage();
      }
/* Return the connection to the ConnectionManager for re-use
 * and set the flag to show that a connection to the database-system is not established. */
      structJSBS_DB_ConnectionManager.returnReservedConnection(this, intDBConReference);
      bol_structDBConEstablished = false;
    }
/*
 * --------------------
 * Method to transfer the values of the variables from this Business Object
 * to the attributes of the Data-Base-Access (DBA) Object that is closest
 * to this Business Object. */
    private void setDBAAttributes(JS_ErrDB_Project_DBA parmJS_ErrDB_Project_DBA) {
/* Call the method of the superclass (JSBS_BO) to transfer the values of the
 * Common Attributes. */
      setCommonDBAAttributes(parmJS_ErrDB_Project_DBA);
/* Transfer the business specific attributes of this Business Object. */
      parmJS_ErrDB_Project_DBA.ProjectCode = this.ProjectCode;
      parmJS_ErrDB_Project_DBA.LanguageCode = this.LanguageCode;
      parmJS_ErrDB_Project_DBA.TargetDirectory = this.TargetDirectory;
    }
/*
 * --------------------
 * Method to store the values of the variables from this Business Object
 * into the database-table(s); or in a technical term: make the data persistent.
 * Within the method is decided if this object is new and an INSERT into
 * the db-table is requiered or the business-values object were changed
 * and an UPDATE has to be done. */
    public void store() {
/* Reset the Status-variables to a state of OK. */
      this.StatusCode = CONST_OK;
      this.StatusMsg = "";
/* Flag, if the Connection to the database was opened in this method;
 * needed to know if the Connection has to be closed when this method is left. */
      boolean bol_structDBConOpenedInThisMethod = false;
/* Check if the database-connection is already established.
 * (Could have been passed as parameter when this class was constructed). */
      if (! bol_structDBConEstablished) {
/* Call the method that handles the establishing of a database-connection.
 * The parameter is for 'ReadOnly'; in this case the Connection is opened for
 * INSERT/UPDATE/DELETE. */
        bol_structDBConOpenedInThisMethod = getDatabaseConnection(false);
      }
/* Verify that a database-connection was opened;
 * otherwise return an error with the Error-Message from the Connection-Manager. */
      if (intDBConReference < 0) {
        StatusCode = CONST_DB_SYSTEM_ERROR;
        StatusMsg = structJSBS_DB_ConnectionManager.StatusMsg;
        return;
      }
/* Decide if the Business Object is newly created (ObjectID is 0) or updated. */
      if (ObjectID == 0) {
/* Storing of a new object requested; check that a dataset with the same User-Known-Key
 * does not already exist for the actual date. */
        boolean locboolDataSetExists =
          structJS_ErrDB_Project_DBA.selectByUserKnownKey(structDBCon, structJSBS_MinimalParameters,
                                                          this.ProjectCode, this.LanguageCode );
        if (locboolDataSetExists) {
/* Data-Set with the known key already exists; report 'error'. */
          StatusCode = CONST_DUPLICATE_KEY;
          StatusMsg = "";
          rollbackAndCloseDBConnection(bol_structDBConOpenedInThisMethod);
          return;
        }
        else {
/* Check if a database-error occured. */
          if (structJS_ErrDB_Project_DBA.ErrorMsg.length() > 0) {
/* Database-Error happened; do not go on with this method. */
            StatusCode = CONST_DB_SYSTEM_ERROR;
            StatusMsg = structJS_ErrDB_Project_DBA.ErrorMsg;
            rollbackAndCloseDBConnection(bol_structDBConOpenedInThisMethod);
            return;
          }
        }
/* Data-Set with the User-Known-Key does not already exist; go ahead with INSERT.
 * The passed parameter signals that this is the first Data-Set with the User-Known-Key. */
        internalInsert(true);
/* Verify if the INSERT was ok; otherwise start error-handling. */
        if (StatusCode != CONST_OK) {
          rollbackAndCloseDBConnection(bol_structDBConOpenedInThisMethod);
          return;
        }
      }
      else {
/* Update of an existing dataset.
 * The ValidTill of the existing dataset will be set to the day before the actual date.
 * This is the 'marking' that the validity of the dataset has ended.
 * A new dataset with the same ObjectID and the changed values is inserted. */
/*
 * First the existing dataset is read again to check if another user has made a change
 * between the last read (to bring the information onto the screen) and now.
 * To do this, a new Server-Side Business Object is constructed and the already
 * established connection to the database-system is passed. */
        JS_ErrDB_Project_BOS existingJS_ErrDB_Project_BOS =
          new JS_ErrDB_Project_BOS(structJSBS_MinimalParameters, structDBCon);
/* Read the Business Object by the DataSetID of the BO that should be updated.
 * That brings the Object that was read some time before. */
         existingJS_ErrDB_Project_BOS.readByDataSetID(this.DataSetID);
/* Verify if the database-access was as expected. */
        if (existingJS_ErrDB_Project_BOS.StatusCode != CONST_OK) {
/* Dataset not found or an error occured while reading from database;
 * return the status to the calling method. */
          StatusCode = existingJS_ErrDB_Project_BOS.StatusCode;
          StatusMsg = "Unexpected Error during re-read: " + existingJS_ErrDB_Project_BOS.StatusMsg;
/* Do a rollback and then end the method. */
          rollbackAndCloseDBConnection(bol_structDBConOpenedInThisMethod);
          return;
        }
/* Dataset found – should be like this. Continue with the inspection if there was a change. */
        if (! isDifferent(existingJS_ErrDB_Project_BOS)) {
/* No change of attributes; no need to store an update. */
          StatusCode = CONST_NOTHING_TO_UPDATE;
          StatusMsg = "";
/* Do a rollback and then end the method. */
          rollbackAndCloseDBConnection(bol_structDBConOpenedInThisMethod);
          return;
        }
/* Inspect if the Business Object was changed since it was read.
 * If it was changed; then the ValidTill was changed too. */
        if (this.differentValidTill(existingJS_ErrDB_Project_BOS.ValidTill)) {
/* Other user made a change; report this to the calling method. */
          StatusCode = CONST_CHANGED_INBETWEEN;
          StatusMsg = "";
/* Do a rollback and then end the method. */
          rollbackAndCloseDBConnection(bol_structDBConOpenedInThisMethod);
          return;
        }
/* Set the new 'ValidTill' to the existing database-record and the do an UPDATE. */
        existingJS_ErrDB_Project_BOS.ValidTill =
          JSBS_BO_Services.getNewValidTill(structJSBS_MinimalParameters);
        existingJS_ErrDB_Project_BOS.internalUpdate();
        if (existingJS_ErrDB_Project_BOS.StatusCode != CONST_OK) {
/* Updating existing record failed; report it to the calling method. */
          StatusCode = existingJS_ErrDB_Project_BOS.StatusCode;
          StatusMsg = "Unexpected Error during update of existing record: " +
                      existingJS_ErrDB_Project_BOS.StatusMsg;
/* Do a rollback and then end the method. */
          rollbackAndCloseDBConnection(bol_structDBConOpenedInThisMethod);
          return;
        }
/* All database operations error-free till now;
 * insert the new dataset with the changed values.
 * The parameter (false) signals that it is the insert of a new dataset of an existing BO. */
        internalInsert(false);
/* Verify if the database-operation was error-free; if not do a rollback. */
        if (StatusCode != CONST_OK) {
/* Updating existing record failed; report it to the calling method. */
          rollbackAndCloseDBConnection(bol_structDBConOpenedInThisMethod);
          return;
        }
/* All database-operations were error-free till now; commit the changes. */
        commitAndCloseDBConnection(bol_structDBConOpenedInThisMethod);
      }
    }
/*
 * --------------------
 * Method (just for usage within this class) to prepare the CommonAttributes and
 * then call the DBA object to insert the data into the database.
 * The passed parameter signals, if this is the first dataset of a Business Object.
 * In that case, the ObjectID, CreatedAt and CreatedBy attributes are filled. */
    private void internalInsert(boolean parmFirstInsert) {
/* Set the attributes defining the time-validity of the BO. */
      ValidFrom = JSBS_BO_Services.getNewValidFrom(structJSBS_MinimalParameters);
      ValidTill = JSBS_BO_Services.getGoodTillCancelled_SQLDate();
/* Set the user who made the change and the system-time when the change was made. */
      ChangedBy = structJSBS_MinimalParameters.strUserName;
      ChangedAt = new Timestamp(new Date().getTime());
/* Get the surrogate for the DataSetID (and the ObjectID if it is the first dataset for a BO)
 * and check if the generated surrogate is already a primary key in the database-table. */
      int intTrialCounter = 9;
      do {
/* Call the method that generates a surrogate with a widespread range. */
        DataSetID = JSBS_BO_Services.generateSurrogate();
/* Make a database-access to check if the just generated surrogate already exists. */
        boolean locbolDataSetExists =
          structJS_ErrDB_Project_DBA.selectByDataSetID(structDBCon, this.DataSetID);
        if (locbolDataSetExists) {
/* Rare case that the generated surrogate is already a key; try again. */
          intTrialCounter--;
          continue;
        }
        else {
/* Check if there was an error at the database operation. */
          if (structJS_ErrDB_Project_DBA.ErrorMsg.length() > 0) {
/* DBA object reports an error; transfer the Error-Message to this object. */
            StatusCode = CONST_DB_SYSTEM_ERROR;
            StatusMsg = structJS_ErrDB_Project_DBA.ErrorMsg;
            return;
          }
/* When the Business Object is inserted for the first time:
 * set the variables for ObjectID, CreatedAt and CreatedBy. */
          if (parmFirstInsert) {
            ObjectID = DataSetID;
            CreatedAt = ChangedAt;
            CreatedBy = ChangedBy;
          }
/* Transfer the values of this Business Object to the DBA object. */
          setDBAAttributes(structJS_ErrDB_Project_DBA);
/* Call the method of the DBA object to do the database INSERT on the low level. */
          structJS_ErrDB_Project_DBA.insert(structDBCon);
/* Check if the database INSERT was error-free. */
          if (structJS_ErrDB_Project_DBA.ErrorMsg.length() > 0) {
/* Error-Message is not empty; transfer the error to this object. */
            StatusCode = CONST_DB_SYSTEM_ERROR;
            StatusMsg = structJS_ErrDB_Project_DBA.ErrorMsg;
            return;
          }
          else {
/* Error-Message is empty; i.e. no error is reported. */
            return;
          }
        }
      } while (intTrialCounter > 0);
/* All of the 9 generated surrogates were already primary key in the table;
 * database obviously full; report error. */
      StatusCode = CONST_DB_UNKNOWN_ERROR;
      StatusMsg = "No surrogate found after 9 trials; database-table obviously full.";
    }
/*
 * --------------------
 * Method (just for usage within this class) to call the DBA object to
 * update the existing dataset with the values of this Business Object. */
    private void internalUpdate() {
/* Transfer the values of this Business Object to the DBA object. */
      setDBAAttributes(structJS_ErrDB_Project_DBA);
/* Call the method of the DBA object to do the database INSERT on the low level. */
      structJS_ErrDB_Project_DBA.update(structDBCon);
/* Check if the database UPDATE was error-free. */
      if (structJS_ErrDB_Project_DBA.ErrorMsg.length() > 0) {
/* Error-Message is not empty; transfer the error to this object. */
        StatusCode = CONST_DB_SYSTEM_ERROR;
        StatusMsg = structJS_ErrDB_Project_DBA.ErrorMsg;
        return;
      }
    }
/*
 * --------------------
 * Method to get the datast identified by the DataSetID.
 * As this attribute is the primary key of the table, only one dataset can be found. */
    public void readByDataSetID(double parmDataSetID) {
/* Reset the Status-variables to a state of OK. */
      this.StatusCode = CONST_OK;
      this.StatusMsg = "";
/* Flag, if the Connection to the database was opened in this method;
 * needed to know if the Connection has to be closed when this method is left. */
      boolean bol_structDBConOpenedInThisMethod = false;
/* Check if the database-connection is already established.
 * (Could have been passed as parameter when this class was constructed). */
      if (! bol_structDBConEstablished) {
/* Call the method that handles the establishing of a database-connection.
 * The parameter is for 'ReadOnly'. As there is just a read-operation,
 * passing this flag improves the performance of the database */
        bol_structDBConOpenedInThisMethod = getDatabaseConnection(true);
      }
/* Verify that a database-connection was opened;
 * otherwise return an error with the Error-Message from the Connection-Manager. */
      if (intDBConReference < 0) {
        StatusCode = CONST_DB_SYSTEM_ERROR;
        StatusMsg = structJSBS_DB_ConnectionManager.StatusMsg;
        return;
      }
/* Perform the database-operation. */
      if (structJS_ErrDB_Project_DBA.selectByDataSetID(structDBCon, parmDataSetID)) {
/* Requested dataset exists; transfer the valuefrom the DBA object to this BO. */
        getDBAAttributes(structJS_ErrDB_Project_DBA);
/* Commit (although there is no commit as the Connection was opened 'ReadOnly'
 * and return the Connection to the ConnectionManager. */
        commitAndCloseDBConnection(bol_structDBConOpenedInThisMethod);
        return;
      }
      else {
/* Verify if the operation was error-free and no dataset was found
 * or an error occured. */
        if (structJS_ErrDB_Project_DBA.ErrorMsg.length() <= 0) {
/* Error-Message is empty; means that no dataset was found with the search criteria. */
          StatusCode = CONST_NOT_FOUND;
          StatusMsg = "";
/* Rollback (although there is no rollback as the Connection was opened 'ReadOnly')
 * and return the Connection to the ConnectionManager. */
          rollbackAndCloseDBConnection(bol_structDBConOpenedInThisMethod);
          return;
        }
        else {
/* Error-Message is not empty; transfer the error-message to this BO. */
          StatusCode = CONST_DB_SYSTEM_ERROR;
          StatusMsg = structJS_ErrDB_Project_DBA.ErrorMsg;
/* Rollback (although there is no rollback as the Connection was opened 'ReadOnly')
 * and return the Connection to the ConnectionManager. */
          rollbackAndCloseDBConnection(bol_structDBConOpenedInThisMethod);
          return;
        }
      }
   }
}