summaryrefslogtreecommitdiff
path: root/framework/Web/Services
diff options
context:
space:
mode:
Diffstat (limited to 'framework/Web/Services')
-rw-r--r--framework/Web/Services/TSoapService.php593
1 files changed, 512 insertions, 81 deletions
diff --git a/framework/Web/Services/TSoapService.php b/framework/Web/Services/TSoapService.php
index a2db2e27..b1b04998 100644
--- a/framework/Web/Services/TSoapService.php
+++ b/framework/Web/Services/TSoapService.php
@@ -1,101 +1,532 @@
<?php
/**
- * TSoapService class file
+ * TSoapService and TSoapServer class file
*
* @author Knut Urdalen <knut.urdalen@gmail.com>
- * @link http://www.pradosoft.com
+ * @author Qiang Xue <qiang.xue@gmail.com>
+ * @link http://www.pradosoft.com/
* @copyright Copyright &copy; 2006 PradoSoft
* @license http://www.pradosoft.com/license/
+ * @version $Id: $
* @package System.Web.Services
*/
-//Prado::using('System.Web.Services.TWebService');
-
-require_once dirname(__FILE__).'/../../3rdParty/WsdlGen/WsdlGenerator.php';
-
/**
* TSoapService class
*
- * TSoapService provides
+ * TSoapService processes SOAP requests for a PRADO application.
+ * TSoapService requires PHP SOAP extension to be loaded.
+ *
+ * TSoapService manages a set of SOAP providers. Each SOAP provider
+ * is a class that implements a set of SOAP methods which are exposed
+ * to SOAP clients for remote invocation. TSoapService generates WSDL
+ * automatically for the SOAP providers by default.
+ *
+ * To use TSoapService, configure it in the application specification like following:
+ * <code>
+ * <services>
+ * <service id="soap" class="System.Web.Services.TSoapService">
+ * <soap id="stockquote" provider="MyStockQuote" />
+ * </service>
+ * </services>
+ * </code>
+ *
+ * The above example specifies a single SOAP provider named "stockquote"
+ * whose class is "MyStockQuote". A SOAP client can then obtain the WSDL for
+ * this provider via the following URL:
+ * <code>
+ * http://hostname/path/to/index.php?soap=stockquote.wsdl
+ * </code>
+ *
+ * The WSDL for the provider class "MyStockQuote" is generated based on special
+ * comment tags in the class. In particular, if a class method's comment
+ * contains the keyword "@soapmethod", it is considered to be a SOAP method
+ * and will be exposed to SOAP clients. For example,
+ * <code>
+ * class MyStockQuote {
+ * / **
+ * * @param string $symbol the stock symbol
+ * * @return float the stock price
+ * * @soapmethod
+ * * /
+ * public function getQuote($symbol) {...}
+ * }
+ * </code>
+ *
+ * With the above SOAP provider, a typical SOAP client may call the method "getQuote"
+ * remotely like the following:
+ * <code>
+ * $client=new SoapClient("http://hostname/path/to/index.php?soap=stockquote.wsdl");
+ * echo $client->getQuote("ibm");
+ * </code>
+ *
+ * Each <soap> element in the application specification actually configures
+ * the properties of a SOAP server which defaults to {@link TSoapServer}.
+ * Therefore, any writable property of {@link TSoapServer} may appear as an attribute
+ * in the <soap> element. For example, the "provider" attribute refers to
+ * the {@link TSoapServer::setProvider Provider} property of {@link TSoapServer}.
+ * The following configuration specifies that the SOAP server is persistent within
+ * the user session (that means a MyStockQuote object will be stored in session)
+ * <code>
+ * <services>
+ * <service id="soap" class="System.Web.Services.TSoapService">
+ * <soap id="stockquote" provider="MyStockQuote" SessionPersistent="true" />
+ * </service>
+ * </services>
+ * </code>
+ *
+ * You may also use your own SOAP server class by specifying the "class" attribute of <soap>.
*
* @author Knut Urdalen <knut.urdalen@gmail.com>
+ * @author Qiang Xue <qiang.xue@gmail.com>
+ * @package System.Web.Services
+ * @since 3.1
+ */
+class TSoapService extends TService
+{
+ const DEFAULT_SOAP_SERVER='TSoapServer';
+ const CONFIG_FILE_EXT='.xml';
+ private $_servers=array();
+ private $_configFile=null;
+ private $_wsdlRequest=false;
+ private $_serverID=null;
+
+ /**
+ * Constructor.
+ * Sets default service ID to 'soap'.
+ */
+ public function __construct()
+ {
+ $this->setID('soap');
+ }
+
+ /**
+ * Initializes this module.
+ * This method is required by the IModule interface.
+ * @param TXmlElement configuration for this module, can be null
+ * @throws TConfigurationException if {@link getConfigFile ConfigFile} is invalid.
+ */
+ public function init($config)
+ {
+ if($this->_configFile!==null)
+ {
+ if(is_file($this->_configFile))
+ {
+ $dom=new TXmlDocument;
+ $dom->loadFromFile($this->_configFile);
+ $this->loadConfig($dom);
+ }
+ else
+ throw new TConfigurationException('soapservice_configfile_invalid',$this->_configFile);
+ }
+ $this->loadConfig($config);
+
+ $this->resolveRequest();
+ }
+
+ /**
+ * Resolves the request parameter.
+ * It identifies the server ID and whether the request is for WSDL.
+ * @throws THttpException if the server ID cannot be found
+ * @see getServerID
+ * @see getIsWsdlRequest
+ */
+ protected function resolveRequest()
+ {
+ $serverID=$this->getRequest()->getServiceParameter();
+ if(($pos=strrpos($serverID,'.wsdl'))===strlen($serverID)-5)
+ {
+ $serverID=substr($serverID,0,$pos);
+ $this->_wsdlRequest=true;
+ }
+ else
+ $this->_wsdlRequest=false;
+ $this->_serverID=$serverID;
+ if(!isset($this->_servers[$serverID]))
+ throw new THttpException(400,'soapservice_request_invalid',$serverID);
+ }
+
+ /**
+ * Loads configuration from an XML element
+ * @param TXmlElement configuration node
+ * @throws TConfigurationException if soap server id is not specified or duplicated
+ */
+ private function loadConfig($xml)
+ {
+ foreach($xml->getElementsByTagName('soap') as $serverXML)
+ {
+ $properties=$serverXML->getAttributes();
+ if(($id=$properties->remove('id'))===null)
+ throw new TConfigurationException('soapservice_serverid_required');
+ if(isset($this->_servers[$id]))
+ throw new TConfigurationException('soapservice_serverid_duplicated',$id);
+ $this->_servers[$id]=$properties;
+ }
+ }
+
+ /**
+ * @return string external configuration file. Defaults to null.
+ */
+ public function getConfigFile()
+ {
+ return $this->_configFile;
+ }
+
+ /**
+ * @param string external configuration file in namespace format. The file
+ * must be suffixed with '.xml'.
+ * @throws TInvalidDataValueException if the file is invalid.
+ */
+ public function setConfigFile($value)
+ {
+ if(($this->_configFile=Prado::getPathOfNamespace($value,self::CONFIG_FILE_EXT))===null)
+ throw new TConfigurationException('soapservice_configfile_invalid',$value);
+ }
+
+ /**
+ * Constructs a URL with specified page path and GET parameters.
+ * @param string soap server ID
+ * @param array list of GET parameters, null if no GET parameters required
+ * @param boolean whether to encode the ampersand in URL, defaults to true.
+ * @param boolean whether to encode the GET parameters (their names and values), defaults to true.
+ * @return string URL for the page and GET parameters
+ */
+ public function constructUrl($serverID,$getParams=null,$encodeAmpersand=true,$encodeGetItems=true)
+ {
+ return $this->getRequest()->constructUrl($this->getID(),$serverID,$getParams,$encodeAmpersand,$encodeGetItems);
+ }
+
+ /**
+ * @return boolean whether this is a request for WSDL
+ */
+ public function getIsWsdlRequest()
+ {
+ return $this->_wsdlRequest;
+ }
+
+ /**
+ * @return string the SOAP server ID
+ */
+ public function getServerID()
+ {
+ return $this->_serverID;
+ }
+
+ /**
+ * Creates the requested SOAP server.
+ * The SOAP server is initialized with the property values specified
+ * in the configuration.
+ * @return TSoapServer the SOAP server instance
+ */
+ protected function createServer()
+ {
+ $properties=$this->_servers[$this->_serverID];
+ if(($serverClass=$properties->remove('class'))===null)
+ $serverClass=self::DEFAULT_SOAP_SERVER;
+ Prado::using($serverClass);
+ $className=($pos=strrpos($serverClass,'.'))!==false?substr($serverClass,$pos+1):$serverClass;
+ if($className!==self::DEFAULT_SOAP_SERVER && !is_subclass_of($className,self::DEFAULT_SOAP_SERVER))
+ throw new TConfigurationException('soapservice_server_invalid',$serverClass);
+ $server=new $className;
+ $server->setID($this->_serverID);
+ foreach($properties as $name=>$value)
+ $server->setSubproperty($name,$value);
+ return $server;
+ }
+
+ /**
+ * Runs the service.
+ * If the service parameter ends with '.wsdl', it will serve a WSDL file for
+ * the specified soap server.
+ * Otherwise, it will handle the soap request using the specified server.
+ */
+ public function run()
+ {
+ Prado::trace("Running SOAP service",'System.Web.Services.TSoapService');
+ $server=$this->createServer();
+ if($this->getIsWsdlRequest())
+ {
+ // server WSDL file
+ Prado::trace("Generating WSDL",'System.Web.Services.TSoapService');
+ $this->getResponse()->setContentType('text/xml');
+ $this->getResponse()->write($server->getWsdl());
+ }
+ else
+ {
+ // provide SOAP service
+ Prado::trace("Handling SOAP request",'System.Web.Services.TSoapService');
+ $server->run();
+ }
+ }
+}
+
+
+/**
+ * TSoapServer class.
+ *
+ * TSoapServer is a wrapper of the PHP SoapServer class.
+ * It associates a SOAP provider class to the SoapServer object.
+ * It also manages the URI for the SOAP service and WSDL.
+ *
+ * @author Qiang Xue <qiang.xue@gmail.com>
+ * @version $Id: $
* @package System.Web.Services
* @since 3.1
*/
-class TSoapService extends TService {
-
- private $_class;
-
- private $_server; // reference to the SOAP server
-
- /**
- * Constructor.
- * Sets default service ID to 'soap'.
- */
- public function __construct() {
- $this->setID('soap');
- }
-
- /**
- * Initializes the service.
- * This method is required by IService interface and is invoked by application.
- * @param TXmlElement service configuration
- */
- public function init($config) {
- // nothing to do here
- }
-
- /**
- * Runs the service.
- *
- * This will serve a WSDL-file of the Soap server if 'wsdl' is provided as a key in
- * the URL, else if will serve the Soap server.
- */
- public function run() {
- Prado::trace("Running SOAP service",'System.Web.Services.TSoapService');
-
- $this->setSoapServer($this->getRequest()->getServiceParameter());
- Prado::using($this->getSoapServer()); // Load class
-
- // TODO: Fix protocol and host
- $uri = 'http://'.$_SERVER['HTTP_HOST'].$this->getRequest()->getRequestUri();
-
- //print_r($this->getRequest());
- if($this->getRequest()->itemAt('wsdl') !== null) { // Show WSDL-file
- // TODO: Check WSDL cache
- // Solution: Use Application Mode 'Debug' = no caching, 'Performance' = use cachez
- $uri = str_replace('&wsdl', '', $uri); // throw away the 'wsdl' key (this is a bit dirty)
- $uri = str_replace('wsdl', '', $uri); // throw away the 'wsdl' key (this is a bit dirty)
- $wsdl = WsdlGenerator::generate($this->_class, $uri);
- $this->getResponse()->setContentType('text/xml');
- $this->getResponse()->write($wsdl);
- } else { // Provide service
- // TODO: use TSoapServer
- $this->_server = new SoapServer($uri.'&wsdl');
- $this->_server->setClass($this->getSoapServer());
- $this->_server->handle();
- }
- }
-
- /**
- * @return TSoapServer
- */
- public function getSoapServer() {
- return $this->_class;
- }
-
- /**
- * @param TSoapServer $class
- */
- public function setSoapServer($class) {
- // TODO: ensure $class instanceof TSoapServer
- $this->_class = $class;
- }
-
- public function getPersistence() {
-
- }
-
+class TSoapServer extends TApplicationComponent
+{
+ const WSDL_CACHE_PREFIX='wsdl.';
+
+ private $_id;
+ private $_provider;
+
+ private $_version='';
+ private $_actor='';
+ private $_encoding='';
+ private $_uri='';
+ private $_classMap;
+ private $_persistent=false;
+ private $_wsdlUri='';
+
+ /**
+ * Constructor.
+ * It creates the classmap object.
+ */
+ public function __construct()
+ {
+ $this->_classMap=new TAttributeCollection;
+ }
+
+ /**
+ * @return string the ID of the SOAP server
+ */
+ public function getID()
+ {
+ return $this->_id;
+ }
+
+ /**
+ * @param string the ID of the SOAP server
+ * @throws TInvalidDataValueException if the ID ends with '.wsdl'.
+ */
+ public function setID($id)
+ {
+ if(strrpos($this->_id,'.wsdl')===strlen($this->_id)-5)
+ throw new TInvalidDataValueException('soapserver_id_invalid',$id);
+ $this->_id=$id;
+ }
+
+ /**
+ * Handles the SOAP request.
+ */
+ public function run()
+ {
+ if(($provider=$this->getProvider())!==null)
+ {
+ Prado::using($provider);
+ $providerClass=($pos=strrpos($provider,'.'))!==false?substr($provider,$pos+1):$provider;
+ $server=$this->createServer();
+ $server->setClass($providerClass);
+ if($this->_persistent)
+ $server->setPersistence(SOAP_PERSISTENCE_SESSION);
+ }
+ else
+ $server=$this->createServer();
+ $server->handle();
+ }
+
+ /**
+ * Creates the SoapServer instance.
+ */
+ protected function createServer()
+ {
+ return new SoapServer($this->getWsdlUri(),$this->getOptions());
+ }
+
+ /**
+ * @return array options for creating SoapServer instance
+ */
+ protected function getOptions()
+ {
+ $options=array();
+ if($this->_version==='1.1')
+ $options['soap_version']=SOAP_1_1;
+ else if($this->_version==='1.2')
+ $options['soap_version']=SOAP_1_2;
+ if(!empty($this->_actor))
+ $options['actor']=$this->_actor;
+ if(!empty($this->_encoding))
+ $options['encoding']=$this->_encoding;
+ if(!empty($this->_uri))
+ $options['uri']=$this->_uri;
+ if($this->_classMap->getCount()>0)
+ $options['classmap']=$this->_classMap->toArray();
+ return $options;
+ }
+
+ /**
+ * Returns the WSDL content of the SOAP server.
+ * If {@link getWsdlUri WsdlUri} is set, its content will be returned.
+ * If not, the {@link setProvider Provider} class will be investigated
+ * and the WSDL will be automatically genearted.
+ * @return string the WSDL content of the SOAP server
+ */
+ public function getWsdl()
+ {
+ if($this->_wsdlUri==='')
+ {
+ $provider=$this->getProvider();
+ $providerClass=($pos=strrpos($provider,'.'))!==false?substr($provider,$pos+1):$provider;
+ Prado::using($provider);
+ if($this->getApplication()->getMode()===TApplicationMode::Performance && ($cache=$this->getApplication()->getCache())!==null)
+ {
+ $wsdl=$cache->get(self::WSDL_CACHE_PREFIX.$providerClass);
+ if(is_string($wsdl))
+ return $wsdl;
+ Prado::using('System.3rdParty.WsdlGen.WsdlGenerator');
+ $wsdl=WsdlGenerator::generate($providerClass, $this->getUri());
+ $cache->set(self::WSDL_CACHE_PREFIX.$providerClass,$wsdl);
+ return $wsdl;
+ }
+ else
+ {
+ Prado::using('System.3rdParty.WsdlGen.WsdlGenerator');
+ return WsdlGenerator::generate($providerClass, $this->getUri());
+ }
+ }
+ else
+ return file_get_contents($this->_wsdlUri);
+ }
+
+ /**
+ * @return string the URI for WSDL
+ */
+ public function getWsdlUri()
+ {
+ if($this->_wsdlUri==='')
+ return $this->getRequest()->getBaseUrl().$this->getService()->constructUrl($this->getID().'.wsdl',false);
+ else
+ return $this->_wsdlUri;
+ }
+
+ /**
+ * @param string the URI for WSDL
+ */
+ public function setWsdlUri($value)
+ {
+ $this->_wsdlUri=$value;
+ }
+
+ /**
+ * @return string the URI for the SOAP service
+ */
+ public function getUri()
+ {
+ if($this->_uri==='')
+ return $this->getRequest()->getBaseUrl().$this->getService()->constructUrl($this->getID(),false);
+ else
+ return $this->_uri;
+ }
+
+ /**
+ * @param string the URI for the SOAP service
+ */
+ public function setUri($uri)
+ {
+ $this->_uri=$uri;
+ }
+
+ /**
+ * @return string the SOAP provider class (in namespace format)
+ */
+ public function getProvider()
+ {
+ return $this->_provider;
+ }
+
+ /**
+ * @param string the SOAP provider class (in namespace format)
+ */
+ public function setProvider($provider)
+ {
+ $this->_provider=$provider;
+ }
+
+ /**
+ * @return string SOAP version, defaults to empty (meaning not set).
+ */
+ public function getVersion()
+ {
+ return $this->_version;
+ }
+
+ /**
+ * @param string SOAP version, either '1.1' or '1.2'
+ * @throws TInvalidDataValueException if neither '1.1' nor '1.2'
+ */
+ public function setVersion($value)
+ {
+ if($value==='1.1' || $value==='1.2' || $value==='')
+ $this->_version=$value;
+ else
+ throw new TInvalidDataValueException('soapserver_version_invalid',$value);
+ }
+
+ /**
+ * @return string actor of the SOAP service
+ */
+ public function getActor()
+ {
+ return $this->_actor;
+ }
+
+ /**
+ * @param string actor of the SOAP service
+ */
+ public function setActor($value)
+ {
+ $this->_actor=$value;
+ }
+
+ /**
+ * @return string encoding of the SOAP service
+ */
+ public function getEncoding()
+ {
+ return $this->_encoding;
+ }
+
+ /**
+ * @param string encoding of the SOAP service
+ */
+ public function setEncoding($value)
+ {
+ $this->_encoding=$value;
+ }
+
+ /**
+ * @return boolean whether the SOAP service is persistent within session. Defaults to false.
+ */
+ public function getSessionPersistent()
+ {
+ return $this->_persistent;
+ }
+
+ /**
+ * @param boolean whether the SOAP service is persistent within session.
+ */
+ public function setSessionPersistent($value)
+ {
+ $this->_persistent=TPropertyValue::ensureBoolean($value);
+ }
+
+ /**
+ * @return TAttributeCollection the class map for the SOAP service
+ */
+ public function getClassMap()
+ {
+ return $this->_classMap;
+ }
}
?> \ No newline at end of file