sca-php-examples-php-structures-8

  • Examples
  • Working with Data Structures

  • Working with Data Structures
  • Working with Data Structures

    Working with Data Structures

    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 the SDO pages 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.

    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.

    How data structures are defined to SCA
    components

    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.

    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.

    Example #1 A Component that uses Data
    Structures

    <?php

    include "SCA/SCA.php";

    /**
     * Manage the portfolio for a customer.
     *
     * @service
     * @binding.soap
     *
     * @types http://www.example.org/Portfolio PortfolioTypes.xsd
     *
     */
    class PortfolioManagement {

        /**
         * Get the stock portfolio for a given customer.
         *
         * @param integer $customer_id The id for the customer
         * @return Portfolio http://www.example.org/Portfolio The stock portfolio (symbols and quantities)
         */
        
    function getPortfolio($customer_id) {
            
    // Pretend we just got this from a database
            
    $portfolio SCA::createDataObject('http://www.example.org/Portfolio''Portfolio');
            
    $holding $portfolio->createDataObject('holding');
            
    $holding->ticker 'AAPL';
            
    $holding->number 100.5;
            
    $holding $portfolio->createDataObject('holding');
            
    $holding->ticker 'INTL';
            
    $holding->number 100.5;
            
    $holding $portfolio->createDataObject('holding');
            
    $holding->ticker 'IBM';
            
    $holding->number 100.5;
            return 
    $portfolio;
        }

    }
    ?>

    The @types annotation:

    <?php
    @types http://www.example.org/Portfolio PortfolioTypes.xsd
    ?>

    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:

    <xs:import schemaLocation="PortfolioTypes.xsd"
                          namespace="http://www.example.org/Portfolio"/>
    

    so the URI, absolute or relative, must be one that
    can be resolved when included in the schemaLocation attribute.

    Creating SDOs

    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.

    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.

    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.

    Creating an SDO to pass to a service

    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.

    <?php
    /**
     * @reference
     * @binding.local AddressBook.php
     */
    $address_book;
    ?>

    The AddressBook component that it wishes to call is
    defined as follows:

    <?php
    /**
    * @service
    * @binding.soap
    * @types http://addressbook ../AddressBook/AddressBook.xsd
    */
    class AddressBook {

        /**
         * @param personType $person http://addressbook (a person object)
         * @return addressType http://addressbook (the address object for the person object)
         */
        
    function lookupAddress($person)  {
            ...
        }
    }
    ?>

    The AddressBook component provides a service method
    called lookupAddress() 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.

    Once the component that wishes to use the
    AddressBook component has been constructed, so that the $address_book instance
    variable contains a proxy for the service, the calling component
    can use the proxy in $address_book to create the person SDO, as
    shown below:

    <?php
    $william_shakespeare        
    $address_book->createDataObject('http://addressbook','personType');
    $william_shakespeare ->name "William Shakespeare";
    $address                    $address_book->lookupAddress($william_shakespeare);
    ?>

    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
    getService() then
    the same approach is used.

    <?php
    $address_book 
    SCA::getService('AddressBook.php');
    $william_shakespeare $address_book->createDataObject('http://addressbook','personType');
    ?>

    Creating an SDO to return from a component

    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 createDataObject() static method
    on SCA.php. Hence if the AddressBook
    component described above needed to create an object of type
    addressType within the namespace
    http://addressbook, it might do so as follows:

    <?php
    $address 
    SCA::createDataObject('http://addressbook','addressType');
    ?>