[Summary view] [Print] [Text view]

   1  <?php
   2  /* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
   3  
   4  // +----------------------------------------------------------------------+
   5  // | Akelos Framework - http://www.akelos.org                             |
   6  // +----------------------------------------------------------------------+
   7  // | Copyright (c) 2002-2006, Akelos Media, S.L.  & Bermi Ferrer Martinez |
   8  // | Released under the GNU Lesser General Public License, see LICENSE.txt|
   9  // +----------------------------------------------------------------------+
  10  
  11  /**
  12   * @package ActionWebservice
  13   * @subpackage Api
  14   * @author Bermi Ferrer <bermi a.t akelos c.om>
  15   * @copyright Copyright (c) 2002-2006, Akelos Media, S.L. http://www.akelos.org
  16   * @license GNU Lesser General Public License <http://www.gnu.org/copyleft/lesser.html>
  17   */
  18  
  19  /**
  20   * A web service API class specifies the methods that will be available for
  21   * invocation for an API. It also contains metadata such as the method type
  22   * signature hints.
  23   *
  24   * It is not intended to be instantiated.
  25   *
  26   * It is attached to web service implementation classes like
  27   * AkActionWebService and AkActionController derivatives by using
  28   * <tt>container::web_service_api</tt>, where <tt>container</tt> is an
  29   * AkActionController or an AkActionWebService.
  30   *
  31   * See AkActionWebService/AkDirectContainer.php class methods for an example
  32   * of use.
  33   */
  34  class AkActionWebserviceApi extends AkObject 
  35  {   
  36      /**
  37       * Whether to transform the public API method names into camel-cased names 
  38       */
  39      var $inflect_names = true;
  40      
  41      /**
  42       * Whether to localize the API documentation automatically.
  43       */
  44      var $localize_documentation = true;
  45  
  46      /**
  47      * If present, the name of a method to call when the remote caller
  48      * tried to call a nonexistent method. 
  49      */
  50      var $default_api_method;
  51      
  52      var $_api_methods = array();
  53      var $_api_public_method_names = array();
  54      
  55      /**
  56      * API methods have a +name+, which must be the PHP method name to use when
  57      * performing the invocation on the web service object.
  58      *
  59      * The signatures for the method input parameters and return value can
  60      * by specified in +options+.
  61      *
  62      * A signature is an array of one or more parameter specifiers. 
  63      * A parameter specifier can be one of the following:
  64      *
  65      * * A string representing one of the Action Web Service base types.
  66      *   See AkActionWebService/AkSignatureTypes.php for a canonical list of the base types.
  67      * * The Class object of the parameter type
  68      * * A single-element Array containing one of the two preceding items. This
  69      *   will cause Action Web Service to treat the parameter at that position
  70      *   as an array containing only values of the given type.
  71      * * An Array containing as key the name of the parameter, and as value
  72      *   one of the three preceding items
  73      * 
  74      * If no method input parameter or method return value signatures are given,
  75      * the method is assumed to take no parameters and/or return no values of
  76      * interest, and any values that are received by the server will be
  77      * discarded and ignored.
  78      *
  79      * Valid options:
  80      * <tt>expects</tt>             Signature for the method input parameters
  81      * <tt>returns</tt>             Signature for the method return value
  82      * <tt>expects_and_returns</tt> Signature for both input parameters and return value
  83      */
  84      function addApiMethod($name, $options = array())
  85      {
  86          $this->_validateOptions(array('expects', 'returns', 'expects_and_returns', 'documentation'), array_keys($options));
  87          if (!empty($options['expects_and_returns'])){
  88              $expects = $returns = $options['expects_and_returns'];
  89          }else{
  90              $expects = @$options['expects'];
  91              $returns = @$options['returns'];
  92          }
  93  
  94          $public_name = $this->getPublicApiMethodName($name);
  95          $method =& new AkActionWebServiceMethod($name, $public_name, $expects, $returns, @$options['documentation'], $this->localize_documentation);
  96          $this->_api_methods[$name] =& $method;
  97          $this->_api_public_method_names[$public_name] = $name;
  98      }
  99  
 100      /**
 101      * Whether the given method name is a service method on this API
 102      */
 103      function hasApiMethod($name)
 104      {
 105          return !empty($this->_api_methods[$name]);
 106      }
 107  
 108      /**
 109      * Whether the given public method name has a corresponding service method
 110      * on this API
 111      */
 112      function hasPublicApiMethod($public_name)
 113      {
 114          return !empty($this->_api_public_method_names[$public_name]);
 115      }
 116  
 117      /**
 118      * The corresponding public method name for the given service method name
 119      */
 120      function getPublicApiMethodName($name)
 121      {
 122          return $this->inflect_names ? AkInflector::camelize($name) : $name;
 123      }
 124  
 125      /**
 126      * The corresponding service method name for the given public method name
 127      */
 128      function getApiMethodName($public_name)
 129      {
 130          return $this->_api_public_method_names[$public_name];
 131      } 
 132      
 133      /**
 134      * An array containing all service methods on this API, and their
 135      * associated metadata.
 136      */
 137      function &getApiMethods()
 138      {
 139          return $this->_api_methods;
 140      }
 141  
 142      /**
 143      * The Method instance for the given public API method name, if any
 144      */
 145      function &getPublicApiMethodInstance($public_method_name)
 146      {
 147          return $this->getApiMethodInstance($this->getApiMethodName($public_method_name));
 148      }
 149  
 150      /**
 151      * The Method instance for the given API method name, if any
 152      */
 153      function &getApiMethodInstance($method_name)
 154      {
 155          return $this->_api_methods[$method_name];
 156      }
 157  
 158      /**
 159      * The Method instance for the default API method, if any
 160      */
 161      function &getDefaultApiMethodInstance()
 162      {
 163          if(empty($this->default_api_method)){
 164              $false = false;
 165              return $false;
 166          }
 167  
 168          $name = $this->default_api_method;
 169          if(!empty($this->default_api_method_instance->name) && $this->default_api_method_instance->name == $name){
 170              return $this->default_api_method_instance;
 171          }
 172  
 173          $this->default_api_method_instance =& new AkActionWebServiceMethod($name, $this->getPublicApiMethodName($name), null, null, null);
 174          return $this->default_api_method_instance;
 175      }
 176  
 177      function _getApiPublicMethodNames()
 178      {
 179          return array_keys($this->_api_public_method_names);
 180      }
 181  
 182      function _validateOptions($valid_option_keys, $supplied_option_keys)
 183      {
 184          $unknown_option_keys = array_diff($supplied_option_keys, $valid_option_keys);
 185          if(!empty($unknown_option_keys)){
 186              trigger_error(Ak::t('Unknown options: %options', array('%options'=> var_export($unknown_option_keys,true))), E_USER_ERROR);
 187          }
 188      }
 189  }
 190  
 191  
 192  /**
 193  * Represents an API method and its associated metadata, and provides functionality
 194  * to assist in commonly performed API method tasks.
 195  */
 196  class AkActionWebServiceMethod
 197  {
 198      var $name;
 199      var $public_name;
 200      var $expects;
 201      var $returns;
 202      var $documentation;
 203      var $expects_documentation = array();
 204      var $returns_documentation = array();
 205  
 206      function AkActionWebServiceMethod($name, $public_name, $expects, $returns, $documentation, $localize_documentation = true)
 207      {
 208          $this->name = $name;
 209          $this->public_name = $public_name;
 210          $this->expects = $expects;
 211          $this->returns = $returns;
 212          $this->documentation = $documentation;
 213          $this->localize_documentation = $localize_documentation;
 214         
 215          $this->_extractDocumentationFromExpects();
 216          $this->_extractDocumentationFromReturns();
 217      }
 218      
 219      function _extractDocumentationFromExpects()
 220      {
 221          return $this->_extractDocumentationFromMethod('expects');
 222      }
 223      
 224      function _extractDocumentationFromReturns()
 225      {
 226          return $this->_extractDocumentationFromMethod('returns');
 227      }
 228      
 229      function _extractDocumentationFromMethod($expects_or_returns)
 230      {
 231          if(!in_array($expects_or_returns, array('expects', 'returns'))){
 232              trigger_error(Ak::t('Only expects and returns options are valid'), E_USER_ERROR);
 233              return false;
 234          }
 235          $parameters = array();
 236          $i = 0;
 237          foreach ((array)$this->{$expects_or_returns} as $parameter=>$documentation){
 238              
 239              if(is_numeric($parameter)){
 240                  $parameters[] = $documentation;
 241              }else{
 242                  $parameters[] = $parameter;
 243                  $this->{$expects_or_returns.'_documentation'}[$i] = $documentation;
 244              }
 245              $i++;
 246          }
 247          $this->{$expects_or_returns} = $parameters;
 248      }
 249      
 250  }
 251  
 252  ?>