Home | Classes | Modules | Annotated | Hierarchy | Functions | Files

Record.php

Go to the documentation of this file.

<?php

/*
 *  $Id: Record.php,v 1.7 2004/05/23 09:33:49 micha Exp $
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * This software consists of voluntary contributions made by many individuals
 * and is licensed under the LGPL. For more information please see
 * <http://creole.phpdb.org>.
 * 
 * This product includes software based on the Village framework,  
 * http://share.whichever.com/index.php?SCREEN=village.
 */

include_once 'creole/CreoleTypes.php';
 
class Record {
    
    // saveType constants
    const ZOMBIE = -1;
    const UNKNOWN = 0;
    const INSERT = 1;
    const UPDATE = 2;
    const DELETE = 3;
    const BEFOREINSERT = 4;
    const AFTERINSERT = 5;
    const BEFOREUPDATE = 6;
    const AFTERUPDATE = 7;
    const BEFOREDELETE = 8;
    const AFTERDELETE = 9;
    
    private $values = array();
    
    private $dirtyCols = array();
    
    private $ds;
        
    private $saveType = 0;
    
    function __construct(DataSet $ds, $addRecord = false)
    {
        $this->setParentDataSet($ds);
        if (!$addRecord) {        
            $this->createValues($this->ds->resultSet());
        }
    }
    
    private function initializeRecord() 
    {
        $this->values = array();
        $this->dirtyCols = array();
        $this->setSaveType(UNKNOWN);                
    }
    
    private function createValues(ResultSet $rs)
    {
        $this->values = $rs->getRow();
    }

    public function delete(Connection $conn = null)
    {
        $this->setSaveType(DELETE);
        $this->save($conn);
    }
    
    public function save(Connection $conn = null) 
    {
        $returnValue = false;

        if ($this->ds instanceof QueryDataSet) {
            throw new DataSetException("You cannot save a QueryDataSet. Please use a TableDataSet instead.");
        }

        if (!$this->needsToBeSaved()) {
            return $returnValue;
        }

        switch($this->saveType) {            
            case INSERT:
                $returnValue = $this->doInsert($conn);
                break;
            case UPDATE:
                $returnValue = $this->doUpdate($conn);
                break;                
            case DELETE:
                $returnValue = $this->doDelete($conn);
                break;
            default:
                throw new DataSetException("Invalid or no-action saveType for Record.");
        }
                
        return (boolean) $returnValue;
    }

    private function doDelete(Connection $conn = null) 
    {
        if ($conn === null) {
            $conn = $this->ds->connection();
        }
        
        $table = $this->ds->tableInfo();
        $stmt = null;
        try {
            $stmt = $conn->prepareStatement($this->getDeleteSql());
            $ps = 1;
            $kd = $this->ds->keydef();
            for ($i = 1, $kdsize = $kd->size(); $i <= $kdsize; $i++) {                
                $col = $kd->getAttrib($i);
                $val = $this->getValue($col);                    
                $setter = 'set' . CreoleTypes::getAffix( $table->getColumn($col)->getType() );
                $stmt->$setter($ps++, $val);
            }

            $ret = $stmt->executeUpdate();

            // note that the actual removal of the Record objects 
            // from the DataSet is done by the TDS::save() method.
            $this->setSaveType(ZOMBIE);
            
            $stmt->close();
            
            if ($ret > 1) {
                throw new SQLException("There were " . $ret . " rows deleted with this records key value.");
            }
            
            return $ret;
            
        } catch (SQLException $e) {
            if ($stmt) $stmt->close();
            throw $e;
        }
    }

    private function doUpdate(Connection $conn = null)
    {
        if ($conn === null) {
            $conn = $this->ds->connection();
        }
        
        $table = $this->ds->tableInfo();
        
        $stmt = null;
        try {
            $stmt = $conn->prepareStatement($this->getUpdateSql());
            
            $ps = 1;
            foreach($this->dirtyColumns() as $col) {
                $setter = 'set' . CreoleTypes::getAffix( $table->getColumn($col)->getType() );
                $stmt->$setter($ps++, $this->getValue($col));
            }

            $kd = $this->ds->keydef();
            for ($i = 1, $kdsize = $kd->size(); $i <= $kdsize; $i++) {
                $attrib = $kd->getAttrib($i);
                $setter = 'set' . CreoleTypes::getAffix( $table->getColumn($attrib)->getType() );
                $stmt->$setter($ps++, $this->getValue($attrib));
            }
            
            $ret = $stmt->executeUpdate();

            if ($this->ds->refreshOnSave()) {
                $this->refresh();
            } else {
                // Marks all of the values clean since they have now been saved
                $this->markRecordClean();
            }

            $this->setSaveType(AFTERUPDATE);

            if ($ret > 1) {
                throw new SQLException ("There were " . $ret . " rows updated with this records key value.");
            }            
            return $ret;
        } catch (SQLException $e) {
            if ($stmt) $stmt->close();
            throw $e;
        }
        
    }

    private function doInsert(Connection $conn = null)
    {
        $stmt = null;

        try {
            $stmt = $conn->prepareStatement($this->getInsertSql());
            $ps = 1;
            foreach($this->dirtyColumns() as $col) {
                $val = $this->getValue($col);
                $setter = 'set' . CreoleTypes::getAffix( $table->getColumn($col)->getType() );
                $stmt->$setter($ps++, $val);
            }
            
            $ret = $stmt->executeUpdate();

            if ($this->ds->refreshOnSave()) {
                $this->refresh();
            } else {
                // Marks all of the values clean since they have now been saved
                $this->markRecordClean();
            }

            $this->setSaveType(AFTERINSERT);

            if ($ret > 1) {
                // a little late again...
                throw new SQLException ("There were " . $ret . " rows inserted with this records key value.");
            }

            return $ret;
        } catch (SQLException $e) {
            if ($stmt) $stmt->close();
            throw $e;
        }        
    }

    private function getUpdateSql() 
    {
        $kd = $this->ds->keydef();
        if ($kd === null || $kd->size() === 0) {
            throw new DataSetException("You must specify KeyDef attributes for this TableDataSet in order to create a Record for update.");
        } elseif ($this->recordIsClean()) {
            throw new DataSetException ("You must Record->setValue() on a column before doing an update.");
        }

        $set_sql = "";
        $where_sql = "";
        
        $comma = false;
        
        foreach($this->dirtyColumns() as $col)  {
            if (!$comma) {
                $set_sql .= $col . " = ?";
                $comma = true;
            } else {
                $set_sql .= ", " . $col . " = ?";
            }            
        }

        $comma = false;               
        for ($i = 1, $kdsize = $kd->size(); $i <= $kdsize; $i++) {        
            $attrib = $kd->getAttrib($i);
            if (! $this->valueIsClean ($attrib)) {
                throw new DataSetException ("The value for column '" . $attrib . "' is a key value and cannot be updated.");
            }
            if (!$comma) {
                $where_sql .= $attrib . " = ?";
                $comma = true;
            } else {
                $where_sql .= " AND " . $attrib . " = ?";
            }
        }
        return "UPDATE " . $this->ds->tableName() . " SET " . $set_sql . " WHERE " . $where_sql;
    }    
    

    private function getDeleteSql() 
    {
        $kd = $this->ds->keydef();
        
        if ($kd === null || $kd->size() === 0) {
            throw new DataSetException("You must specify KeyDef attributes for this TableDataSet in order to delete a Record.");
        }

        $where_sql = "";
        $comma = false;
        for ($i = 1, $kdsize = $kd->size(); $i <= $kdsize; $i++) {
            if (!$comma) {
                $where_sql .= $kd->getAttrib($i) . " = ?";               
                $comma = true;
            } else {
                $where_sql .= " AND " . $kd->getAttrib($i) . " = ?";
            }
        }
        
        return "DELETE FROM " . $this->ds->tableName() . " WHERE " . $where_sql;
    }

    private function getInsertSql() 
    {
        $fields_sql = "";
        $values_sql = "";                
        $comma = false;
        foreach($this->dirtyColumns() as $col) {
            if (!$comma) {
                $fields_sql .= $col;
                $values_sql .= "?";
                $comma = true;
            } else {
                $fields_sql .= ", " . $col;                    
                $values_sql .= ", ?";
            }
        }
        return "INSERT INTO " . $this->ds->tableName() . " ( " . $fields_sql . " ) VALUES ( " . $values_sql . " )";
    }       

    public function getValue($col) 
    {
        if (!isset($this->values[$col])) {
            throw new DataSetException("Undefined column in Record: " . $col);
        }        
        return $this->values[$col];
    }   

    public function columns()
    {
        return array_keys($this->values);
    }

    private function dirtyColumns()
    {
        return array_keys($this->dirtyCols);
    }

    public function size()
    {
        return count($this->values);
    }
    
    public function toBeSavedWithInsert()
    {
        return ($this->saveType === INSERT);
    }
    
    public function toBeSavedWithUpdate()
    {
        return ($this->saveType === UPDATE);
    }
    
    public function toBeSavedWithDelete()
    {
        return ($this->saveType === DELETE);
    }

    public function markRecordClean()
    {
        $this->dirtyCols = array();
    }

    public function markForInsert() 
    {
        if ($this->ds instanceof QueryDataSet) {
            throw new DataSetException ("You cannot mark a record in a QueryDataSet for insert");
        }
        $this->setSaveType(INSERT);
    }
    
    public function markForUpdate()
    {
        if ($this->ds instanceof QueryDataSet) {
            throw new DataSetException ("You cannot mark a record in a QueryDataSet for update");
        }
        $this->setSaveType(UPDATE);
    }
    public function markToBeDeleted()
    {
        if ($this->ds instanceof QueryDataSet) {
            throw new DataSetException ("You cannot mark a record in a QueryDataSet for deletion");
        }
        $this->setSaveType(DELETE);
        // return this;
    }

    public function unmarkToBeDeleted() 
    {
        if ($this->saveType === ZOMBIE) {
            throw new DataSetException ("This record has already been deleted!");
        }   
        $this->setSaveType(UNKNOWN);
        //return $this;
    }
    
    public function markValueClean($col)
    {
        unset($this->dirtyCols[$col]);
    }

    public function markValueDirty($col)
    {
        $this->dirtyCols[$col] = true;
    }
   
    public function setSaveType($type)
    {
        $this->saveType = $type;
    }

    public function getSaveType()
    {
        return $this->saveType;    
    }
    
    public function setValue ($col, $value) 
    {
        $this->values[$col] = $value;
        $this->markValueDirty($col);
        return $this;
    }

    public function isAZombie()
    {
        return ($this->saveType === ZOMBIE);
    }

    public function needsToBeSaved()
    {
        return (!$this->isAZombie() || !$this->recordIsClean() || $this->toBeSavedWithUpdate() ||
                $this->toBeSavedWithDelete() || $this->toBeSavedWithInsert());
    }

    public function valueIsClean($column) 
    {
        if (!isset($this->values[$column])) {
            throw new DataSetException("Undefined column: ".$column);
        }
        return !isset($this->dirtyCols[$column]);
    }

    public function recordIsClean()
    {
        return empty($this->dirtyCols);
    }
        
    public function refresh(Connection $conn = null)
    {
        if ($conn === null) {
            $conn = $this->ds->connection();
        }
        
        if ($this->toBeSavedWithDelete()) {
            return;
        } elseif ($this->toBeSavedWithInsert()) {
            throw new DataSetException("There is no way to refresh a record which has been created with addRecord().");
        } elseif ($this->ds instanceof QueryDataSet) {
            throw new DataSetException ("You can only perform a refresh on Records created with a TableDataSet.");
        }

        $stmt = null;
        try {        
            $stmt = $conn->prepareStatement ($this->getRefreshSql());
            $ps = 1;
            $kd = $this->ds->keydef();
            for ($i = 1, $kdsize = $kd->size(); $i <= $kdsize; $i++)
            {
                $val = $this->getValue($kd->getAttrib($i));
                if ($val == null) {
                    throw new DataSetException ("You cannot execute an update with a null value for a KeyDef.");
                }                    
                $setter = 'set' . CreoleTypes::getAffix( $table->getColumn($col)->getType() );
                $stmt->$setter($ps++, $val);
            }
            $rs = $stmt->executeQuery();
            $rs->next();            
            $this->initializeRecord();
            $this->createValues($rs);
        } catch (SQLException $e) {
            if ($stmt) $stmt->close();
            throw $e;
        }
    }

    public function getRefreshSql()
    {
        if ($this->ds->keydef() === null || $this->ds->keydef()->size() === 0) {
            throw new DataSetException("You can only perform a getRefreshQueryString on a TableDataSet that was created with a KeyDef.");            
        } elseif ($this->ds instanceof QueryDataSet) {
            throw new DataSetException("You can only perform a getRefreshQueryString on Records created with a TableDataSet.");
        }
        
        $sql1 = "";
        $sql2 = "";
        $comma = false;

        foreach($this->columns() as $col) {
            if (!$comma) {                
                $attribs_sql .= $col;
                $comma = true;
            } else {
                $attribs_sql .= ", " . $col;
            }
        }

        $comma = false;

        for ($i = 1, $kdsize = $kd->size(); $i <= $kdsize; $i++) {
            $attrib = $kd->getAttrib($i);

            if (!$this->valueIsClean($attrib)) {
                throw new DataSetException (
                        "You cannot do a refresh from the database if the value " .
                        "for a KeyDef column has been changed with a Record.setValue().");
            }
            
            if (!$comma) {
                $where_sql .= $attrib . " = ?";
                $comma = true;
            } else {
                $where_sql .= " AND " . $attrib . " = ?";
            }
        }
        
        return "SELECT " . $attribs_sql . " FROM " . $this->ds->tableName() . " WHERE " . $where_sql;
    }    

    public function dataset()
    {
        return $this->ds;
    }

    public function setParentDataSet(DataSet $ds)
    {
        $this->ds = $ds;
    }
    
    public function __toString()
    {
        $sb = "{";
        foreach($this->columns() as $col) {
            $sb .= "'" . $this->getValue($col) . "',";
        }
        $sb = substr($sb, 0, -1);
        $sb .= "}";
        return $sb;
    }
    
}

---

This file is part of the Creole[php5] library.