/common/libraries/php/storage/data_class.class.php

<?php

namespace common\libraries;

/**

 * $Id: data_class.class.php 128 2009-11-09 13:13:20Z vanpouckesven $

 * @package common

 */



abstract class DataClass

{

    const CLASS_NAME = __CLASS__;

    

    const PROPERTY_ID = 'id';

    const NO_UID = - 1;

    

    const PROPERTIES_DEFAULT = 'default_properties';

    const PROPERTIES_OPTIONAL = 'optional_properties';

    

    /**

     * Properties of the data class object, stored in an associative

     * array. Combination of different types of properties.

     * Default properties => properties that are a mapping of dataclass and data table

     * Optional properties => other properties that were added in join queries

     */

    private $properties;

    

    /**

     * A list of errors that this dataclass has

     * @var Array

     */

    private $errors;



    /**

     * Creates a new data class object.

     * @param array $default_properties The default properties of the data class

     * object. Associative array.

     * @param array $optional_properties The optional properties of the data class

     * object. Associative array.

     */

    function __construct($default_properties = array (), $optional_properties = array())

    {

        $this->set_default_properties($default_properties);

        $this->set_optional_properties($optional_properties);

    }



    /**

     * Gets a default property of this data class object by name.

     * @param string $name The name of the property.

     */

    function get_default_property($name)

    {

        return $this->get_specific_property(self :: PROPERTIES_DEFAULT, $name);

    }



    /**

     * Gets the default properties of this data class.

     * @return array An associative array containing the properties.

     */

    function get_default_properties()

    {

        return $this->get_specific_properties(self :: PROPERTIES_DEFAULT);

    }



    /**

     * Sets the default properties of this dataclass

     * @param array $default_properties

     */

    function set_default_properties($default_properties)

    {

        $this->set_specific_properties(self :: PROPERTIES_DEFAULT, $default_properties);

    }



    /**

     * Get the default properties of all data classes.

     * @return array The property names.

     */

    static function get_default_property_names($extended_property_names = array())

    {

        $extended_property_names[] = self :: PROPERTY_ID;

        return $extended_property_names;

    }



    /**

     * Sets a default property of this data class by name.

     * @param string $name The name of the property.

     * @param mixed $value The new value for the property.

     */

    function set_default_property($name, $value)

    {

        $this->set_specific_property(self :: PROPERTIES_DEFAULT, $name, $value);

    }



    /**

     * Checks if the given identifier is the name of a default data class

     * property.

     * @param string $name The identifier.

     * @return boolean True if the identifier is a property name, false

     * otherwise.

     */

    static function is_default_property_name($name)

    {

        return in_array($name, self :: get_default_property_names());

    }



    /**

     * Gets the optional properties of this data class.

     * @return array An associative array containing the properties.

     */

    function get_optional_properties()

    {

        return $this->get_specific_properties(self :: PROPERTIES_OPTIONAL);

    }



    /**

     * Sets the optional properties of this dataclass

     * @param Array $optional_properties

     */

    function set_optional_properties($optional_properties)

    {

        $this->set_specific_properties(self :: PROPERTIES_OPTIONAL, $optional_properties);

    }



    /**

     * Gets a optional property of this data class object by name.

     * @param string $name The name of the property.

     */

    function get_optional_property($name)

    {

        return $this->get_specific_property(self :: PROPERTIES_OPTIONAL, $name);

    }



    /**

     * Sets a optional property of this data class by name.

     * @param string $name The name of the property.

     * @param mixed $value The new value for the property.

     */

    function set_optional_property($name, $value)

    {

        $this->set_specific_property(self :: PROPERTIES_OPTIONAL, $name, $value);

    }



    /**

     * Retrieves all the properties

     * @return Array

     */

    function get_properties()

    {

        return $this->properties;

    }



    /**

     * Sets all the properties

     * @param Array $properties

     */

    function set_properties($properties)

    {

        $this->properties = $properties;

    }



    /**

     * Sets the properties for a specific type

     * @param String $properties_type

     * @param Array $properties

     */

    function set_specific_properties($properties_type, $properties)

    {

        $this->properties[$properties_type] = $properties;

    }



    /**

     * Returns the properties for a specific type

     * @param String $properties_type

     * @return Array

     */

    function get_specific_properties($properties_type)

    {

        return $this->properties[$properties_type];

    }



    /**

     * Get a property from a property type

     * @param String $properties_type

     * @param String $property_name

     * @return String

     */

    function get_specific_property($properties_type, $property_name)

    {

        $properties = $this->get_specific_properties($properties_type);

        

        return (isset($properties) && array_key_exists($property_name, $properties)) ? $properties[$property_name] : null;

    }



    /**

     * Sets a property for a specific property type

     * @param String $properties_type

     * @param String $property_name

     * @param String $property_value

     */

    function set_specific_property($properties_type, $property_name, $property_value)

    {

        $this->properties[$properties_type][$property_name] = $property_value;

    }



    /**

     * Returns the id of this object

     * @return int The id.

     */

    function get_id()

    {

        return $this->get_default_property(self :: PROPERTY_ID);

    }



    /**

     * Sets id of the object

     * @param int $id

     */

    function set_id($id)

    {

        if (isset($id) && strlen($id) > 0)

        {

            $this->set_default_property(self :: PROPERTY_ID, $id);

        }

    }



    /**

     * Check if the data class has an id or not (and therefore exists in the database)

     * @return boolean

     */

    function is_identified()

    {

        $id = $this->get_id();

        return isset($id) && strlen($id) > 0 && $id != self :: NO_UID;

    }



    /**

     * Saves the object

     * @return boolean

     */

    function save()

    {

        if ($this->is_identified())

        {

            return $this->update();

        }

        else

        {

            return $this->create();

        }

    }



    /**

     * Returns the name of the object

     * @return String

     */

    function get_object_name()

    {

        return Utilities :: get_classname_from_object($this, true);

    }



    /**

     * Creates the object

     * @return boolean

     */

    function create()

    {

        if ($this->check_before_save())

        {

            $data_manager = $this->get_data_manager();

            $class_name = $this->get_object_name();

            

            $method = 'create_' . $class_name;

            if (method_exists($data_manager, $method))

            {

                return $data_manager->$method($this);

            }

            else

            {

                return $data_manager->create($this);

            }

        }

        return false;

    }



    /**

     * Updates the object

     * @return boolean

     */

    function update()

    {

        if ($this->check_before_save())

        {

            $data_manager = $this->get_data_manager();

            $class_name = $this->get_object_name();

            

            $method = 'update_' . $class_name;

            

            if (method_exists($data_manager, $method))

            {

                return $data_manager->$method($this);

            }

            else

            {

                $condition = new EqualityCondition(self :: PROPERTY_ID, $this->get_id());

                return $data_manager->update($this, $condition);

            }

        }

        return false;

    }



    /**

     * Deletes the object

     * @return boolean

     */

    function delete()

    {

        $data_manager = $this->get_data_manager();

        $class_name = $this->get_object_name();

        

        $method = 'delete_' . $class_name;

        

        if (method_exists($data_manager, $method))

        {

            return $data_manager->$method($this);

        }

        else

        {

            $condition = new EqualityCondition(self :: PROPERTY_ID, $this->get_id());

            return $data_manager->delete($this->get_table_name(), $condition);

        }

    }



    /**

     * Check wether the object contains all mandatory properties to be saved in datasource

     * This method should be overriden in classes inheriting from DataClass

     *

     * @return boolean Return true if the object can be saved, false otherwise

     */

    protected function check_before_save()

    {

        /*

         * Example: object with mandatory title

         *

         * if(StringUtilities :: is_null_or_empty($this->get_title()))

         * {

         *    $this->add_error(Translation :: get('TitleIsRequired'));

         * }

         *

         */

        

        return ! $this->has_errors();

    }



    /**

     * Adds an error to the error list

     * @param String $error_msg

     */

    public function add_error($error_msg)

    {

        if (! isset($this->errors))

        {

            $this->errors = array();

        }

        

        $this->errors[] = $error_msg;

    }



    /**

     * Checks wether the object has errors

     * @return booleans

     */

    public function has_errors()

    {

        return isset($this->errors) && count($this->errors) > 0;

    }



    /**

     * Retrieves the list of errors

     * @return Array

     */

    public function get_errors()

    {

        return isset($this->errors) ? $this->errors : array();

    }



    /**

     * Clears the errors

     */

    public function clear_errors()

    {

        unset($this->errors);

    }



    /**

     * Gets the data manager

     */

    abstract function get_data_manager();



    static function is_extended_type()

    {

        return false;

    }

}

?>