first commit
This commit is contained in:
316
plugins/emu/lib/imu_api/Web/Service.php
Executable file
316
plugins/emu/lib/imu_api/Web/Service.php
Executable file
@@ -0,0 +1,316 @@
|
||||
<?php
|
||||
/* KE Software Open Source Licence
|
||||
**
|
||||
** Notice: Copyright (c) 2011-2013 KE SOFTWARE PTY LTD (ACN 006 213 298)
|
||||
** (the "Owner"). All rights reserved.
|
||||
**
|
||||
** Licence: Permission is hereby granted, free of charge, to any person
|
||||
** obtaining a copy of this software and associated documentation files
|
||||
** (the "Software"), to deal with the Software without restriction,
|
||||
** including without limitation the rights to use, copy, modify, merge,
|
||||
** publish, distribute, sublicense, and/or sell copies of the Software,
|
||||
** and to permit persons to whom the Software is furnished to do so,
|
||||
** subject to the following conditions.
|
||||
**
|
||||
** Conditions: The Software is licensed on condition that:
|
||||
**
|
||||
** (1) Redistributions of source code must retain the above Notice,
|
||||
** these Conditions and the following Limitations.
|
||||
**
|
||||
** (2) Redistributions in binary form must reproduce the above Notice,
|
||||
** these Conditions and the following Limitations in the
|
||||
** documentation and/or other materials provided with the distribution.
|
||||
**
|
||||
** (3) Neither the names of the Owner, nor the names of its contributors
|
||||
** may be used to endorse or promote products derived from this
|
||||
** Software without specific prior written permission.
|
||||
**
|
||||
** Limitations: Any person exercising any of the permissions in the
|
||||
** relevant licence will be taken to have accepted the following as
|
||||
** legally binding terms severally with the Owner and any other
|
||||
** copyright owners (collectively "Participants"):
|
||||
**
|
||||
** TO THE EXTENT PERMITTED BY LAW, THE SOFTWARE IS PROVIDED "AS IS",
|
||||
** WITHOUT ANY REPRESENTATION, WARRANTY OR CONDITION OF ANY KIND, EXPRESS
|
||||
** OR IMPLIED, INCLUDING (WITHOUT LIMITATION) AS TO MERCHANTABILITY,
|
||||
** FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. TO THE EXTENT
|
||||
** PERMITTED BY LAW, IN NO EVENT SHALL ANY PARTICIPANT BE LIABLE FOR ANY
|
||||
** CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
||||
** TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
||||
** SOFTWARE OR THE USE OR OTHER DEALINGS WITH THE SOFTWARE.
|
||||
**
|
||||
** WHERE BY LAW A LIABILITY (ON ANY BASIS) OF ANY PARTICIPANT IN RELATION
|
||||
** TO THE SOFTWARE CANNOT BE EXCLUDED, THEN TO THE EXTENT PERMITTED BY
|
||||
** LAW THAT LIABILITY IS LIMITED AT THE OPTION OF THE PARTICIPANT TO THE
|
||||
** REPLACEMENT, REPAIR OR RESUPPLY OF THE RELEVANT GOODS OR SERVICES
|
||||
** (INCLUDING BUT NOT LIMITED TO SOFTWARE) OR THE PAYMENT OF THE COST OF SAME.
|
||||
*/
|
||||
require_once __DIR__ . '/../IMu.php';
|
||||
require_once IMu::$lib . '/Exception.php';
|
||||
require_once IMu::$lib . '/Handler.php';
|
||||
require_once IMu::$lib . '/Session.php';
|
||||
require_once IMu::$lib . '/Trace.php';
|
||||
|
||||
/**
|
||||
* @brief A helper class for implementing %IMu web services.
|
||||
* @code{.php}
|
||||
* require_once IMu::$lib . '/Web/Service.php';
|
||||
* @endcode
|
||||
* @copyright 2011-2012 KE SOFTWARE PTY LTD
|
||||
* @version 2.0
|
||||
*/
|
||||
class IMuWebService
|
||||
{
|
||||
/**
|
||||
* @details The base web service directory. Supplied in the constructor.
|
||||
* @var string $dir
|
||||
* @see __construct()
|
||||
*/
|
||||
public $dir;
|
||||
|
||||
/**
|
||||
* @details The full request URL. Generated at construction.
|
||||
* @var string $url
|
||||
* @see __construct()
|
||||
*/
|
||||
public $url;
|
||||
|
||||
/**
|
||||
* @details The configuration options. Loaded from files at construction.
|
||||
* @var array $config
|
||||
* @see __construct()
|
||||
* @see loadConfig()
|
||||
*/
|
||||
public $config;
|
||||
|
||||
/**
|
||||
* @details The HTTP GET & POST parameters. Generated at construction.
|
||||
* @var array $params
|
||||
* @see __construct()
|
||||
*/
|
||||
public $params;
|
||||
|
||||
/**
|
||||
* @details Determines the full request URL, loads all GET & POST parameters
|
||||
* to a common variable and loads config files relative to #$dir param.
|
||||
*
|
||||
* @param string $dir
|
||||
* The base web service directory.
|
||||
* @see loadConfig()
|
||||
*/
|
||||
public function
|
||||
__construct($dir)
|
||||
{
|
||||
$this->dir = $dir;
|
||||
|
||||
$this->url = strtolower(preg_replace('/\/.*$/', '', $_SERVER['SERVER_PROTOCOL']));
|
||||
if (isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] == 'on')
|
||||
$this->url .= 's';
|
||||
$this->url .= '://' . $_SERVER['SERVER_NAME'];
|
||||
if ($_SERVER['SERVER_PORT'] != 80)
|
||||
$this->url .= ':' . $_SERVER['SERVER_PORT'];
|
||||
$this->url .= $_SERVER['REQUEST_URI'];
|
||||
|
||||
$this->params = array();
|
||||
global $_GET;
|
||||
foreach ($_GET as $name => $value)
|
||||
$this->params[$name] = $value;
|
||||
global $_POST;
|
||||
foreach ($_POST as $name => $value)
|
||||
$this->params[$name] = $value;
|
||||
|
||||
/* Configure */
|
||||
$config = array();
|
||||
|
||||
/* ... defaults */
|
||||
$config['host'] = IMuSession::getDefaultHost();
|
||||
$config['port'] = IMuSession::getDefaultPort();
|
||||
|
||||
/* ... service-specific */
|
||||
$this->loadConfig($config);
|
||||
|
||||
$this->config = $config;
|
||||
if (array_key_exists('trace-file', $this->config))
|
||||
IMuTrace::setFile($this->config['trace-file']);
|
||||
if (array_key_exists('trace-level', $this->config))
|
||||
IMuTrace::setLevel($this->config['trace-level']);
|
||||
}
|
||||
|
||||
/**
|
||||
* @details Remove and return the value for the HTTP parameter specified by
|
||||
* $name from #$params or just return $default if the parameter does not
|
||||
* exists.
|
||||
*
|
||||
* @param string $name
|
||||
* The name of the parameter to remove and return.
|
||||
* @param string $default
|
||||
* The value to return if no value exists for $name.
|
||||
*
|
||||
* @retval mixed
|
||||
* The value of the parameter specified by $name or $default.
|
||||
*/
|
||||
public function
|
||||
extractParam($name, $default = false)
|
||||
{
|
||||
if (! array_key_exists($name, $this->params))
|
||||
return $default;
|
||||
$value = $this->params[$name];
|
||||
unset($this->params[$name]);
|
||||
return $value;
|
||||
}
|
||||
|
||||
/**
|
||||
* @details Return the value for the HTTP parameter specified by $name from
|
||||
* #$params or just return $default if the parameter does not exists.
|
||||
*
|
||||
* @param string $name
|
||||
* The name of the parameter to return.
|
||||
* @param string $default
|
||||
* The value to return if no value exists for $name.
|
||||
*
|
||||
* @retval mixed
|
||||
* The value of the parameter specified by $name or $default.
|
||||
*/
|
||||
public function
|
||||
getParam($name, $default = false)
|
||||
{
|
||||
if (! array_key_exists($name, $this->params))
|
||||
return $default;
|
||||
return $this->params[$name];
|
||||
}
|
||||
|
||||
/**
|
||||
* @details Check for the presence of the HTTP parameter specified by $name
|
||||
* in #$params.
|
||||
*
|
||||
* @param string $name
|
||||
* The name of the parameter to check.
|
||||
*
|
||||
* @retval boolean
|
||||
* True if $name exists, false otherwise.
|
||||
*/
|
||||
public function
|
||||
hasParam($name)
|
||||
{
|
||||
return array_key_exists($name, $this->params);
|
||||
}
|
||||
|
||||
/**
|
||||
* @details Set the HTTP parameter specified by $name in #$params.
|
||||
*
|
||||
* @param string $name
|
||||
* The name of the parameter to set.
|
||||
* @param string $value
|
||||
* The value to set the parameter specified by $name.
|
||||
*/
|
||||
public function
|
||||
setParam($name, $value)
|
||||
{
|
||||
$this->params[$name] = $value;
|
||||
}
|
||||
|
||||
/**
|
||||
* @details An empty method definition. The convention is to overridden this
|
||||
* method in a subclass and call it to process web service requests.
|
||||
*
|
||||
* @internal
|
||||
* @note This should probably be abstract or removed. I don't see any
|
||||
* value in this function. It could literally just be a convention to use
|
||||
* process() as the entry point to web service request processing.
|
||||
*/
|
||||
public function
|
||||
process()
|
||||
{
|
||||
/* Do nothing by default */
|
||||
}
|
||||
|
||||
/**
|
||||
* @details An IMuSession object. Only accessible after the connect()
|
||||
* method has been called.
|
||||
* @var IMuSession $session
|
||||
* @see connect()
|
||||
*/
|
||||
protected $session;
|
||||
|
||||
/**
|
||||
* @details Construct an IMuSession object and invoke its @link
|
||||
* IMuSession#connect() connect()@endlink method using the `host` and
|
||||
* `port` parameters of the #$config variable.
|
||||
*
|
||||
* @see $session
|
||||
*/
|
||||
protected function
|
||||
connect()
|
||||
{
|
||||
$this->session = new IMuSession;
|
||||
$this->session->host = $this->config['host'];
|
||||
$this->session->port = $this->config['port'];
|
||||
$this->session->connect();
|
||||
}
|
||||
|
||||
/**
|
||||
* @details Disconnect from the IMuSession.
|
||||
*
|
||||
* @see $session
|
||||
*/
|
||||
protected function
|
||||
disconnect()
|
||||
{
|
||||
$this->session->disconnect();
|
||||
}
|
||||
|
||||
/**
|
||||
* @details Load configuration options from the files:
|
||||
* - /ws/common/config.php
|
||||
* - /ws/client/config.php
|
||||
* - /ws/local/config.php
|
||||
*
|
||||
* relative to #$dir.
|
||||
*
|
||||
* @param array &$config
|
||||
* @see __construct()
|
||||
*/
|
||||
protected function
|
||||
loadConfig(&$config)
|
||||
{
|
||||
@include $this->dir . '/ws/common/config.php';
|
||||
@include $this->dir . '/ws/client/config.php';
|
||||
@include $this->dir . '/ws/local/config.php';
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* @details Write an error to the trace file and throw an IMuException.
|
||||
* @note Optionally, any number of additional parameters can be supplied when
|
||||
* calling this function. Usually these are messages or values that provide
|
||||
* more information about the error that is being raised.
|
||||
*
|
||||
* Usage examples:
|
||||
* @code{.php}
|
||||
* raise(400, 'UpdateNoFiles');
|
||||
* raise(500, 'MultimediaTempFileOpen', $tempName);
|
||||
* @endcode
|
||||
*
|
||||
* @param int $code
|
||||
* Usually the HTTP error code that should be used in the HTTP response.
|
||||
* @param string $id
|
||||
* A string that identifies the exception.
|
||||
*
|
||||
* @throws IMuException
|
||||
*/
|
||||
function
|
||||
raise($code, $id)
|
||||
{
|
||||
$exception = new IMuException($id);
|
||||
|
||||
$args = func_get_args();
|
||||
array_shift($args);
|
||||
array_shift($args);
|
||||
$exception->setArgs($args);
|
||||
|
||||
$exception->setCode($code);
|
||||
|
||||
IMuTrace::write(2, 'raising exception %s', $exception);
|
||||
throw $exception;
|
||||
}
|
||||
?>
|
||||
Reference in New Issue
Block a user