<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Working with Data Structures</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="sca.examples.understanding-wsdl.html">Understanding how the WSDL is generated</a></div>
<div class="next" style="text-align: right; float: right;"><a href="sca.examples.errorhandling.html">Error handling</a></div>
<div class="up"><a href="sca.examples.html">Examples</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="sca.examples.structures" class="section">
<h2 class="title"> Working with Data Structures </h2>
<p class="para">
SCA components can pass and return the four PHP scalar types
boolean, integer, float 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" class="link">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 class="para">
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" id="sca.examples.structures.defined">
<h2 class="title"> How data structures are defined to SCA components </h2>
<p class="para">
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 class="para">
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 class="para">
<div class="example" id="example-6551">
<p><strong>Example #1 A Component that uses Data Structures</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br /></span><span style="color: #007700">include </span><span style="color: #DD0000">"SCA/SCA.php"</span><span style="color: #007700">;<br /><br /></span><span style="color: #FF8000">/**<br /> * Manage the portfolio for a customer.<br /> *<br /> * @service<br /> * @binding.soap<br /> *<br /> * @types http://www.example.org/Portfolio PortfolioTypes.xsd<br /> *<br /> */<br /></span><span style="color: #007700">class </span><span style="color: #0000BB">PortfolioManagement </span><span style="color: #007700">{<br /><br /> </span><span style="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 /> </span><span style="color: #007700">function </span><span style="color: #0000BB">getPortfolio</span><span style="color: #007700">(</span><span style="color: #0000BB">$customer_id</span><span style="color: #007700">) {<br /> </span><span style="color: #FF8000">// Pretend we just got this from a database<br /> </span><span style="color: #0000BB">$portfolio </span><span style="color: #007700">= </span><span style="color: #0000BB">SCA</span><span style="color: #007700">::</span><span style="color: #0000BB">createDataObject</span><span style="color: #007700">(</span><span style="color: #DD0000">'http://www.example.org/Portfolio'</span><span style="color: #007700">, </span><span style="color: #DD0000">'Portfolio'</span><span style="color: #007700">);<br /> </span><span style="color: #0000BB">$holding </span><span style="color: #007700">= </span><span style="color: #0000BB">$portfolio</span><span style="color: #007700">-></span><span style="color: #0000BB">createDataObject</span><span style="color: #007700">(</span><span style="color: #DD0000">'holding'</span><span style="color: #007700">);<br /> </span><span style="color: #0000BB">$holding</span><span style="color: #007700">-></span><span style="color: #0000BB">ticker </span><span style="color: #007700">= </span><span style="color: #DD0000">'AAPL'</span><span style="color: #007700">;<br /> </span><span style="color: #0000BB">$holding</span><span style="color: #007700">-></span><span style="color: #0000BB">number </span><span style="color: #007700">= </span><span style="color: #0000BB">100.5</span><span style="color: #007700">;<br /> </span><span style="color: #0000BB">$holding </span><span style="color: #007700">= </span><span style="color: #0000BB">$portfolio</span><span style="color: #007700">-></span><span style="color: #0000BB">createDataObject</span><span style="color: #007700">(</span><span style="color: #DD0000">'holding'</span><span style="color: #007700">);<br /> </span><span style="color: #0000BB">$holding</span><span style="color: #007700">-></span><span style="color: #0000BB">ticker </span><span style="color: #007700">= </span><span style="color: #DD0000">'INTL'</span><span style="color: #007700">;<br /> </span><span style="color: #0000BB">$holding</span><span style="color: #007700">-></span><span style="color: #0000BB">number </span><span style="color: #007700">= </span><span style="color: #0000BB">100.5</span><span style="color: #007700">;<br /> </span><span style="color: #0000BB">$holding </span><span style="color: #007700">= </span><span style="color: #0000BB">$portfolio</span><span style="color: #007700">-></span><span style="color: #0000BB">createDataObject</span><span style="color: #007700">(</span><span style="color: #DD0000">'holding'</span><span style="color: #007700">);<br /> </span><span style="color: #0000BB">$holding</span><span style="color: #007700">-></span><span style="color: #0000BB">ticker </span><span style="color: #007700">= </span><span style="color: #DD0000">'IBM'</span><span style="color: #007700">;<br /> </span><span style="color: #0000BB">$holding</span><span style="color: #007700">-></span><span style="color: #0000BB">number </span><span style="color: #007700">= </span><span style="color: #0000BB">100.5</span><span style="color: #007700">;<br /> return </span><span style="color: #0000BB">$portfolio</span><span style="color: #007700">;<br /> }<br /><br />}<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<p class="para">
The @types annotation:
</p>
<p class="para">
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">@</span><span style="color: #0000BB">types http</span><span style="color: #007700">:</span><span style="color: #FF8000">//www.example.org/Portfolio PortfolioTypes.xsd<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</p>
<p class="para">
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 class="para">
<div class="example-contents">
<div class="xmlcode"><pre class="xmlcode"><xs:import schemaLocation="PortfolioTypes.xsd"
namespace="http://www.example.org/Portfolio"/></pre>
</div>
</div>
</p>
<p class="para">
so the URI, absolute or relative, must be one that can be
resolved when included in the schemaLocation attribute.
</p>
</div>
<div class="section" id="sca.examples.structures.creating">
<h2 class="title">Creating SDOs </h2>
<p class="para">
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 class="para">
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 class="para">
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" id="sca.examples.structures.services">
<h2 class="title">Creating an SDO to pass to a service</h2>
<p class="para">
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 class="para">
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">/**<br /> * @reference<br /> * @binding.local AddressBook.php<br /> */<br /></span><span style="color: #0000BB">$address_book</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</p>
<p class="para">
The AddressBook component that it wishes to call is defined
as follows:
</p>
<p class="para">
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">/**<br />* @service<br />* @binding.soap<br />* @types http://addressbook ../AddressBook/AddressBook.xsd<br />*/<br /></span><span style="color: #007700">class </span><span style="color: #0000BB">AddressBook </span><span style="color: #007700">{<br /><br /> </span><span style="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 /> </span><span style="color: #007700">function </span><span style="color: #0000BB">lookupAddress</span><span style="color: #007700">(</span><span style="color: #0000BB">$person</span><span style="color: #007700">) {<br /> ...<br /> }<br />}<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</p>
<p class="para">
The AddressBook component provides a service method called
<span class="function"><strong>lookupAddress()</strong></span> 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 class="para">
Once the component that wishes to use the AddressBook
component has been constructed, so that the
<var class="varname"><var class="varname">$address_book</var></var> instance variable contains
a proxy for the service, the calling component can use the proxy in
<var class="varname"><var class="varname">$address_book</var></var> to create the person SDO, as
shown below:
</p>
<p class="para">
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$william_shakespeare </span><span style="color: #007700">= </span><span style="color: #0000BB">$address_book</span><span style="color: #007700">-></span><span style="color: #0000BB">createDataObject</span><span style="color: #007700">(</span><span style="color: #DD0000">'http://addressbook'</span><span style="color: #007700">,</span><span style="color: #DD0000">'personType'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$william_shakespeare </span><span style="color: #007700">-></span><span style="color: #0000BB">name </span><span style="color: #007700">= </span><span style="color: #DD0000">"William Shakespeare"</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$address </span><span style="color: #007700">= </span><span style="color: #0000BB">$address_book</span><span style="color: #007700">-></span><span style="color: #0000BB">lookupAddress</span><span style="color: #007700">(</span><span style="color: #0000BB">$william_shakespeare</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</p>
<p class="para">
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
<span class="function"><strong>getService()</strong></span> then the same approach is
used.
</p>
<p class="para">
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$address_book </span><span style="color: #007700">= </span><span style="color: #0000BB">SCA</span><span style="color: #007700">::</span><span style="color: #0000BB">getService</span><span style="color: #007700">(</span><span style="color: #DD0000">'AddressBook.php'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$william_shakespeare </span><span style="color: #007700">= </span><span style="color: #0000BB">$address_book</span><span style="color: #007700">-></span><span style="color: #0000BB">createDataObject</span><span style="color: #007700">(</span><span style="color: #DD0000">'http://addressbook'</span><span style="color: #007700">,</span><span style="color: #DD0000">'personType'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</p>
</div>
<div class="section" id="sca.examples.structures.services.returning">
<h2 class="title"> Creating an SDO to return from a component </h2>
<p class="para">
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
<span class="function"><strong>createDataObject()</strong></span> static method on
<var class="filename">SCA.php</var>. Hence if the AddressBook
component described above needed to create an object of type
<strong class="classname">addressType</strong> within the namespace
http://addressbook, it might do so as follows:
</p>
<p class="para">
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$address </span><span style="color: #007700">= </span><span style="color: #0000BB">SCA</span><span style="color: #007700">::</span><span style="color: #0000BB">createDataObject</span><span style="color: #007700">(</span><span style="color: #DD0000">'http://addressbook'</span><span style="color: #007700">,</span><span style="color: #DD0000">'addressType'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="sca.examples.understanding-wsdl.html">Understanding how the WSDL is generated</a></div>
<div class="next" style="text-align: right; float: right;"><a href="sca.examples.errorhandling.html">Error handling</a></div>
<div class="up"><a href="sca.examples.html">Examples</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
