diff options
Diffstat (limited to 'framework/base/interfaces.php')
| -rw-r--r-- | framework/base/interfaces.php | 607 |
1 files changed, 607 insertions, 0 deletions
diff --git a/framework/base/interfaces.php b/framework/base/interfaces.php new file mode 100644 index 0000000..d92b49b --- /dev/null +++ b/framework/base/interfaces.php @@ -0,0 +1,607 @@ +<?php +/** + * This file contains core interfaces for Yii framework. + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @link http://www.yiiframework.com/ + * @copyright Copyright © 2008-2011 Yii Software LLC + * @license http://www.yiiframework.com/license/ + */ + +/** + * IApplicationComponent is the interface that all application components must implement. + * + * After the application completes configuration, it will invoke the {@link init()} + * method of every loaded application component. + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @version $Id: interfaces.php 3515 2011-12-28 12:29:24Z mdomba $ + * @package system.base + * @since 1.0 + */ +interface IApplicationComponent +{ + /** + * Initializes the application component. + * This method is invoked after the application completes configuration. + */ + public function init(); + /** + * @return boolean whether the {@link init()} method has been invoked. + */ + public function getIsInitialized(); +} + +/** + * ICache is the interface that must be implemented by cache components. + * + * This interface must be implemented by classes supporting caching feature. + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @version $Id: interfaces.php 3515 2011-12-28 12:29:24Z mdomba $ + * @package system.caching + * @since 1.0 + */ +interface ICache +{ + /** + * Retrieves a value from cache with a specified key. + * @param string $id a key identifying the cached value + * @return mixed the value stored in cache, false if the value is not in the cache or expired. + */ + public function get($id); + /** + * Retrieves multiple values from cache with the specified keys. + * Some caches (such as memcache, apc) allow retrieving multiple cached values at one time, + * which may improve the performance since it reduces the communication cost. + * In case a cache doesn't support this feature natively, it will be simulated by this method. + * @param array $ids list of keys identifying the cached values + * @return array list of cached values corresponding to the specified keys. The array + * is returned in terms of (key,value) pairs. + * If a value is not cached or expired, the corresponding array value will be false. + */ + public function mget($ids); + /** + * Stores a value identified by a key into cache. + * If the cache already contains such a key, the existing value and + * expiration time will be replaced with the new ones. + * + * @param string $id the key identifying the value to be cached + * @param mixed $value the value to be cached + * @param integer $expire the number of seconds in which the cached value will expire. 0 means never expire. + * @param ICacheDependency $dependency dependency of the cached item. If the dependency changes, the item is labelled invalid. + * @return boolean true if the value is successfully stored into cache, false otherwise + */ + public function set($id,$value,$expire=0,$dependency=null); + /** + * Stores a value identified by a key into cache if the cache does not contain this key. + * Nothing will be done if the cache already contains the key. + * @param string $id the key identifying the value to be cached + * @param mixed $value the value to be cached + * @param integer $expire the number of seconds in which the cached value will expire. 0 means never expire. + * @param ICacheDependency $dependency dependency of the cached item. If the dependency changes, the item is labelled invalid. + * @return boolean true if the value is successfully stored into cache, false otherwise + */ + public function add($id,$value,$expire=0,$dependency=null); + /** + * Deletes a value with the specified key from cache + * @param string $id the key of the value to be deleted + * @return boolean whether the deletion is successful + */ + public function delete($id); + /** + * Deletes all values from cache. + * Be careful of performing this operation if the cache is shared by multiple applications. + * @return boolean whether the flush operation was successful. + */ + public function flush(); +} + +/** + * ICacheDependency is the interface that must be implemented by cache dependency classes. + * + * This interface must be implemented by classes meant to be used as + * cache dependencies. + * + * Objects implementing this interface must be able to be serialized and unserialized. + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @version $Id: interfaces.php 3515 2011-12-28 12:29:24Z mdomba $ + * @package system.caching + * @since 1.0 + */ +interface ICacheDependency +{ + /** + * Evaluates the dependency by generating and saving the data related with dependency. + * This method is invoked by cache before writing data into it. + */ + public function evaluateDependency(); + /** + * @return boolean whether the dependency has changed. + */ + public function getHasChanged(); +} + + +/** + * IStatePersister is the interface that must be implemented by state persister calsses. + * + * This interface must be implemented by all state persister classes (such as + * {@link CStatePersister}. + * + * @version $Id: interfaces.php 3515 2011-12-28 12:29:24Z mdomba $ + * @package system.base + * @since 1.0 + */ +interface IStatePersister +{ + /** + * Loads state data from a persistent storage. + * @return mixed the state + */ + public function load(); + /** + * Saves state data into a persistent storage. + * @param mixed $state the state to be saved + */ + public function save($state); +} + + +/** + * IFilter is the interface that must be implemented by action filters. + * + * @version $Id: interfaces.php 3515 2011-12-28 12:29:24Z mdomba $ + * @package system.base + * @since 1.0 + */ +interface IFilter +{ + /** + * Performs the filtering. + * This method should be implemented to perform actual filtering. + * If the filter wants to continue the action execution, it should call + * <code>$filterChain->run()</code>. + * @param CFilterChain $filterChain the filter chain that the filter is on. + */ + public function filter($filterChain); +} + + +/** + * IAction is the interface that must be implemented by controller actions. + * + * @version $Id: interfaces.php 3515 2011-12-28 12:29:24Z mdomba $ + * @package system.base + * @since 1.0 + */ +interface IAction +{ + /** + * @return string id of the action + */ + public function getId(); + /** + * @return CController the controller instance + */ + public function getController(); +} + + +/** + * IWebServiceProvider interface may be implemented by Web service provider classes. + * + * If this interface is implemented, the provider instance will be able + * to intercept the remote method invocation (e.g. for logging or authentication purpose). + * @author Qiang Xue <qiang.xue@gmail.com> + * @version $Id: interfaces.php 3515 2011-12-28 12:29:24Z mdomba $ + * @package system.base + * @since 1.0 + */ +interface IWebServiceProvider +{ + /** + * This method is invoked before the requested remote method is invoked. + * @param CWebService $service the currently requested Web service. + * @return boolean whether the remote method should be executed. + */ + public function beforeWebMethod($service); + /** + * This method is invoked after the requested remote method is invoked. + * @param CWebService $service the currently requested Web service. + */ + public function afterWebMethod($service); +} + + +/** + * IViewRenderer interface is implemented by a view renderer class. + * + * A view renderer is {@link CWebApplication::viewRenderer viewRenderer} + * application component whose wants to replace the default view rendering logic + * implemented in {@link CBaseController}. + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @version $Id: interfaces.php 3515 2011-12-28 12:29:24Z mdomba $ + * @package system.base + * @since 1.0 + */ +interface IViewRenderer +{ + /** + * Renders a view file. + * @param CBaseController $context the controller or widget who is rendering the view file. + * @param string $file the view file path + * @param mixed $data the data to be passed to the view + * @param boolean $return whether the rendering result should be returned + * @return mixed the rendering result, or null if the rendering result is not needed. + */ + public function renderFile($context,$file,$data,$return); +} + + +/** + * IUserIdentity interface is implemented by a user identity class. + * + * An identity represents a way to authenticate a user and retrieve + * information needed to uniquely identity the user. It is normally + * used with the {@link CWebApplication::user user application component}. + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @version $Id: interfaces.php 3515 2011-12-28 12:29:24Z mdomba $ + * @package system.base + * @since 1.0 + */ +interface IUserIdentity +{ + /** + * Authenticates the user. + * The information needed to authenticate the user + * are usually provided in the constructor. + * @return boolean whether authentication succeeds. + */ + public function authenticate(); + /** + * Returns a value indicating whether the identity is authenticated. + * @return boolean whether the identity is valid. + */ + public function getIsAuthenticated(); + /** + * Returns a value that uniquely represents the identity. + * @return mixed a value that uniquely represents the identity (e.g. primary key value). + */ + public function getId(); + /** + * Returns the display name for the identity (e.g. username). + * @return string the display name for the identity. + */ + public function getName(); + /** + * Returns the additional identity information that needs to be persistent during the user session. + * @return array additional identity information that needs to be persistent during the user session (excluding {@link id}). + */ + public function getPersistentStates(); +} + + +/** + * IWebUser interface is implemented by a {@link CWebApplication::user user application component}. + * + * A user application component represents the identity information + * for the current user. + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @version $Id: interfaces.php 3515 2011-12-28 12:29:24Z mdomba $ + * @package system.base + * @since 1.0 + */ +interface IWebUser +{ + /** + * Returns a value that uniquely represents the identity. + * @return mixed a value that uniquely represents the identity (e.g. primary key value). + */ + public function getId(); + /** + * Returns the display name for the identity (e.g. username). + * @return string the display name for the identity. + */ + public function getName(); + /** + * Returns a value indicating whether the user is a guest (not authenticated). + * @return boolean whether the user is a guest (not authenticated) + */ + public function getIsGuest(); + /** + * Performs access check for this user. + * @param string $operation the name of the operation that need access check. + * @param array $params name-value pairs that would be passed to business rules associated + * with the tasks and roles assigned to the user. + * @return boolean whether the operations can be performed by this user. + */ + public function checkAccess($operation,$params=array()); +} + + +/** + * IAuthManager interface is implemented by an auth manager application component. + * + * An auth manager is mainly responsible for providing role-based access control (RBAC) service. + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @version $Id: interfaces.php 3515 2011-12-28 12:29:24Z mdomba $ + * @package system.base + * @since 1.0 + */ +interface IAuthManager +{ + /** + * Performs access check for the specified user. + * @param string $itemName the name of the operation that need access check + * @param mixed $userId the user ID. This should can be either an integer and a string representing + * the unique identifier of a user. See {@link IWebUser::getId}. + * @param array $params name-value pairs that would be passed to biz rules associated + * with the tasks and roles assigned to the user. + * @return boolean whether the operations can be performed by the user. + */ + public function checkAccess($itemName,$userId,$params=array()); + + /** + * Creates an authorization item. + * An authorization item represents an action permission (e.g. creating a post). + * It has three types: operation, task and role. + * Authorization items form a hierarchy. Higher level items inheirt permissions representing + * by lower level items. + * @param string $name the item name. This must be a unique identifier. + * @param integer $type the item type (0: operation, 1: task, 2: role). + * @param string $description description of the item + * @param string $bizRule business rule associated with the item. This is a piece of + * PHP code that will be executed when {@link checkAccess} is called for the item. + * @param mixed $data additional data associated with the item. + * @return CAuthItem the authorization item + * @throws CException if an item with the same name already exists + */ + public function createAuthItem($name,$type,$description='',$bizRule=null,$data=null); + /** + * Removes the specified authorization item. + * @param string $name the name of the item to be removed + * @return boolean whether the item exists in the storage and has been removed + */ + public function removeAuthItem($name); + /** + * Returns the authorization items of the specific type and user. + * @param integer $type the item type (0: operation, 1: task, 2: role). Defaults to null, + * meaning returning all items regardless of their type. + * @param mixed $userId the user ID. Defaults to null, meaning returning all items even if + * they are not assigned to a user. + * @return array the authorization items of the specific type. + */ + public function getAuthItems($type=null,$userId=null); + /** + * Returns the authorization item with the specified name. + * @param string $name the name of the item + * @return CAuthItem the authorization item. Null if the item cannot be found. + */ + public function getAuthItem($name); + /** + * Saves an authorization item to persistent storage. + * @param CAuthItem $item the item to be saved. + * @param string $oldName the old item name. If null, it means the item name is not changed. + */ + public function saveAuthItem($item,$oldName=null); + + /** + * Adds an item as a child of another item. + * @param string $itemName the parent item name + * @param string $childName the child item name + * @throws CException if either parent or child doesn't exist or if a loop has been detected. + */ + public function addItemChild($itemName,$childName); + /** + * Removes a child from its parent. + * Note, the child item is not deleted. Only the parent-child relationship is removed. + * @param string $itemName the parent item name + * @param string $childName the child item name + * @return boolean whether the removal is successful + */ + public function removeItemChild($itemName,$childName); + /** + * Returns a value indicating whether a child exists within a parent. + * @param string $itemName the parent item name + * @param string $childName the child item name + * @return boolean whether the child exists + */ + public function hasItemChild($itemName,$childName); + /** + * Returns the children of the specified item. + * @param mixed $itemName the parent item name. This can be either a string or an array. + * The latter represents a list of item names. + * @return array all child items of the parent + */ + public function getItemChildren($itemName); + + /** + * Assigns an authorization item to a user. + * @param string $itemName the item name + * @param mixed $userId the user ID (see {@link IWebUser::getId}) + * @param string $bizRule the business rule to be executed when {@link checkAccess} is called + * for this particular authorization item. + * @param mixed $data additional data associated with this assignment + * @return CAuthAssignment the authorization assignment information. + * @throws CException if the item does not exist or if the item has already been assigned to the user + */ + public function assign($itemName,$userId,$bizRule=null,$data=null); + /** + * Revokes an authorization assignment from a user. + * @param string $itemName the item name + * @param mixed $userId the user ID (see {@link IWebUser::getId}) + * @return boolean whether removal is successful + */ + public function revoke($itemName,$userId); + /** + * Returns a value indicating whether the item has been assigned to the user. + * @param string $itemName the item name + * @param mixed $userId the user ID (see {@link IWebUser::getId}) + * @return boolean whether the item has been assigned to the user. + */ + public function isAssigned($itemName,$userId); + /** + * Returns the item assignment information. + * @param string $itemName the item name + * @param mixed $userId the user ID (see {@link IWebUser::getId}) + * @return CAuthAssignment the item assignment information. Null is returned if + * the item is not assigned to the user. + */ + public function getAuthAssignment($itemName,$userId); + /** + * Returns the item assignments for the specified user. + * @param mixed $userId the user ID (see {@link IWebUser::getId}) + * @return array the item assignment information for the user. An empty array will be + * returned if there is no item assigned to the user. + */ + public function getAuthAssignments($userId); + /** + * Saves the changes to an authorization assignment. + * @param CAuthAssignment $assignment the assignment that has been changed. + */ + public function saveAuthAssignment($assignment); + + /** + * Removes all authorization data. + */ + public function clearAll(); + /** + * Removes all authorization assignments. + */ + public function clearAuthAssignments(); + + /** + * Saves authorization data into persistent storage. + * If any change is made to the authorization data, please make + * sure you call this method to save the changed data into persistent storage. + */ + public function save(); + + /** + * Executes a business rule. + * A business rule is a piece of PHP code that will be executed when {@link checkAccess} is called. + * @param string $bizRule the business rule to be executed. + * @param array $params additional parameters to be passed to the business rule when being executed. + * @param mixed $data additional data that is associated with the corresponding authorization item or assignment + * @return whether the execution returns a true value. + * If the business rule is empty, it will also return true. + */ + public function executeBizRule($bizRule,$params,$data); +} + + +/** + * IBehavior interfaces is implemented by all behavior classes. + * + * A behavior is a way to enhance a component with additional methods that + * are defined in the behavior class and not available in the component class. + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @version $Id: interfaces.php 3515 2011-12-28 12:29:24Z mdomba $ + * @package system.base + */ +interface IBehavior +{ + /** + * Attaches the behavior object to the component. + * @param CComponent $component the component that this behavior is to be attached to. + */ + public function attach($component); + /** + * Detaches the behavior object from the component. + * @param CComponent $component the component that this behavior is to be detached from. + */ + public function detach($component); + /** + * @return boolean whether this behavior is enabled + */ + public function getEnabled(); + /** + * @param boolean $value whether this behavior is enabled + */ + public function setEnabled($value); +} + +/** + * IWidgetFactory is the interface that must be implemented by a widget factory class. + * + * When calling {@link CBaseController::createWidget}, if a widget factory is available, + * it will be used for creating the requested widget. + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @version $Id: interfaces.php 3515 2011-12-28 12:29:24Z mdomba $ + * @package system.web + * @since 1.1 + */ +interface IWidgetFactory +{ + /** + * Creates a new widget based on the given class name and initial properties. + * @param CBaseController $owner the owner of the new widget + * @param string $className the class name of the widget. This can also be a path alias (e.g. system.web.widgets.COutputCache) + * @param array $properties the initial property values (name=>value) of the widget. + * @return CWidget the newly created widget whose properties have been initialized with the given values. + */ + public function createWidget($owner,$className,$properties=array()); +} + +/** + * IDataProvider is the interface that must be implemented by data provider classes. + * + * Data providers are components that can feed data for widgets such as data grid, data list. + * Besides providing data, they also support pagination and sorting. + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @version $Id: interfaces.php 3515 2011-12-28 12:29:24Z mdomba $ + * @package system.web + * @since 1.1 + */ +interface IDataProvider +{ + /** + * @return string the unique ID that identifies the data provider from other data providers. + */ + public function getId(); + /** + * Returns the number of data items in the current page. + * This is equivalent to <code>count($provider->getData())</code>. + * When {@link pagination} is set false, this returns the same value as {@link totalItemCount}. + * @param boolean $refresh whether the number of data items should be re-calculated. + * @return integer the number of data items in the current page. + */ + public function getItemCount($refresh=false); + /** + * Returns the total number of data items. + * When {@link pagination} is set false, this returns the same value as {@link itemCount}. + * @param boolean $refresh whether the total number of data items should be re-calculated. + * @return integer total number of possible data items. + */ + public function getTotalItemCount($refresh=false); + /** + * Returns the data items currently available. + * @param boolean $refresh whether the data should be re-fetched from persistent storage. + * @return array the list of data items currently available in this data provider. + */ + public function getData($refresh=false); + /** + * Returns the key values associated with the data items. + * @param boolean $refresh whether the keys should be re-calculated. + * @return array the list of key values corresponding to {@link data}. Each data item in {@link data} + * is uniquely identified by the corresponding key value in this array. + */ + public function getKeys($refresh=false); + /** + * @return CSort the sorting object. If this is false, it means the sorting is disabled. + */ + public function getSort(); + /** + * @return CPagination the pagination object. If this is false, it means the pagination is disabled. + */ + public function getPagination(); +}
\ No newline at end of file |