Code for the Server-Side Business Object holding a set of 'Project' Business Objects - Fat-Client-Development

This is document contains the code for Class JS_ErrDB_Project_Set_BOS.
This is the Client-Derivation for the Business Object holding a set of 'Project' Business Objects.

For easy 'cut and paste' ;-)

package js_errdb.bos;

import java.sql.*;

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

import js_errdb.bo.*;
import js_errdb.dba.*;

/**
 *
 * @author kurt@javascout.biz
 * @date 2007-01-12
 *
 * @description
 *  Server-Side Derivation of a Set of Business Objects reflecting 'Project's.
 *
 *  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 get a list of data-sets by using the more simple methods
 *  * Implements (if neccessary) the logic to get additional Business Objects (which
      are like 'children' of a Business Object)..
 *  * 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_Set_BOS extends JS_ErrDB_Project_Set_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_Set_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_Set_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_Set_BOS(JSBS_MinimalParameters parmMinParm,
                                        JSBS_DB_ConnectionManager parmJSBS_DB_ConnectionManager,
                                        JS_ErrDB_Project_Set_BO parmJS_ErrDB_Project_Set_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_Set_BO(parmJS_ErrDB_Project_Set_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_Set_BOS(JSBS_MinimalParameters parmMinParm,
                                    Connection parmDBCon,
                                    JS_ErrDB_Project_Set_BO parmJS_ErrDB_Project_Set_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 Object to
 * copy the values from the BO passed as parameter to the variables of this Business Objject. */
      getJS_ErrDB_Project_Set_BO(parmJS_ErrDB_Project_Set_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 = JSBS_BO.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,
                                            boolean parmReadOnly) {
/* Run the 'commit' to have a integral state of all changes made with this db-connection. */
      if (! parmDBConOpenedInThisMethod) return;
/* If the 'commit' only if the connection is not specified to 'autocommit'. */
      if (! parmReadOnly) {
/* 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 = JSBS_BO.CONST_DB_SYSTEM_ERROR;
          StatusMsg = SQLExc.getMessage();
/* To be on the sure side: perform a rollback. */
          rollbackAndCloseDBConnection(parmDBConOpenedInThisMethod, parmReadOnly);
        }
      }
/* 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,
                                              boolean parmReadOnly) {
/* If the connection was not opened in the calling method: do nothing. */
      if (! parmDBConOpenedInThisMethod) return;
/* If the 'commit' only if the connection is not specified to 'autocommit'. */
      if (! parmReadOnly) {
/* 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 = JSBS_BO.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 attibutes from the Data-Base-Access (DBA) Object
 * that coincides this Business Object to this Business Object. */
    private void getDBARecords(JS_ErrDB_Project_Set_DBA parmJS_ErrDB_Project_Set_DBA) {
/* Check if the DBA-Set is empty; in this case return the 'Not Found' Status. */
      int locintVectorSize = parmJS_ErrDB_Project_Set_DBA.vecRecordSet.size();
      if (locintVectorSize < 1) {
        StatusCode = JSBS_BO.CONST_NOT_FOUND;
        return;
      }
/* Run a loop to get each DBA-Object out of the vector; transfer it to the BO
 * and put it to the vector of this object. */
      int locintVectorIndex;
      for (locintVectorIndex = 0; locintVectorIndex < locintVectorSize; locintVectorIndex++) {
/* Define a variable for the DBA-object and get the DBA-object out of the vector. */
        JS_ErrDB_Project_DBA locstructJS_ErrDB_Project_DBA =
          (JS_ErrDB_Project_DBA) parmJS_ErrDB_Project_Set_DBA.vecRecordSet.elementAt(locintVectorIndex);
/* Construct a BO and define the attributes from the DBA-object. */
        JS_ErrDB_Project_BO locstructJS_ErrDB_Project_BO = new JS_ErrDB_Project_BO();
        locstructJS_ErrDB_Project_BO.getDBAAttributes(locstructJS_ErrDB_Project_DBA);
/* Add the just created BO to the vector of this object. */
        vecRecordSet.addElement(locstructJS_ErrDB_Project_BO);
      }
    }
/*
 * --------------------
 * Method to get all datasets that are valid at the current date
 * (supplied with the 'MinimalParameter').
 * As this BO is pretty simple, no further 'search criteria' is defined. */
    public void getAllValidProjectLanguageCombinations() {
/* Define that there are only 'Read' operations: set 'autocommit'. */
      boolean bol_autocommit = true;
/* Empty the vector of this object as the result is completely renewed with the found data. */
      this.vecRecordSet.removeAllElements();
/* Reset the Status-variables to a state of OK. */
      this.StatusCode = JSBS_BO.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(bol_autocommit);
      }
/* Verify that a database-connection was opened;
 * otherwise return an error with the Error-Message from the Connection-Manager. */
      if (intDBConReference < 0) {
        StatusCode = JSBS_BO.CONST_DB_SYSTEM_ERROR;
        StatusMsg = structJSBS_DB_ConnectionManager.StatusMsg;
        return;
      }
/* Perform the database-operation. */
      JS_ErrDB_Project_Set_DBA structJS_ErrDB_Project_Set_DBA =
        new JS_ErrDB_Project_Set_DBA();
      structJS_ErrDB_Project_Set_DBA.getAllValidProjectLanguageCombinations(structDBCon,
                                                                            structJSBS_MinimalParameters);
/* Verify that the db-operation ended error-free.
 * This is done by checking for an empty Error-Message */
      if (structJS_ErrDB_Project_Set_DBA.ErrorMsg.length() < 1) {
        getDBARecords(structJS_ErrDB_Project_Set_DBA);
/* Commit (although there is no commit as the Connection was opened 'ReadOnly' -
 * but is easier to copy and paste ;-) )
 * and return the Connection to the ConnectionManager. */
        commitAndCloseDBConnection(bol_structDBConOpenedInThisMethod, bol_autocommit);
        return;
      }
      else {
/* Transfer the error-message and set a Status-Code. */
        StatusMsg = structJS_ErrDB_Project_Set_DBA.ErrorMsg;
        StatusCode = JSBS_BO.CONST_DB_SYSTEM_ERROR;
/* Rollback (although there is no rollback as the Connection was opened 'ReadOnly')
 * and return the Connection to the ConnectionManager. */
        rollbackAndCloseDBConnection(bol_structDBConOpenedInThisMethod, bol_autocommit);
        return;
      }
   }
}