<?php
 
//
// Open Web Analytics - An Open Source Web Analytics Framework
//
// Copyright 2006 - 2010 Peter Adams. All rights reserved.
//
// Licensed under GPL v2.0 http://www.gnu.org/copyleft/gpl.html
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
// $Id$
//
 
/**
 * Abstract Update Class
 * 
 * Performs an Update for a specific module
 *
 * @author      Peter Adams <peter@openwebanalytics.com>
 * @copyright   Copyright &copy; 2008 Peter Adams <peter@openwebanalytics.com>
 * @license     http://www.gnu.org/copyleft/gpl.html GPL v2.0
 * @category    owa
 * @package     owa
 * @version             $Revision$            
 * @since               owa 1.0.0
 */
 
class owa_update extends owa_base {
        
        /**
         * Module Name
         *
         * Name of the module that his update is invoked under. This is set by the
         * factory.
         *
         * @var string
         */
        var $module_name;
        
        /**
         * Schema Version Number
         *
         * Version number of the schema that will be in place after update is applied.
         *
         * This is set by the module's update method from the concrete class filename 
         * when it creates the concrete version of this update class.  This ensures 
         * that the schema version number is only set in one place (the file name) and 
         * that only one concrete update class can ever be applied for a particular 
         * schema version.
         *
         * @var integer
         */
        var $schema_version;
        
        var $is_cli_mode_required;
        
        function __construct() {
                                
                return parent::__construct();
        }
        
        function isCliModeRequired() {
                
                return $this->is_cli_mode_required;
        }
        
        /**
         * Applies an update
         *
         * @return boolean
         */
        function apply() {
                
                // check for schema version. abort if not present or else updates will get out of sync.
                if (empty($this->schema_version)) {
                        $this->e->notice(sprintf("Aborting %s Update (%s): Schema Version Number is not set.", get_class(), $this->module_name));
                        return false;
                }
                
                $current_version = $this->c->get($this->module_name, 'schema_version');
                
                // check to see that you are applying an update that was successfully applied
                if ($current_version === $this->schema_version) { 
                        $this->e->notice(sprintf("Aborting %s Update (%s): Update has already ben applied.", get_class(), $this->module_name));
                        return false;
                }
                
                // execute pre update proceadure
                $ret = $this->pre();
                
                if ($ret == true):
                
                        $this->e->notice("Pre Update Proceadure Suceeded");
                        
                        // execute actual update proceadure
                        $ret = $this->up();
        
                        if ($ret == true):
                        
                                // execute post update proceadure
                                $ret = $this->post();
                
                                if ($ret == true):
                                        $this->e->notice("Post Update Proceadure Suceeded");
                                        $this->c->persistSetting($this->module_name, 'schema_version', $this->schema_version);
                                        $this->c->save();
                                        return true;
                                else:
                                        $this->e->notice("Post Update Proceadure Failed");
                                        return false;
                                endif;
                        else:
                                $this->e->notice("Update Proceadure Failed");
                                return false;
                        endif;
                else:
                        $this->e->notice("Pre Update Proceadure Failed");
                        return false;
                endif;
                
        }
        
        
        /**
         * Rollsback an update
         *
         * @return boolean
         */
        function rollback() {
                
                $current_version = $this->c->get($this->module_name, 'schema_version');
                
                // check to see that you are rolling back either an update that was successfully applied or one that might have failed.
                // we dont want people applying rollbacks out of sequence.
                if ($current_version === $this->schema_version || $current_version === $this->schema_version - 1) {
                        $ret = $this->down();
                        if ($ret) {
                                // only touch the current schema number if needed
                                
                                $prior_version = $current_version - 1;
 
                                if ($current_version === $this->schema_version) {
                                        $this->c->persistSetting($this->module_name, 'schema_version', $prior_version);
                                        $this->c->save();
                                        $this->e->notice("Rollback succeeded to version: $prior_version.");
                                } else {
                                        $this->e->notice("Rollback succeeded to version: $current_version.");
                                }
                                
                        } else {
                                $this->e->notice("Rollback failed.");
                        }                       
                } else {
                        $this->e->notice(sprintf('Rollback of update %s cannot be applied because it does not appear that it update %s has been applied to your instance. Your current schema version is only %s', $this->schema_version, $this->schema_version, $current_version));
                }
                
                return true;
        }
        
        /**
         * Abstract Pre-update hook
         *
         * @return boolean
         */
        function pre() {
                
                return true;
        }
        
        /**
         * Abstract Post-update hook
         *
         * @return boolean
         */
        function post() {
                
                return true;
        }
        
        /**
         * Abstract Method for update 
         *
         * @return boolean
         */
        function up() {
        
                return false;
        }
        
        /**
         * Abstract Method for reversing an update
         *
         * @return boolean
         */
        function down() {
                
                return false;
        }
                
}
 
?>