Exemplo n.º 1
0
Arquivo: DataItem.php Projeto: rf/2012
 /**
  * The constructor for the Services_AMEE_DataItem class.
  *
  * @param <string> $sPath The path of the AMEE API Data Item.
  * @param <array> $aOptions An optional array of AMEE API Data Item
  *      name/value pairs that define the AMEE API Data Item's Drill Down
  *      UID, in those cases where the path does not define the UID.
  * @return <object> The created Services_AMEE_DataItem object; an Exception
  *      object otherwise.
  */
 function __construct($sPath, $aOptions = array())
 {
     try {
         parent::__construct();
         // Helpfully re-format the path, if required
         if (!preg_match('#^/#', $sPath)) {
             $sPath = '/' . $sPath;
         }
         if (preg_match('#(.*)/$#', $sPath, $aMatches)) {
             $sPath = $aMatches[1];
         }
         // Store the path and array
         $this->sPath = $sPath;
         $this->aOptions = $aOptions;
         // Prepare the AMEE REST API path
         $sPath = '/data' . $this->sPath . '/drill';
         // Call the AMEE REST API
         $this->sLastJSON = $this->oAPI->get($sPath, $this->aOptions);
         // Process the result data
         $this->aLastJSON = json_decode($this->sLastJSON, true);
         // Test that a valid Data Item UID has been located
         if (isset($this->aLastJSON['choices']) && isset($this->aLastJSON['choices']['name']) && $this->aLastJSON['choices']['name'] == 'uid' && isset($this->aLastJSON['choices']['choices']) && count($this->aLastJSON['choices']['choices']) == 1 && isset($this->aLastJSON['choices']['choices'][0]) && isset($this->aLastJSON['choices']['choices'][0]['value'])) {
             // Set this object's UID
             $this->sUID = $this->aLastJSON['choices']['choices'][0]['value'];
         } else {
             throw new Services_AMEE_Exception('AMEE API Data Item Drill Down for path \'' . $sPath . '\' with the specified options did not return a Data ' . 'Item UID - check that the specified options fully ' . 'define a complete Drill Down to a single Data Item');
         }
     } catch (Exception $oException) {
         throw $oException;
     }
 }
Exemplo n.º 2
0
 /**
  * The constructor for the Services_AMEE_ProfileItem class.
  *
  * There are three different ways to create a new Services_AMEE_ProfileItem
  * object.
  *
  ***************************************************************************
  *
  * 1. Create an object for a new AMEE API Profile Item
  *
  * @param <array> $aParams An array of parameters, being:
  *
  *      $aParams[0] => <Services_AMEE_Profile> The instance of the
  *          Services_AMEE_Profile class representing the AMEE API Profile in
  *          which the new AMEE API Profile Item should be created.
  *
  *      $aParams[1] => <Services_AMEE_DataItem> The instance of the
  *          Services_AMEE_DataItem class representing the AMEE API Data Item
  *          on which the AMEE API Profile Item should be based.
  *
  *      $aParams[2] => <array> An array of name/value pairs that represent
  *          the input data for one or more AMEE API Profile Item Values.
  *
  *          For example, assuming that the AMEE API Data Item that the AMEE
  *          API Profile Item is to be based on is
  *          http://explorer.amee.com/categories/Car_Defra_By_Size, then the
  *          array *must* contain the "distance" key (because this is defined
  *          as a required parameter in the AMEE API Data Item above), with
  *          value specifying the km/year travelled. That is, the absolute
  *          minimum array that this parameter could be for this AMEE API
  *          Data Item would be, for example:
  *
  *          array(
  *              'distance' => 100
  *          );
  *
  *          representing that the car usage is/was 100 km/year.
  *
  *          Optionally, the array in this example could additionally contain
  *          the keys "occupants", "ownFuelConsumption", "totalFuelConsumed"
  *          and "numberOfJourneys", to specify additional information about
  *          the car use, as described on the AMEE API Data Item page above.
  * 
  *          Optionally, the array in this example could addtionally contain
  *          keys specifying "unit" and "perUnit" options for the name/value
  *          pairs. That is, on the
  *          http://explorer.amee.com/categories/Car_Defra_By_Size page, the
  *          required parameter "distance" is, by default, specified in
  *          km/year. However, if you wanted to specify this in another
  *          format, such as miles/week, then you could do so, by setting
  *          the array to be, for example:
  *
  *          array(
  *              'distance'        => '5'
  *              'distanceUnit'    => 'mi'
  *              'distancePerUnit' => 'week'
  *          );
  *
  *          representing that the car usage is/was 5 miles/week.
  *
  *          Note that you can only specify "unit" and "perUnit" modifer
  *          options for those name/value pairs that support it -- that is,
  *          for example, it is not possible to specify different "unit" or
  *          "perUnit" options for the "occupants" key in this case.
  *
  *          You can find details of supported units at
  *              http://my.amee.com/developers/wiki/Units
  *
  *      $aParams[3] => <array> An optional array of name/value pairs that
  *          represent AMEE API Profile Items options. Valid key values are
  *          "name", "startDate", "endDate", and "duration" as defined at
  *          http://my.amee.com/developers/wiki/ProfileItem#CreateanewProfileItem.
  *
  *          Use null for this parameter if no AMEE API Profile Item options
  *          need to be set, but you do want to set the fifth option array
  *          below.
  *
  *      $aParams[4] => <array> An optional array of name/value pairs that
  *          represent the desired "unit" and "per unit" values that should
  *          be used for the AMEE API Profile Item. Must be specified using
  *          the key values "returnUnit" and "returnPerUnit" as defined at
  *          http://my.amee.com/developers/wiki/ProfileCategory#GetCategory.
  *
  ***************************************************************************
  *
  * 2. Create an object for an existing AMEE API Profile Item by UID
  *
  * @param <array> $aParams An array of parameters, being:
  *
  *      $aParams[0] => <Services_AMEE_Profile> The instance of the
  *          Services_AMEE_Profile class representing the AMEE API Profile in
  *          which the AMEE API Profile Item exists.
  *
  *      $aParams[1] => <Services_AMEE_DataItem> The instance of the
  *          Services_AMEE_DataItem class representing the AMEE API Data Item
  *          on which the existing AMEE API Profile Item is based.
  *
  *      $aParams[2] => <string> The AMEE API Profile Item UID for the
  *          existing AMEE API Profile Item.
  *
  *      $aParams[3] => <array> An optional array of name/value pairs that
  *          represent the desired "unit" and "per unit" values that should
  *          be used for the AMEE API Profile Item. Must be specified using
  *          the key values "returnUnit" and "returnPerUnit" as defined at
  *          http://my.amee.com/developers/wiki/ProfileCategory#GetCategory.
  *
  ***************************************************************************
  *
  * 3. Create an object for an existing AMEE API Profile Item by AMEE API
  *      Data Item
  *
  * @param <array> $aParams An array of parameters, being:
  *
  *      $aParams[0] => <Services_AMEE_Profile> The instance of the
  *          Services_AMEE_Profile class representing the AMEE API Profile in
  *          which the AMEE API Profile Item exists.
  * 
  *      $aParams[1] => <Services_AMEE_DataItem> The instance of the
  *          Services_AMEE_DataItem class representing the AMEE API Data Item
  *          on which the existing AMEE API Profile Item is based.
  *
  *      $aParams[2] => <array> An optional array of name/value pairs that
  *          represent the desired "unit" and "per unit" values that should
  *          be used for the AMEE API Profile Item. Must be specified using
  *          the key values "returnUnit" and "returnPerUnit" as defined at
  *          http://my.amee.com/developers/wiki/ProfileCategory#GetCategory.
  *
  ***************************************************************************
  *
  * In all three cases:
  *
  * @return <object> A Services_AMEE_ProfileItem object (either for the
  *      specified existing AMEE API Profile Item, or for the newly created
  *      AMEE API Profile Item), or an Exception object on error.
  */
 function __construct($aParams)
 {
     try {
         parent::__construct();
         // Validate the number of parameters passed into the constructor
         if (!is_array($aParams)) {
             throw new Services_AMEE_Exception('Services_AMEE_ProfileItem constructor method called ' . 'with a parameter that is not an array');
         }
         if (count($aParams) < 2 || count($aParams) > 5) {
             throw new Services_AMEE_Exception('Services_AMEE_ProfileItem constructor method called ' . 'with the parameter array containing an invalid number ' . 'of items');
         }
         // Validate parameters one and two, which are always the object
         // representing the owning AMEE API Profile, and the object
         // representing the associated AMEE API Data Item, respectively
         if (!is_a($aParams[0], 'Services_AMEE_Profile')) {
             throw new Services_AMEE_Exception('Services_AMEE_ProfileItem constructor method called ' . 'with the parameter array\'s first parameter not being ' . 'the required Services_AMEE_Profile object');
         }
         $this->oProfile = $aParams[0];
         if (!is_a($aParams[1], 'Services_AMEE_DataItem')) {
             throw new Services_AMEE_Exception('Services_AMEE_ProfileItem constructor method called ' . 'with the parameter array\'s second parameter not being ' . 'the required Services_AMEE_DataItem object');
         }
         $this->oDataItem = $aParams[1];
         // Validate the optional third parameter and set the construction
         // method type based on the existence (or otherwise) of this
         // parameter and its type
         if (array_key_exists(2, $aParams)) {
             $sConstructType = $this->_validateThirdParam($aParams[2]);
         } else {
             $sConstructType = $this->_validateThirdParam();
         }
         // Validate the optional fourth parameter
         if ($sConstructType == 'search' && array_key_exists(3, $aParams)) {
             // The fourth parameter is only valid with construction types
             // 'new' and 'uid'
             throw new Services_AMEE_Exception('Services_AMEE_ProfileItem constructor method called ' . 'with the parameter array\'s fourth parameter being set, ' . 'but with other parameters such that a fourth parameter ' . 'is not expected to be set');
         }
         if (array_key_exists(3, $aParams)) {
             $this->_validateFourthParam($sConstructType, $aParams[3]);
         }
         // Validate the optional fifth parameter
         if ($sConstructType != 'new' && array_key_exists(4, $aParams)) {
             // The fifth parameter is only valid with construction type
             // 'new'
             throw new Services_AMEE_Exception('Services_AMEE_ProfileItem constructor method called ' . 'with the parameter array\'s fifth parameter being set, ' . 'but with other parameters such that a fifth parameter ' . 'is not expected to be set');
         }
         if (array_key_exists(4, $aParams)) {
             $this->_validateReturnUnitParamArray($aParams[4]);
         }
         // All validation has passed
         if ($sConstructType == 'new') {
             // Create a new AMEE API Profile Item in the AMEE REST API, and
             // obtain the details of the created AMEE API Profile Item
             $this->_constructNew($aParams);
         } else {
             if ($sConstructType == 'uid') {
                 // Obtain the details of the already existing AMEE API Profile
                 // Item
                 $this->_constructExistingByUID($aParams[2]);
             } else {
                 if ($sConstructType == 'search') {
                     // Obtain the details of the already existing AMEE API Profile
                     // Item
                     $this->_constructExistingBySearch();
                 } else {
                     throw new Services_AMEE_Exception('Services_AMEE_ProfileItem constructor method failed ' . 'with an internal error - found construction type of ' . $sConstructType);
                 }
             }
         }
     } catch (Exception $oException) {
         throw $oException;
     }
 }