<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>SCA Functions</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="Manual do PHP"
HREF="index.html"><LINK
REL="UP"
TITLE="Referência das Funções"
HREF="funcref.html"><LINK
REL="PREVIOUS"
TITLE="satellite_object_to_string"
HREF="function.satellite-object-to-string.html"><LINK
REL="NEXT"
TITLE="SCA_LocalProxy::createDataObject"
HREF="function.sca-localproxy-createdataobject.html"><META
HTTP-EQUIV="Content-type"
CONTENT="text/html; charset=UTF-8"></HEAD
><BODY
CLASS="reference"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>Manual do PHP</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="function.satellite-object-to-string.html"
ACCESSKEY="P"
>Anterior</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="function.sca-localproxy-createdataobject.html"
ACCESSKEY="N"
>Próxima</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="reference"
><A
NAME="ref.SCA"
></A
><DIV
CLASS="TITLEPAGE"
><H1
CLASS="title"
>CXLII. SCA Functions</H1
><DIV
CLASS="PARTINTRO"
><A
NAME="AEN196888"
></A
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="SCA.intro"
>Introdução</A
></H1
><DIV
CLASS="warning"
><P
></P
><TABLE
CLASS="warning"
BORDER="1"
WIDTH="100%"
><TR
><TD
ALIGN="CENTER"
><B
>Atenção</B
></TD
></TR
><TR
><TD
ALIGN="LEFT"
><P
>Este módulo é
<SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>EXPERIMENTAL</I
></SPAN
>. Isso quer dizer que o comportamento neste módulo ---
incluindo suas funções e seus nomes, e TUDO mais que está documentado
sobre esse módulo --- poderá mudar em futuras versões do PHP, SEM QUALQUER NOTIFICAÇÃO.
Esteja avisado, e use este módulo por sua própria conta e risco.</P
></TD
></TR
></TABLE
></DIV
><P
>
SCA for PHP makes it possible for a PHP programmer to write
reusable components, which can be called in a variety of ways, with an
identical interface and with a minimum of fuss. At present
components can call each other either locally or via Web services,
but in the future it is expected that other ways will be possible. It
provides the programmer with a way of doing this which will look as
natural as possible in PHP.
</P
><P
>
SCA components use phpDocumentor-style (see
http://www.phpdoc.org/) annotations to declare dependencies on
other SCA components or Web services. The SCA for PHP runtime
resolves these dependencies at runtime on behalf of the components,
and thus allows the PHP programmer to focus on the business logic
rather than on locating and obtaining references to dependencies.
</P
><P
>
The SCA for PHP programming model can be extended to support a
number of service types, such as REST and Atompub. However, Web
services (more accurately, WSDL defined, SOAP/HTTP services), are
the only type currently specified.
</P
><P
>
Components also use annotations to define the interface which
they expose as a service. The SCA for PHP runtime will automatically
generate WSDL from these annotations, so that an SCA component is
easily exposed as a web service. These annotations are a natural
extension to those provided by phpDocumentor. Deploying a Web
service can be as simple as placing a PHP component under the document
root of a web server.
</P
><P
>
Components also use annotations to specify data structures
(expressed using XML schema complex types) which are then handled
using Service Data Objects (SDOs).
</P
><P
>
A PHP script which is not an SCA component and which contains no
annotations can use the services of an SCA component. A PHP script or
component can make calls to a web service that is not an SCA component,
but using the same system of calls or annotations to obtain a
reference.
</P
><P
>
First we show a single SCA component, ConvertedStockQuote
which illustrates many of the features of SCA for PHP. It has one
method,
<B
CLASS="function"
>getQuote()</B
>, which given a stock "ticker"
obtains a price quote for that stock, converted to a given currency.
We shall be using this example as a basis for explaining the SCA for PHP
throughout the rest of this document.
</P
><P
> <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN196903"
></A
><P
><B
>Exemplo 1. A sample SCA component </B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php<br /><br /></font><font color="#007700">include </font><font color="#DD0000">"SCA/SCA.php"</font><font color="#007700">;<br /><br /></font><font color="#FF8000">/**<br /> * Calculate a stock price for a given ticker symbol in a given currency.<br /> *<br /> * @service<br /> * @binding.ws<br /> */<br /></font><font color="#007700">class </font><font color="#0000BB">ConvertedStockQuote </font><font color="#007700">{<br /><br /> </font><font color="#FF8000">/**<br /> * The currency exchange rate service to use.<br /> *<br /> * @reference<br /> * @binding.php ../ExchangeRate/ExchangeRate.php<br /> */<br /> </font><font color="#0000BB">public $exchange_rate</font><font color="#007700">;<br /><br /> </font><font color="#FF8000">/**<br /> * The stock quote service to use.<br /> *<br /> * @reference<br /> * @binding.wsdl ../StockQuote/StockQuote.wsdl<br /> */<br /> </font><font color="#0000BB">public $stock_quote</font><font color="#007700">;<br /><br /> </font><font color="#FF8000">/**<br /> * Get a stock quote for a given ticker symbol in a given currency.<br /> *<br /> * @param string $ticker The ticker symbol.<br /> * @param string $currency What currency to convert the value to.<br /> * @return float The stock value is the target currency.<br /> */<br /> </font><font color="#007700">function </font><font color="#0000BB">getQuote</font><font color="#007700">(</font><font color="#0000BB">$ticker</font><font color="#007700">, </font><font color="#0000BB">$currency</font><font color="#007700">)<br /> {<br /> </font><font color="#0000BB">$quote </font><font color="#007700">= </font><font color="#0000BB">$this</font><font color="#007700">-></font><font color="#0000BB">stock_quote</font><font color="#007700">-></font><font color="#0000BB">getQuote</font><font color="#007700">(</font><font color="#0000BB">$ticker</font><font color="#007700">);<br /> </font><font color="#0000BB">$rate </font><font color="#007700">= </font><font color="#0000BB">$this</font><font color="#007700">-></font><font color="#0000BB">exchange_rate</font><font color="#007700">-></font><font color="#0000BB">getRate</font><font color="#007700">(</font><font color="#0000BB">$currency</font><font color="#007700">);<br /> return </font><font color="#0000BB">$rate </font><font color="#007700">* </font><font color="#0000BB">$quote</font><font color="#007700">;<br /> }<br />}<br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
</P
><P
>
In this example, we see that an SCA component is implemented by a
script containing a PHP class and includes
<TT
CLASS="filename"
>SCA.php</TT
>. The class contains a mixture of
business logic and references to other components or services. In
the illustrated
<B
CLASS="function"
>getQuote()</B
> method there is only business
logic, but it relies on the instance variables
<CODE
CLASS="varname"
>$stock_quote</CODE
> and
<CODE
CLASS="varname"
>$exchange_rate</CODE
> having been initialized.
These refer to two other components and will be initialized by the SCA
runtime with proxies for these two services, whenever this
component executes. The annotations for these two services show one
to be a local component, which will be called within the same PHP
runtime, and one to be a remote component which will be called via a
SOAP request. This component also exposes the
<B
CLASS="function"
>getQuote()</B
> method both locally and as a web
service, so it in turn can be called either locally or remotely.
</P
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="SCA.requirements"
>Dependências</A
></H1
><P
>
If you want to use SCA to consume or produce Web services then you
need PHP 5.2.0 or later, built with the soap extension enabled. If you
just want to use local components, and do not wish to use the Web
service bindings, then this version of SCA for PHP will also run with
PHP 5.1.6.
</P
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="SCA.installation"
>Instalação</A
></H1
><P
>
SCA is packaged along with SDO in one combined package on PECL.
See http://www.php.net/sdo#sdo.installation for installing the
SCA_SDO package from PECL. The SCA code must be on the include path of
your PHP installation, for example if it is installed as
/usr/local/lib/php/SCA, the include_path directive must include
/usr/local/lib/php
</P
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="SCA.examples"
>Exemplos</A
></H1
><P
>
The examples in the subsequent sections illustrate the
following aspects of PHP for SCA:
</P
><P
></P
><UL
><LI
><P
> How PHP annotations are used to define PHP classes as SCA
components, and how annotations are used to define the
services.
</P
></LI
><LI
><P
> How an SCA component can be exposed as a Web service
</P
></LI
><LI
><P
> How an SCA component can consume a Web service, whether
provided by another SCA component or by some other service which
knows nothing of SCA
</P
></LI
><LI
><P
> How an SCA component can call another SCA component locally
(within the same process and on the same call stack)
</P
></LI
><LI
><P
> How a client script which is not an SCA component can use the
getService call to obtain a proxy for an SCA component.
</P
></LI
><LI
><P
> How data structures such as Addresses, or Puchase Orders,
are represented as Service Data Objects, and handled.
</P
></LI
><LI
><P
> How SCA components are deployed, and in particular how and
when WSDL is generated for a service.
</P
></LI
><LI
><P
> How parameters are always passed by value (and not by
reference) between components, even when the calls are local.
This ensures that the semantics of a call do not change depending on
the location of a component.
</P
></LI
><LI
><P
> How positional parameters to a service are supported, even
when the underlying WSDL is document literal wrapped, and
naturally supports only named parameters.
</P
></LI
><LI
><P
> How business and runtime exceptions are handled.
</P
></LI
></UL
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="SCA.examples.structure"
>The structure of a Service Component</A
></H2
><P
>
A service component is implemented by a class. To identify it
as a service component, it contains an @service annotation. The SCA
runtime will use the file name of the script to determine the
component name, by convention. The class and script file must
therefore share the same name.
</P
><P
>
PHP SCA components always expose a service, and there is no way
for a component to be invoked other than to be called as a result of a
Web service request, or called directly from another component or
from a script. For this reason a valid PHP SCA component will always
contain an @service annotation and at least one public method.
</P
><P
>
Each SCA Component requires that the SCA.php script is
included. As well as containing the definition of the SCA class,
this script contains executable PHP code that will run whenever the
script is called, and which will be responsible for making the
component behave as needed.
</P
><DIV
CLASS="caution"
><P
></P
><TABLE
CLASS="caution"
BORDER="1"
WIDTH="100%"
><TR
><TD
ALIGN="CENTER"
><B
>Cuidado</B
></TD
></TR
><TR
><TD
ALIGN="LEFT"
><P
>
It is very important that if your file contains other
includes, they come before the include for SCA.php. If there are
includes after the include for SCA.php, they will not have been
processed when the SCA runtime runs your class.
</P
></TD
></TR
></TABLE
></DIV
><P
>
The example below illustrates this overall structure
</P
><P
> <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN196951"
></A
><P
><B
>Exemplo 2. The structure of an SCA for PHP component </B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php<br /><br /></font><font color="#FF8000">// any includes<br /><br /></font><font color="#007700">include </font><font color="#DD0000">"SCA/SCA.php<br /><br />/**<br /> * @service<br /> */<br /><br />class ConvertedStockQuote </font><font color="#007700">{</font><font color="#DD0000"><br /><br /> // instance variables, business logic, including at least one public method<br /><br /></font><font color="#007700">}</font><font color="#DD0000"><br />?></font>
</font>
</code></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
</P
></DIV
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="SCA.examples.proxies"
>Obtaining a proxy for another Service Component</A
></H2
><P
> One SCA component can call the service provided by another SCA
component. The service a component provides is made up of all of its
public methods. SCA for PHP currently provides two ways for one
component to call another: either locally (i.e. within the same PHP
run-time, and on the same call stack) or remotely if the called
component exposes a Web service binding.
</P
><P
> In order for one component to call another, the calling
component needs a proxy for the called component. This proxy is
usually provided as an instance variable in the calling component,
though proxies can also be obtained with the SCA::getService()
call, as we shall see later. When a component is constructed,
proxies are constructed for any instance variable which refer to
another component, and these proxies are "injected" into the
instance variables. Proxies are always used, whether the
component is local or remote, in order to provide identical calling
behavior between remote and local calls (for example, local calls
are made to always pass data by-value). The proxies know how to
locate the required component and to pass the calls made on to them.
</P
><P
> Instance variables which are intended to hold proxies for
services are indicated by the two PHPDocumentor-style
annotations, @reference and @binding. Both annotations are
placed in the documentation section for a class instance variable,
as shown by the code below.
</P
><P
> The @reference annotation before an instance variable
indicates that that instance variable is to be initialized with a
proxy to a component.
</P
><P
>
The @binding annotation has two forms @binding.php and
@@binding.ws, and indicates that the proxy is either for a local
component or for a Web service respectively. For both @binding.php
and @binding.ws, the annotation gives a target URI.
</P
><P
> At the moment, with the annotation-based method of
specifying dependencies, the only way to alter the intended target
of a reference is to alter the annotation within the component.
</P
><P
> In our ConvertedStockQuote example, the
<CODE
CLASS="varname"
>$exchange_rate</CODE
> instance variable will be
initialized with a proxy to the local ExchangeRate component
whenever an instance of the ConvertedStockQuote is constructed.
</P
><P
> <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN196965"
></A
><P
><B
>Exemplo 3. Obtaining a proxy for a local PHP class </B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php <br /> </font><font color="#FF8000">/**<br /> * The currency exchange rate service to use.<br /> *<br /> * @reference<br /> * @binding.php ../ExchangeRate/ExchangeRate.php<br /> */<br /> </font><font color="#0000BB">public $exchange_rate</font><font color="#007700">;<br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
</P
><P
>
For @binding.php, the URI identifies the location of the
script containing the implementation of the component. The
component will be called locally. The service provided is the set of
public methods of the component. The URI must be a simple pathname,
either absolute or relative. The component will be loaded with the
PHP include directive, after testing to see if it is already loaded
with
<A
HREF="function.class-exists.html"
><B
CLASS="function"
>class_exists()</B
></A
>. If the URI is a relative
path, it is resolved relative to the component containing the
annotation. Note that this is different from the normal PHP
behaviour where scripts would be looked for along the PHP
include_path, This is intended to provide some
location-independence for cross-component references.
</P
><P
>
If this ExchangeRate service were remote and to be called as a
Web service, only the @binding line changes. Instead of giving the
location of a PHP class, it gives the location of the WSDL describing
the web service. In our example component, this is illustrated by
the second reference:
</P
><P
> <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN196972"
></A
><P
><B
>Exemplo 4. Obtaining a proxy for a web service </B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php<br /></font><font color="#FF8000">/**<br /> * The stock quote service to use.<br /> *<br /> * @reference<br /> * @binding.wsdl ../StockQuote/StockQuote.wsdl<br /> */<br /> </font><font color="#0000BB">public $stock_quote</font><font color="#007700">;<br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
</P
><P
>
The StockQuote component will be called via a Web service
request. In this case the URI for the WSDL can be a simple pathname, or
may contain a PHP wrapper and begin, for example, with
<CODE
CLASS="varname"
>file://</CODE
> or
<CODE
CLASS="varname"
>http://</CODE
>. In the event that it is a simple
pathname, it can be absolute or relative, and if relative will be
resolved relative to the component containing the annotation.
Note that this is like the behaviour for @binding.php, and
different from the normal PHP behaviour where the file would be
looked for relative to the PHP current working directory, which
would usually be the location of the first script to be called. This
behaviour is intended to give consistency across the different
bindings and to provide some location-independence for
references between components.
</P
></DIV
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="SCA.examples.calling"
>Calling another Service Component</A
></H2
><P
> The ConvertedStockQuote example also calls the proxies for
the two components to which it refers.
</P
><P
> <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN196982"
></A
><P
><B
>Exemplo 5. Calling services </B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php<br />$quote </font><font color="#007700">= </font><font color="#0000BB">$this</font><font color="#007700">-></font><font color="#0000BB">stock_quote</font><font color="#007700">-></font><font color="#0000BB">getQuote</font><font color="#007700">(</font><font color="#0000BB">$ticker</font><font color="#007700">);<br /></font><font color="#0000BB">$rate </font><font color="#007700">= </font><font color="#0000BB">$this</font><font color="#007700">-></font><font color="#0000BB">exchange_rate</font><font color="#007700">-></font><font color="#0000BB">getRate</font><font color="#007700">(</font><font color="#0000BB">$currency</font><font color="#007700">);<br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
</P
><P
>
The call to the StockQuote service is a call to a local service;
the call to the ExchangeRate service is a call to a remote service.
Note that the way the call is made looks the same regardless of
whether the call is to a local service or a remote one.
</P
><P
>
The proxies which have been injected ensure that the way calls
to components look and behave are the same way regardless of whether
they are to a local or remote service, so that components are not
sensitive to whether a call is to a local or a remote service. For
example, the proxy for a local service takes copies of the arguments
and passes only those copies, to ensure that calls are made to be
pass-by-value, as they would be for a remote call. Also, the proxy
for a remote service takes the arguments from a positional
parameter list and ensures they are packaged properly in a SOAP
request and converted back to a positional parameter list at the far
end.
</P
><P
>
In the example above, the
<CODE
CLASS="varname"
>$ticker</CODE
> and
<CODE
CLASS="varname"
>$currency</CODE
> are clearly PHP scalar types.
Components can pass the PHP scalar types string, integer, float and
boolean, but data structures on service calls are always passed as
Service Data Objects (SDOs). A later section describes how a
component can create an SDO to pass on a local or Web service call, or
how a component can create an SDO to return. The PHP SDO project
documentation describes how to work with the SDO APIs (see
<A
HREF="ref.sdo.html"
>the SDO pages</A
>.
</P
></DIV
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="SCA.examples.nonSCAscript"
>Locating and calling services from a script which is not an
SCA Component</A
></H2
><P
>
SCA components obtain proxies for other components or
services as instance variables annotated with @reference, but
this is not possible for a script that is not itself also a component.
A client script which is not a component must use the
<B
CLASS="function"
>SCA::getService()</B
> static method to obtain a
proxy for a service, whether local or remote. The
<B
CLASS="function"
>getService()</B
> method takes a URI as the
argument. Typically this is the location of a local PHP script
containing a component, or of a wsdl file, and is used in exactly the
same way as the targets of the @binding annotations described in the
previous section: that is, relative URIs are resolved against the
location of the client script and not against the PHP include_path
or current working directory.
</P
><P
>
For example, a script that needed to obtain proxies for the
ExchangeRate and StockQuote services but was not a component would
use the
<B
CLASS="function"
>getService()</B
> method as follows:
</P
><P
> <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN196999"
></A
><P
><B
>Exemplo 6. Obtaining a proxy using getService </B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php<br />$exchange_rate </font><font color="#007700">= </font><font color="#0000BB">SCA</font><font color="#007700">::</font><font color="#0000BB">getService</font><font color="#007700">(</font><font color="#DD0000">'../ExchangeRate/ExchangeRate.php'</font><font color="#007700">);<br /></font><font color="#0000BB">$stock_quote </font><font color="#007700">= </font><font color="#0000BB">SCA</font><font color="#007700">::</font><font color="#0000BB">getService</font><font color="#007700">(</font><font color="#DD0000">'../StockQuote/StockQuote.wsdl'</font><font color="#007700">);<br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
</P
><P
> Methods on services can then be called on the returned proxy,
just as they can in a component.
</P
><P
> <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN197004"
></A
><P
><B
>Exemplo 7. Making calls on the proxy </B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php<br />$quote </font><font color="#007700">= </font><font color="#0000BB">$stock_quote</font><font color="#007700">-></font><font color="#0000BB">getQuote</font><font color="#007700">(</font><font color="#0000BB">$ticker</font><font color="#007700">);<br /></font><font color="#0000BB">$rate </font><font color="#007700">= </font><font color="#0000BB">$exchange_rate</font><font color="#007700">-></font><font color="#0000BB">getRate</font><font color="#007700">(</font><font color="#0000BB">$currency</font><font color="#007700">);<br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
</P
></DIV
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="AEN197007"
>Exposing a Service Component as a Web service</A
></H2
><P
>
SCA for PHP can generate WSDL from the annotations within a
service component, so that it can be easily deployed and exposed as a
Web service. To provide SCA with the information it needs to
generate the WSDL, it is necessary to add the annotation
@binding.ws under the @service annotation and to specify the
parameters and return values of the methods using the @param and
@return annotations. These annotations will be read when WSDL is
generated, and the order and types of the parameters determine the
contents of the
<schema> section of the WSDL.
</P
><P
>
SCA for PHP always generates document/literal wrapped WSDL
for components that are exposing a Web service. Note that this does
not stop components from consuming Web services which are not SCA
components and which are documented with WSDL written in a
different style.
</P
><P
>
The scalar types which can be used in the @param annotation are
the four common PHP scalar types: boolean, integer, float and
string. These are simply mapped to the XML schema types of the same
name in the WSDL. The example below, which is a trivial
implementation of the StockQuote service that the
ConvertedStockQuote component calls, illustrates string and
float types.
</P
><P
> <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN197013"
></A
><P
><B
>Exemplo 8. StockQuote Service </B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php<br /><br /></font><font color="#007700">include </font><font color="#DD0000">"SCA/SCA.php"</font><font color="#007700">;<br /><br /></font><font color="#FF8000">/**<br /> * Scaffold implementation for a remote StockQuote Web service.<br /> *<br /> * @service<br /> * @binding.ws<br /> *<br /> */<br /></font><font color="#007700">class </font><font color="#0000BB">StockQuote </font><font color="#007700">{<br /><br /> </font><font color="#FF8000">/**<br /> * Get a stock quote for a given ticker symbol.<br /> *<br /> * @param string $ticker The ticker symbol.<br /> * @return float The stock quote.<br /> */<br /> </font><font color="#007700">function </font><font color="#0000BB">getQuote</font><font color="#007700">(</font><font color="#0000BB">$ticker</font><font color="#007700">) {<br /> return </font><font color="#0000BB">80.9</font><font color="#007700">;<br /> }<br />}<br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
</P
><P
>
WSDL much like the following (though with a service location
other than 'localhost', probably) would be generated from this
service:
</P
><P
> <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN197018"
></A
><P
><B
>Exemplo 9. Generated WSDL </B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="xml"
><?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/" xsi:type="tDefinitions"
xmlns:tns2="http://StockQuote" xmlns:tns="http://schemas.xmlsoap.org/wsdl/"
xmlns:tns3="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" targetNamespace="http://StockQuote">
<types>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://StockQuote">
<xs:element name="getQuote">
<xs:complexType>
<xs:sequence>
<xs:element name="ticker" type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="getQuoteResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="getQuoteReturn" type="xs:float"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
</types>
<message name="getQuoteRequest">
<part name="getQuoteRequest" element="tns2:getQuote"/>
</message>
<message name="getQuoteResponse">
<part name="return" element="tns2:getQuoteResponse"/>
</message>
<portType name="StockQuotePortType">
<operation name="getQuote">
<input message="tns2:getQuoteRequest"/>
<output message="tns2:getQuoteResponse"/>
</operation>
</portType>
<binding name="StockQuoteBinding" type="tns2:StockQuotePortType">
<operation name="getQuote">
<input>
<tns3:body xsi:type="tBody" use="literal"/>
</input>
<output>
<tns3:body xsi:type="tBody" use="literal"/>
</output>
<tns3:operation xsi:type="tOperation" soapAction=""/>
</operation>
<tns3:binding xsi:type="tBinding" transport="http://schemas.xmlsoap.org/soap/http" style="document"/>
</binding>
<service name="StockQuoteService">
<port name="StockQuotePort" binding="tns2:StockQuoteBinding">
<tns3:address xsi:type="tAddress" location="http://localhost/StockQuote/StockQuote.php"/>
</port>
</service>
</definitions>
<!-- this line identifies this file as WSDL generated by SCA for PHP. Do not remove --></PRE
></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
</P
></DIV
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="SCA.examples.deploy"
>Deploying an SCA component</A
></H2
><P
>
There are no special steps needed to deploy a PHP SCA
component. It is sufficient to place the component PHP script in its
proper place under the web server document root, just like any other
PHP script. It is the
<B
CLASS="function"
>SCA::initComponent()</B
> executable line
within each component that will be executed whenever the script is
called, and which will be responsible for making the component
respond appropriately to Web service calls, local calls, or
requests for WSDL.
</P
></DIV
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="SCA.examples.obtaining-wsdl"
>Obtaining the WSDL for an SCA component offering a Service as
a Web service</A
></H2
><P
>
SCA components that expose a Web service interface (i.e. have
an @binding.ws annotation) will return their WSDL definition in
response to an HTTP request with a get parameter of "wsdl". The usual
way to obtain this is with "?wsdl" on the end of a URL. The example
below uses
<A
HREF="function.file-get-contents.html"
><B
CLASS="function"
>file_get_contents()</B
></A
> to obtain WSDL from a
service and writes it to a temporary file before then obtaining a
proxy for the service in the usual way. You could of course also
obtain the WSDL in a browser, or by some other means, and save the file
yourself.
</P
><P
> <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN197030"
></A
><P
><B
>Exemplo 10. Generated WSDL </B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="xml"
><?php
$wsdl = file_get_contents('http://www.example.com/Services/Example.php?wsdl');
file_put_contents("service.wsdl",$wsdl); //write the wsdl to a file
$service = SCA::getService('service.wsdl');
?></PRE
></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
</P
><P
> NOTE: If the wsdl requires imported xsds, these will need to be
fetched separately.
</P
></DIV
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="SCA.examples.understanding-wsdl"
>Understanding how the WSDL is generated</A
></H2
><P
>
SCA for PHP generates WSDL for components which contain an
@binding.ws annotation after the @service annotation. To
generate WSDL, the SCA runtime reflects on the component and
examines the @param and @return annotations for each public
method, as well as any @types annotations within the component. The
information from the @param and @return annotations is used to
build the <types> section of the WSDL. Any @types
annotations which specify a separate schema file will result in an
<import> element for that schema within the WSDL.
</P
><DIV
CLASS="section"
><H3
CLASS="section"
><A
NAME="SCA.examples.understanding-wsdl.location"
>Location attribute of the <service> element</A
></H3
><P
>
At the bottom of the WSDL is the <service> element
which uses the location attribute to identify the URL of the
service. For example this might look as follows:
</P
><P
> <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN197041"
></A
><P
><B
>Exemplo 11. location attribute </B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="xml"
><service name="ConvertedStockQuote"
...
location="http://localhost/ConvertedStockQuote/ConvertedStockQuote.php"/></PRE
></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
</P
><P
> Note that this location is relative to the document root of
the web server, and cannot be worked out in advance. It can only be
worked out once the component is in its proper place under a running
web server, when the hostname and port can be known and placed in the
WSDL. Detail from the URL that requests the WSDL is used, so for
example if the WSDL is generated in response to a request to
http://www.example.com:1111/ConvertedStockQuote/ConvertedStockQuote.php?wsdl,
a location of
http://www.example.com:1111/ConvertedStockQuote/ConvertedStockQuote.php
is what will be inserted into the location attribute in the WSDL.
</P
></DIV
><DIV
CLASS="section"
><H3
CLASS="section"
><A
NAME="SCA.examples.understanding-wsdl.positional-parameters"
>Document/literal wrapped WSDL and positional
parameters</A
></H3
><P
>
SCA for PHP generates WSDL in the document/literal wrapped
style. This style encloses the parameters and return types of a
method in 'wrappers' which are named after the corresponding
method. The <types> element at the top of the WSDL defines
each of these wrappers. If we consider the
<B
CLASS="function"
>getQuote()</B
> method of the
ConvertedStockQuote example:
</P
><P
> <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN197050"
></A
><P
><B
>Exemplo 12. method with two arguments </B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php<br /> </font><font color="#FF8000">/**<br /> * Get a stock quote for a given ticker symbol in a given currency.<br /> *<br /> * @param string $ticker The ticker symbol.<br /> * @param string $currency What currency to convert the value to.<br /> * @return float The stock value is the target currency.<br /> */<br /> </font><font color="#007700">function </font><font color="#0000BB">getQuote</font><font color="#007700">(</font><font color="#0000BB">$ticker</font><font color="#007700">, </font><font color="#0000BB">$currency</font><font color="#007700">)<br /> {<br /> </font><font color="#0000BB">$quote </font><font color="#007700">= </font><font color="#0000BB">$this</font><font color="#007700">-></font><font color="#0000BB">stock_quote</font><font color="#007700">-></font><font color="#0000BB">getQuote</font><font color="#007700">(</font><font color="#0000BB">$ticker</font><font color="#007700">);<br /> </font><font color="#0000BB">$rate </font><font color="#007700">= </font><font color="#0000BB">$this</font><font color="#007700">-></font><font color="#0000BB">exchange_rate</font><font color="#007700">-></font><font color="#0000BB">getRate</font><font color="#007700">(</font><font color="#0000BB">$currency</font><font color="#007700">);<br /> return </font><font color="#0000BB">$rate </font><font color="#007700">* </font><font color="#0000BB">$quote</font><font color="#007700">;<br /> }<br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
</P
><P
> The WSDL generated to define this method will name both the
method and the parameters, and give an XML schema type for the
parameters. The types section of the WSDL looks like this:
</P
><P
> <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN197055"
></A
><P
><B
>Exemplo 13. types section illustrating named parameters </B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="xml"
><types>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://ConvertedStockQuote">
<xs:element name="getQuote">
<xs:complexType>
<xs:sequence>
<xs:element name="ticker" type="xs:string"/>
<xs:element name="currency" type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="getQuoteResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="getQuoteReturn" type="xs:float"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
</types></PRE
></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
</P
><P
> The SCA run-time has special processing to handle how
positional parameter lists in the interface are converted to XML
containing named parameters in the soap request, and then back to
positional parameter lists again. To see why this matters,
consider how a PHP script which used a different interface to make a
SOAP call would need to construct the parameter list. A PHP script
using the PHP SoapClient, for example, would need to pass the
SoapClient a single parameter giving the values for "ticker" and
"currency", perhaps as an associative array. To insist that SCA
components construct parameter lists to make Web service calls in
this way would be to make local and remote calls look different, so a
different approach is needed.
</P
><P
> When SCA generates WSDL for an SCA component it includes a
comment in the WSDL which marks that WSDL as being the interface for
an SCA component. In this case, when one SCA component calls
another through a Web service, the SCA runtime on the calling end
takes the positional parameter list from the call and assigns the
values one by one to the named elements in the soap message. For
example a call to the
<B
CLASS="function"
>getQuote()</B
> method defined above that
passes the values 'IBM' and 'USD' and looks like this:
</P
><P
> <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
$quote = $remote_service->getQuote('IBM','USD');</font>
</code></TD
></TR
></TABLE
>
</P
><P
> will result in a soap message containing the
following:
</P
><P
> <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<getQuote><br /> <ticker>IBM</ticker><br /> <currency>USD</currency><br /></getQuote></font>
</code></TD
></TR
></TABLE
>
</P
><P
> On the service-providing end, the SCA run-time takes the
parameters one by one from the soap message and forms a positional
parameter list from them, re-forming the argument list
('IBM','USD').
</P
><DIV
CLASS="caution"
><P
></P
><TABLE
CLASS="caution"
BORDER="1"
WIDTH="100%"
><TR
><TD
ALIGN="CENTER"
><B
>Cuidado</B
></TD
></TR
><TR
><TD
ALIGN="LEFT"
><P
>
At both ends the SCA runtime relies on the order in which the
parameters appear in the soap message being the same as that in the
target method's parameter list. This is ultimately determined
by the order of the @param annotations: this determines the order
in which the parameters appear in the WSDL and thereby the order in
which they appear in the soap message. Therefore it is essential
that the order of the @param annotations matches that of the
parameters in the method's parameter list.
</P
></TD
></TR
></TABLE
></DIV
></DIV
></DIV
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="SCA.examples.structures"
>Working with Data Structures</A
></H2
><P
> SCA components can pass and return the four PHP scalar types
boolean, integer, real and string, but to pass or return data
structures, SCA components use Service Data Objects (SDOs). SDOs
are described in much more detail in
<A
HREF="ref.sdo.html"
>the SDO pages</A
> of this manual.
Readers familiar with SDOs will know that they are suitable for
representing the sort of structured and semi-structured data that
is frequently modeled in XML, and that they serialize very
naturally for passing between remote components, or in Web
services. SDOs are presently the only supported way to pass and
return data structures. It is not possible to pass or return PHP
objects, or PHP arrays.
</P
><P
>
The SCA runtime always assures data is passed by-value, even
for local calls. To do this, the SCA runtime copies any SDOs in the
parameter list before passing them on, just as it does for scalar
types.
</P
><DIV
CLASS="section"
><H3
CLASS="section"
><A
NAME="AEN197074"
>How data structures are defined to SCA components</A
></H3
><P
>
Currently the only mechanism for specifying the location of
a data structure definition is by specifying the types in an XML
schema file. However, in the future it may be possible to define
types in other ways, such as based on PHP classes or interfaces, or
based on definitions expressed as associative arrays.
</P
><P
> To illustrate the use of SDOs we introduce a new component.
The PortfolioMangement service below returns an SDO
representing a stock portfolio for a given customer.
</P
><P
> <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN197079"
></A
><P
><B
>Exemplo 14. A Component that uses Data Structures</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php<br /><br /></font><font color="#007700">include </font><font color="#DD0000">'SCA/SCA.php'</font><font color="#007700">;<br /><br /></font><font color="#FF8000">/**<br /> * Manage the portfolio for a customer.<br /> *<br /> * @service<br /> * @binding.ws<br /> *<br /> * @types http://www.example.org/Portfolio PortfolioTypes.xsd<br /> *<br /> */<br /></font><font color="#007700">class </font><font color="#0000BB">PortfolioManagement </font><font color="#007700">{<br /><br /> </font><font color="#FF8000">/**<br /> * Get the stock portfolio for a given customer.<br /> *<br /> * @param integer $customer_id The id for the customer<br /> * @return Portfolio http://www.example.org/Portfolio The stock portfolio (symbols and quantities)<br /> */<br /> </font><font color="#007700">function </font><font color="#0000BB">getPortfolio</font><font color="#007700">(</font><font color="#0000BB">$customer_id</font><font color="#007700">) {<br /> </font><font color="#FF8000">// Pretend we just got this from a database<br /> </font><font color="#0000BB">$portfolio </font><font color="#007700">= </font><font color="#0000BB">SCA</font><font color="#007700">::</font><font color="#0000BB">createDataObject</font><font color="#007700">(</font><font color="#DD0000">'http://www.example.org/Portfolio'</font><font color="#007700">, </font><font color="#DD0000">'Portfolio'</font><font color="#007700">);<br /> </font><font color="#0000BB">$holding </font><font color="#007700">= </font><font color="#0000BB">$portfolio</font><font color="#007700">-></font><font color="#0000BB">createDataObject</font><font color="#007700">(</font><font color="#DD0000">'holding'</font><font color="#007700">);<br /> </font><font color="#0000BB">$holding</font><font color="#007700">-></font><font color="#0000BB">ticker </font><font color="#007700">= </font><font color="#DD0000">'AAPL'</font><font color="#007700">;<br /> </font><font color="#0000BB">$holding</font><font color="#007700">-></font><font color="#0000BB">number </font><font color="#007700">= </font><font color="#0000BB">100.5</font><font color="#007700">;<br /> </font><font color="#0000BB">$holding </font><font color="#007700">= </font><font color="#0000BB">$portfolio</font><font color="#007700">-></font><font color="#0000BB">createDataObject</font><font color="#007700">(</font><font color="#DD0000">'holding'</font><font color="#007700">);<br /> </font><font color="#0000BB">$holding</font><font color="#007700">-></font><font color="#0000BB">ticker </font><font color="#007700">= </font><font color="#DD0000">'INTL'</font><font color="#007700">;<br /> </font><font color="#0000BB">$holding</font><font color="#007700">-></font><font color="#0000BB">number </font><font color="#007700">= </font><font color="#0000BB">100.5</font><font color="#007700">;<br /> </font><font color="#0000BB">$holding </font><font color="#007700">= </font><font color="#0000BB">$portfolio</font><font color="#007700">-></font><font color="#0000BB">createDataObject</font><font color="#007700">(</font><font color="#DD0000">'holding'</font><font color="#007700">);<br /> </font><font color="#0000BB">$holding</font><font color="#007700">-></font><font color="#0000BB">ticker </font><font color="#007700">= </font><font color="#DD0000">'IBM'</font><font color="#007700">;<br /> </font><font color="#0000BB">$holding</font><font color="#007700">-></font><font color="#0000BB">number </font><font color="#007700">= </font><font color="#0000BB">100.5</font><font color="#007700">;<br /> return </font><font color="#0000BB">$portfolio</font><font color="#007700">;<br /> }<br /><br />}<br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
</P
><P
> The @types annotation:
</P
><P
> <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php<br /></font><font color="#007700">@</font><font color="#0000BB">types http</font><font color="#007700">:</font><font color="#FF8000">//www.example.org/Portfolio PortfolioTypes.xsd<br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
>
</P
><P
> indicates that types in the namespace
http://www.example.org/Portfolio will be found in the schema
file located by the URI PortfolioTypes.xsd. The generated WSDL
would reproduce this information with an import statement as
follows:
</P
><P
> <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="xml"
><xs:import schemaLocation="PortfolioTypes.xsd"
namespace="http://www.example.org/Portfolio"/></PRE
></TD
></TR
></TABLE
>
</P
><P
> so the URI, absolute or relative, must be one that can be
resolved when included in the schemaLocation attribute.
</P
></DIV
><DIV
CLASS="section"
><H3
CLASS="section"
><A
NAME="AEN197089"
>Creating SDOs</A
></H3
><P
> Readers familiar with SDOs will know that they are always
created according to a description of the permitted structure
(sometimes referred to as the 'schema' or 'model') and that,
rather than creating them directly using 'new', some form of data
factory is needed. Often, an existing data object can be used as the
data factory, but sometimes, and especially in order to get the
first data object, something else must act as the data factory.
</P
><P
> In SCA, either the SCA runtime class or the proxies for
services, whether local or remote, can act as the data factories
for SDOs. The choice of which to use, and when, is described in the
next two sections.
</P
><P
>
We switch to a new example in order to illustrate the creation
of SDOs, both to pass to a service, and to be returned from a service.
</P
></DIV
><DIV
CLASS="section"
><H3
CLASS="section"
><A
NAME="AEN197094"
>Creating an SDO to pass to a service</A
></H3
><P
> A caller of a service which requires a data structure to be
passed in to it uses the proxy to the service as the data factory for
the corresponding SDOs. For example, suppose a component makes
use of a proxy for a service provided by a local AddressBook
component.
</P
><P
> <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php<br /></font><font color="#FF8000">/**<br /> * @reference<br /> * @binding.local AddressBook.php<br /> */<br /></font><font color="#0000BB">$address_book</font><font color="#007700">;<br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
>
</P
><P
>
The AddressBook component that it wishes to call is defined
as follows:
</P
><P
> <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php<br /></font><font color="#FF8000">/**<br />* @service<br />* @binding.ws<br />* @types http://addressbook ../AddressBook/AddressBook.xsd<br />*/<br /></font><font color="#007700">class </font><font color="#0000BB">AddressBook </font><font color="#007700">{<br /><br /> </font><font color="#FF8000">/**<br /> * @param personType $person http://addressbook (a person object)<br /> * @return addressType http://addressbook (the address object for the person object)<br /> */<br /> </font><font color="#007700">function </font><font color="#0000BB">lookupAddress</font><font color="#007700">(</font><font color="#0000BB">$person</font><font color="#007700">) {<br /> ...<br /> }<br />}<br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
>
</P
><P
>
The AddressBook component provides a service method called
<B
CLASS="function"
>lookupAddress()</B
> which uses types from the
http://addressbook namespace. The lookupAddress method takes a
personType data structure and returns an addressType. Both types
are defined in the schema file addressbook.xsd.
</P
><P
>
Once the component that wishes to use the AddressBook
component has been constructed, so that the
<CODE
CLASS="varname"
>$address_book</CODE
> instance variable contains
a proxy for the service, the calling component can use the proxy in
<CODE
CLASS="varname"
>$address_book</CODE
> to create the person SDO, as
shown below:
</P
><P
> <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php<br />$william_shakespeare </font><font color="#007700">= </font><font color="#0000BB">$address_book</font><font color="#007700">-></font><font color="#0000BB">createDataObject</font><font color="#007700">(</font><font color="#DD0000">'http://addressbook'</font><font color="#007700">,</font><font color="#DD0000">'personType'</font><font color="#007700">);<br /></font><font color="#0000BB">$william_shakespeare </font><font color="#007700">-></font><font color="#0000BB">name </font><font color="#007700">= </font><font color="#DD0000">"William Shakespeare"</font><font color="#007700">;<br /></font><font color="#0000BB">$address </font><font color="#007700">= </font><font color="#0000BB">$address_book</font><font color="#007700">-></font><font color="#0000BB">lookupAddress</font><font color="#007700">(</font><font color="#0000BB">$william_shakespeare</font><font color="#007700">);<br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
>
</P
><P
>
Note, the use of the proxy as the means to create the SDO is not
limited to SCA components. If a service is being called from a
general PHP script, and the proxy was obtained with
<B
CLASS="function"
>getService()</B
> then the same approach is
used.
</P
><P
> <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php<br />$address_book </font><font color="#007700">= </font><font color="#0000BB">SCA</font><font color="#007700">::</font><font color="#0000BB">getService</font><font color="#007700">(</font><font color="#DD0000">'AddressBook.php'</font><font color="#007700">);<br /></font><font color="#0000BB">$william_shakespeare </font><font color="#007700">= </font><font color="#0000BB">$address_book</font><font color="#007700">-></font><font color="#0000BB">createDataObject</font><font color="#007700">(</font><font color="#DD0000">'http://addressbook'</font><font color="#007700">,</font><font color="#DD0000">'personType'</font><font color="#007700">);<br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
>
</P
></DIV
><DIV
CLASS="section"
><H3
CLASS="section"
><A
NAME="AEN197113"
>Creating an SDO to return from a component</A
></H3
><P
>
A component that needs to create a data object for return to a
caller will not have a proxy to use as a data object, In this case it
uses the
<B
CLASS="function"
>createDataObject()</B
> static method on
<TT
CLASS="filename"
>SCA.php</TT
>. Hence if the AddressBook
component described above needed to create an object of type
<B
CLASS="classname"
>addressType</B
> within the namespace
http://addressbook, it might do so as follows:
</P
><P
> <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php<br />$address </font><font color="#007700">= </font><font color="#0000BB">SCA</font><font color="#007700">::</font><font color="#0000BB">createDataObject</font><font color="#007700">(</font><font color="#DD0000">'http://addressbook'</font><font color="#007700">,</font><font color="#DD0000">'addressType'</font><font color="#007700">);<br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
>
</P
></DIV
></DIV
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="SCA.examples.errorhandling"
>Error handling</A
></H2
><P
>
This section describes how errors are handled. There are two
types of errors:
</P
><P
></P
><UL
><LI
><P
>
SCA runtime exceptions are those that signal problems in
the management of the execution of components, and in the
interaction with remote services. These might occur due to
network or configuration problems.
</P
></LI
><LI
><P
>
Business exceptions are those that are defined by the
programmer. They extend the PHP Exception class, and are thrown
and caught deliberately as part of the business logic.
</P
></LI
></UL
><DIV
CLASS="section"
><H3
CLASS="section"
><A
NAME="AEN197129"
>Handling of Runtime exceptions</A
></H3
><P
>
There are two types of SCA runtime exception:
</P
><P
></P
><UL
><LI
><P
>
SCA_RuntimeException - signals a problem found by or
perhaps occurring within the SCA runtime. This can be thrown for
a variety of reasons, many of which can occur regardless of
whether a connection is being made to a local or a remote service:
an error in one of the annotations within a component, a missing
WSDL or php file, and so on. In the case of Web services, an
SCA_RuntimeException can also be thrown if a SoapFault is
received from a remote Web service and the fault code in the
SoapFault indicates that a retry is unlikely to be successful.
</P
></LI
><LI
><P
>
SCA_ServiceUnavailableException - this is a subclass of
SCA_RuntimeException and signals a problem in connecting to or
using a remote service, but one which might succeed if retried.
In the case of Web services, this exception is thrown if a
SoapFault is received with a fault code that indicates that a
retry might be successful.
</P
></LI
></UL
></DIV
><DIV
CLASS="section"
><H3
CLASS="section"
><A
NAME="AEN197137"
>Handling of Business exceptions</A
></H3
><P
>
Business exceptions may be defined and thrown by a component
in the normal way, regardless of whether the component has been
called locally or remotely. The SCA runtime does not catch
business exceptions that have been thrown by a component called
locally, so they will be returned to a caller in the normal way. If a
component has been called via a Web service, on the other hand, the
SCA runtime on the service providing end does catch business
exceptions, and will ensure these are passed back to the calling
end and re-thrown. Assuming that the calling end has a definition
of the exception (that is, is able to include a file containing the
PHP class defining the exception) the re-thrown exception will
contain the same details as the original, so that the
<B
CLASS="function"
>getLine()</B
> and
<B
CLASS="function"
>getFile()</B
> methods for example will contain
the location where the exception was thrown within the business
logic. The exception will be passed in the detail field of a soap
fault with a fault code of "Client".
</P
></DIV
></DIV
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="sca.classes"
>Classes pré-definidas</A
></H1
><P
>
Most of the interface to SCA is through the annotations within
SCA components so there are few public classes and methods. The only
SCA classes that scripts or components can call are the SCA class
itself, and the proxy classes SCA_LocalProxy and SCA_SoapProxy.
</P
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="sca.class"
><B
CLASS="classname"
>SCA</B
></A
></H2
><P
> Much of the work of the SCA class is performed when the file
SCA.php is included within an SCA component. However, a PHP script
may include
<TT
CLASS="filename"
>SCA.php</TT
> and call the
<B
CLASS="function"
>getService()</B
> method on the SCA class in order
to obtain a proxy for a service. A component will not need to do this as
proxies are obtained instead by defining an instance variable with
the @reference annotation.
</P
><P
>
Components that need to create an SDO to return to a caller will
need a data factory to call. For this purpose the SCA class supports
the
<B
CLASS="function"
>createDataObject()</B
> method, which will
create an SDO according to the model defined by the component's
@types annotations. The arguments to
<B
CLASS="function"
>createDataObject()</B
> are the same as those to
SDO's XML Data Access Service.
</P
><DIV
CLASS="section"
><H3
CLASS="section"
><A
NAME="sca.class.SCA.methods"
>Métodos</A
></H3
><P
></P
><UL
><LI
><P
> <A
HREF="function.sca-getservice.html"
> getService</A
> - obtain a proxy for a service
</P
></LI
><LI
><P
> <A
HREF="function.sca-createdataobject.html"
> createDataObject</A
> - create an SDO
</P
></LI
></UL
></DIV
></DIV
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="sca-local-proxy.class"
><B
CLASS="classname"
>SCA_LocalProxy</B
></A
></H2
><P
> When
<B
CLASS="function"
>getService()</B
> is called with the target of a
local PHP component, a local proxy is returned. A local proxy is also
injected into the instance variables of a component that are
defined with an @reference and an @binding.php anotation. When the
script or component makes calls on the local proxy, they are passed
on to the target component itself.
</P
><P
>
Components that need to create an SDO to pass to a component
will need a data factory to call. For this purpose the
SCA_LocalProxy class supports the createDataObject method,
which will create an SDO according to the model defined by the
components' @types annotations. The arguments to the
createDataObject are the same as those to SDO's XML Data Access
Service.
</P
><DIV
CLASS="section"
><H3
CLASS="section"
><A
NAME="sca.class.SCA-LocalProxy.methods"
>Métodos</A
></H3
><P
></P
><UL
><LI
><P
> <A
HREF="function.sca-localproxy-createdataobject.html"
> createDataObject</A
> - create an SDO
</P
></LI
></UL
></DIV
></DIV
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="sca-soap-proxy.class"
><B
CLASS="classname"
>SCA_SoapProxy</B
></A
></H2
><P
> When
<B
CLASS="function"
>getService()</B
> is called with the target of a
WSDL file, a SOAP proxy is returned. A SOAP proxy is also injected
into the instance variables of a component that are defined with an
@reference and an @binding.ws anotations. When the script or
component makes calls on the SOAP proxy, they are formed into Web
service SOAP requests and passed on to the target component, with
the help of the PHP Soap extension.
</P
><P
>
Components that need to create an SDO to pass to a component
will need a data factory to call. For this purpose the SCA_SoapProxy
class supports the createDataObject method, which will create an
SDO according to the model defined within the target WSDL. The
arguments to the createDataObject are the same as those to SDO's XML
Data Access Service.
</P
><DIV
CLASS="section"
><H3
CLASS="section"
><A
NAME="sca.class.SCA-SoapProxy.methods"
>Métodos</A
></H3
><P
></P
><UL
><LI
><P
> <A
HREF="function.sca-soapproxy-createdataobject.html"
> createDataObject</A
> - create an SDO
</P
></LI
></UL
></DIV
></DIV
></DIV
></DIV
><DIV
CLASS="TOC"
><DL
><DT
><B
>Índice</B
></DT
><DT
><A
HREF="function.sca-localproxy-createdataobject.html"
>SCA_LocalProxy::createDataObject</A
> -- create an SDO </DT
><DT
><A
HREF="function.sca-soapproxy-createdataobject.html"
>SCA_SoapProxy::createDataObject</A
> -- create an SDO </DT
><DT
><A
HREF="function.sca-createdataobject.html"
>SCA::createDataObject</A
> -- create an SDO </DT
><DT
><A
HREF="function.sca-getservice.html"
>SCA::getService</A
> --
Obtain a proxy for a service
</DT
></DL
></DIV
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="function.satellite-object-to-string.html"
ACCESSKEY="P"
>Anterior</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Principal</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="function.sca-localproxy-createdataobject.html"
ACCESSKEY="N"
>Próxima</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>satellite_object_to_string</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="funcref.html"
ACCESSKEY="U"
>Acima</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>SCA_LocalProxy::createDataObject</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
