mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-18 18:08:54 +00:00
452688c02c
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@214448 c90b9560-bf6c-de11-be94-00142212c4b1
1704 lines
54 KiB
XML
1704 lines
54 KiB
XML
<?xml version='1.0' encoding='iso-8859-1'?>
|
|
<!-- $Revision: 1.23 $ -->
|
|
<!-- Purpose: database.abstract -->
|
|
<!-- Membership: pecl -->
|
|
<!-- State: experimental -->
|
|
|
|
<reference id="ref.sdo">
|
|
<title>SDO Functions</title>
|
|
<titleabbrev>SDO</titleabbrev>
|
|
|
|
<partintro>
|
|
<section id="sdo.intro">
|
|
&reftitle.intro;
|
|
<para>
|
|
Service Data Objects (SDOs) enable PHP applications to work with
|
|
data from different sources (like a database query, an XML file,
|
|
and a spreadsheet) using a single interface.
|
|
</para>
|
|
<para>
|
|
Each different kind of data source requires a Data Access Service
|
|
(DAS) to provide access to the data in the data source.
|
|
In your PHP application, you use a DAS to create an SDO
|
|
instance that represents some data in the data source. You can then
|
|
set and get values in the SDO instance using the standard SDO
|
|
interface. Finally, you use a DAS to write the modified data back
|
|
to a data source, typically the same one.
|
|
</para>
|
|
<para>
|
|
See the
|
|
<link linkend="sdo.das.table">list of Data Access Services</link>
|
|
for details on those
|
|
currently available. In addition to the provided DASs, SDO also
|
|
provides interfaces to enable others to be implemented
|
|
(see the section on <link linkend="sdo.class.sdo-das-spis">SDO Data
|
|
Access Services Interface</link> for more details).
|
|
</para>
|
|
<para>
|
|
This extension is derived from concepts taken from the
|
|
<ulink url="&url.ibm.sdo;">Service Data Objects specification</ulink>.
|
|
It includes a version of the
|
|
<ulink url="&url.apache.tuscany;">Apache Tuscany</ulink> SDO 2.0 for C++ project.
|
|
</para>
|
|
|
|
<section id="sdo.intro.structure">
|
|
<title>The Structure of a Service Data Object</title>
|
|
<para>
|
|
A Service Data Object instance is made up of a tree of data objects.
|
|
The tree is defined by containment relationships between the data
|
|
objects. For example, a Company data object might consist of a number
|
|
of Department data objects and therefore the Company would have
|
|
a containment relationship to the Departments.
|
|
</para>
|
|
<para> An SDO may also have non-containment references between data objects in the
|
|
tree. For example, one Employee data object might reference another Employee to
|
|
identify a career mentor.
|
|
</para>
|
|
<para>
|
|
As well as data objects referencing each other, they can also have
|
|
primitive properties. For example, the Company data object might
|
|
have a property called "name" of type string, for holding the name
|
|
of the company (for example, "Acme").
|
|
</para>
|
|
<para> Each of these properties of a data object - containment relationships,
|
|
non-containment references, or primitive properties - may be many-valued or
|
|
single-valued. In the above examples, Departments is many-valued and
|
|
the Company name is single-valued.
|
|
</para>
|
|
<para> In PHP, each SDO data object is represented as a PHP object. The properties of the
|
|
data object can be accessed using either object syntax or associative array syntax.
|
|
We'll see some examples of this later.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="sdo.requirements">
|
|
&reftitle.required;
|
|
<para> The SDO extension requires PHP 5.1 or higher. It also requires the libxml2 library.
|
|
Normally libxml2 will already be installed, but if not, it can be downloaded from
|
|
<ulink url='&url.libxml;'>&url.libxml;</ulink>.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="sdo.installation">
|
|
&reftitle.install;
|
|
<procedure id='sdo.install.unix'>
|
|
<title>Unix systems</title>
|
|
<step>
|
|
<para> You can download and install the latest stable release of all three SDO
|
|
components - the SDO core, the XML DAS and the Relational DAS - with the command:
|
|
<screen> <![CDATA[
|
|
pecl install sdo
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
<para> This command will build the SDO and XML shared libraries as well as installing
|
|
the PHP files that make the Relational DAS.
|
|
</para>
|
|
<para>
|
|
If you want to use the latest beta version, then instead run:
|
|
<screen>
|
|
<![CDATA[
|
|
pecl install sdo-beta
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para> The
|
|
<command>pecl</command> command automatically installs the SDO and SDO_DAS_XML
|
|
modules into your PHP extensions directory. To enable the SDO extensions you must add
|
|
the following lines to &php.ini;:
|
|
<screen> <![CDATA[
|
|
extension=sdo.so
|
|
extension=sdo_das_xml.so
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
<para> For more information about building PECL packages, consult the
|
|
<link linkend="install.pecl">PECL installation</link> section of the manual.
|
|
</para>
|
|
</step>
|
|
</procedure>
|
|
|
|
<procedure id='sdo.install.win32'>
|
|
<title>Windows</title>
|
|
<step>
|
|
<para>
|
|
The latest DLLs for the SDO core and the XML DAS can be
|
|
downloaded from
|
|
<ulink url='&url.pecl.win.ext;php_sdo.dll'>php_sdo.dll</ulink> and
|
|
<ulink url='&url.pecl.win.ext;php_sdo_das_xml.dll'>php_sdo_das_xml.dll</ulink> respectively.
|
|
</para>
|
|
<para>
|
|
Note that currently the <ulink url='&url.pecl.win;'>pecl4win</ulink> site does not provide
|
|
these binaries at the current release level; you can only download the latest level.
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para> The
|
|
<command>pecl</command> command automatically installs the SDO and SDO_DAS_XML
|
|
modules into your PHP extensions directory. To enable the SDO extensions you must add
|
|
the following lines to &php.ini;:
|
|
<screen>
|
|
<![CDATA[
|
|
extension=php_sdo.dll
|
|
extension=php_sdo_das_xml.dll
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para> The Relational DAS can be downloaded and installed with the command:
|
|
<screen>
|
|
<![CDATA[
|
|
pecl install -B sdo
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
<para> The Relational DAS is written in PHP. You may need to update your
|
|
<link linkend="ini.include-path">include_path</link> in &php.ini; to point to
|
|
the directory that contains
|
|
<filename>sdo/DAS/Relational</filename>.
|
|
</para>
|
|
</step>
|
|
</procedure>
|
|
|
|
<procedure id='sdo.build.linux.steps'>
|
|
<title>Building SDO on Linux</title>
|
|
<para> This section describes how to build the SDO core and XML DAS on Linux. You would
|
|
only need to know how to do this if you wish to build a recent version that you have checked
|
|
out of CVS.
|
|
</para>
|
|
<step>
|
|
<para>
|
|
Change to the main extension directory:
|
|
<command>cd < wherever your sdo code is ></command>
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para>
|
|
Run <command>phpize</command>, which will set up the environment to
|
|
compile both SDO and the XML Data Access Service.
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para>
|
|
Next, run <command>./configure; make; make install</command>.
|
|
Please note, you may need to login as root to install the extension.
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para>
|
|
Make sure that these modules are loaded by PHP, by adding
|
|
<command>extension=sdo.so</command> and
|
|
<command>extension=sdo_das_xml.so</command> to your
|
|
&php.ini; file in the same order.
|
|
</para>
|
|
</step>
|
|
</procedure>
|
|
</section>
|
|
|
|
<section id="sdo.das.table">
|
|
<title>Data Access Services</title>
|
|
<para>
|
|
The table below lists the currently provided SDO Data Access Services:
|
|
<informaltable>
|
|
<tgroup cols='2'>
|
|
<thead>
|
|
<row>
|
|
<entry>DAS Name</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<link linkend="ref.sdo-das-xml">SDO_DAS_XML</link>
|
|
</entry>
|
|
<entry>
|
|
An XML Data Access Service supporting reading/writing
|
|
SDOs as XML documents.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<link linkend="ref.sdo.das.rel">SDO_DAS_Relational</link>
|
|
</entry>
|
|
<entry>
|
|
A PDO-based Data Access Service supporting reading/writing SDO
|
|
to relational databases.
|
|
Implements an optimistic concurrency policy for updates.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
</section>
|
|
|
|
<section id='sdo.limitations'>
|
|
<title>Limitations</title>
|
|
<procedure id='sdo.limitations.implementation'>
|
|
<title>Implementation Limitations</title>
|
|
<para>
|
|
The following are limitations in the current SDO implementation:
|
|
</para>
|
|
<step>
|
|
<para>
|
|
There is no support for multi-byte character sets.
|
|
This will be considered, depending on community requirements,
|
|
in the Unicode-enabled version of PHP.
|
|
See <link linkend="ref.unicode">Unicode Functions</link>.
|
|
</para>
|
|
</step>
|
|
</procedure>
|
|
<procedure id='sdo.limitations.sdo'>
|
|
<title>SDO Limitations</title>
|
|
<para>
|
|
The following SDO 2.0 concepts are not supported in the current
|
|
PHP implementation.
|
|
It is not necessarily the case that these will all be added over time.
|
|
Their inclusion will depend on community requirements.
|
|
</para>
|
|
<step>
|
|
<para>
|
|
Bi-directional relationships.
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para>
|
|
Type and property alias names.
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para>
|
|
Read-only properties.
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para>
|
|
The Helper classes defined in SDO 2.0 are not directly implemented.
|
|
However equivalent function is provided in a more natural way for PHP.
|
|
For example the function of <command>CopyHelper::copy()</command>
|
|
is provided by applying the PHP
|
|
<link linkend='language.oop5.cloning'>clone</link> keyword to a data object.
|
|
</para>
|
|
</step>
|
|
</procedure>
|
|
</section>
|
|
|
|
<section id='sdo.examples'>
|
|
&reftitle.examples;
|
|
<para>
|
|
The examples below assume an SDO created with the schema
|
|
and instance information shown below, using the XML Data Access Service.
|
|
</para>
|
|
<para>
|
|
The instance document below describes a single company,
|
|
called 'MegaCorp', which contains a single department,
|
|
called 'Advanced Technologies'.
|
|
The Advanced Technologies department contains three employees.
|
|
The company employeeOfTheMonth is referencing the second employee,
|
|
'Jane Doe'.
|
|
</para>
|
|
<para>
|
|
<programlisting role="xml">
|
|
<![CDATA[
|
|
<?xml version="1.0" encoding="UTF-8" ?>
|
|
<company xmlns="companyNS" name="MegaCorp"
|
|
employeeOfTheMonth="E0003">
|
|
<departments name="Advanced Technologies" location="NY" number="123">
|
|
<employees name="John Jones" SN="E0001"/>
|
|
<employees name="Jane Doe" SN="E0003"/>
|
|
<employees name="Al Smith" SN="E0004" manager="true"/>
|
|
</departments>
|
|
</company>
|
|
]]>
|
|
</programlisting>
|
|
</para>
|
|
<para> The root element of the schema is a company. The company contains departments, and
|
|
each department contains employees. Each element has a number of attributes to store
|
|
things like name, serial number, and so on. Finally, the company also has an IDREF
|
|
attribute which identifies one of the employees as the 'employeeOfTheMonth'.
|
|
</para>
|
|
<para>
|
|
<programlisting role="xml">
|
|
<![CDATA[
|
|
<xsd:schema
|
|
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
|
|
xmlns:sdo="commonj.sdo"
|
|
xmlns:sdoxml="commonj.sdo/xml"
|
|
xmlns:company="companyNS"
|
|
targetNamespace="companyNS">
|
|
<xsd:element name="company" type="company:CompanyType"/>
|
|
<xsd:complexType name="CompanyType">
|
|
<xsd:sequence>
|
|
<xsd:element name="departments" type="company:DepartmentType"
|
|
maxOccurs="unbounded"/>
|
|
</xsd:sequence>
|
|
<xsd:attribute name="name" type="xsd:string"/>
|
|
<xsd:attribute name="employeeOfTheMonth" type="xsd:IDREF"
|
|
sdoxml:propertyType="company:EmployeeType"/>
|
|
</xsd:complexType>
|
|
<xsd:complexType name="DepartmentType">
|
|
<xsd:sequence>
|
|
<xsd:element name="employees" type="company:EmployeeType"
|
|
maxOccurs="unbounded"/>
|
|
</xsd:sequence>
|
|
<xsd:attribute name="name" type="xsd:string"/>
|
|
<xsd:attribute name="location" type="xsd:string"/>
|
|
<xsd:attribute name="number" type="xsd:int"/>
|
|
</xsd:complexType>
|
|
<xsd:complexType name="EmployeeType">
|
|
<xsd:attribute name="name" type="xsd:string"/>
|
|
<xsd:attribute name="SN" type="xsd:ID"/>
|
|
<xsd:attribute name="manager" type="xsd:boolean"/>
|
|
</xsd:complexType>
|
|
</xsd:schema>
|
|
]]>
|
|
</programlisting>
|
|
</para>
|
|
<para>The XML Data Access Service maps the schema to an SDO. Attributes such as "name"
|
|
become primitive properties, the sequence of employees becomes a many-valued
|
|
containment relationship, and so on. Note that the containment relationships are
|
|
expressed as one complex type within another, whereas non-containment references are
|
|
expressed in terms of ID and IDREF, with a special
|
|
<command>sdoxml:propertyType</command> attribute specifying the type of the
|
|
non-containment reference.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="sdo.sample.getset">
|
|
<title>Setting and Getting Property Values</title>
|
|
<para> The following examples assume
|
|
<command>$company</command> is the root of a tree of data objects created from the
|
|
schema and instance document shown above.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>Access via property name</title>
|
|
<para>
|
|
Data object properties can be accessed using the object property
|
|
access syntax. The following sets the company name to 'Acme'.
|
|
</para>
|
|
<programlisting role="php" id="sdo.examples.propname">
|
|
<![CDATA[
|
|
<?php
|
|
$company->name = 'Acme';
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
|
|
<para>
|
|
<example>
|
|
<title>Access via property name as array index</title>
|
|
<para>We can also access properties using associative array syntax. The simplest
|
|
form of this uses the property name as the array index. For example, the following sets
|
|
the company name and gets the employeeOfTheMonth.
|
|
</para>
|
|
<programlisting role="php" id="sdo.examples.simplexpath">
|
|
<![CDATA[
|
|
<?php
|
|
$company['name'] = 'UltraCorp';
|
|
$eotm = $company['employeeOfTheMonth'];
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
|
|
<para>
|
|
<example>
|
|
<title>Data Object iteration</title>
|
|
<para>
|
|
We can iterate over the properties of a data object using foreach.
|
|
The following iterates over the properties of the employee of the month.
|
|
</para>
|
|
<programlisting role="php" id="sdo.examples.doiter">
|
|
<![CDATA[
|
|
<?php
|
|
$eotm = $company->employeeOfTheMonth;
|
|
foreach ($eotm as $name => $value) {
|
|
echo "$name: $value\n";
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
which will output:
|
|
</para>
|
|
<programlisting id="sdo.examples.doiter-output">
|
|
<![CDATA[
|
|
name: Jane Doe
|
|
SN: E0003
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
The 'manager' property is not output, because it has not been set.
|
|
</para>
|
|
</example>
|
|
</para>
|
|
|
|
<para>
|
|
<example>
|
|
<title>Access many-valued property by name</title>
|
|
<para> Many-valued data object properties can also be accessed using the object
|
|
property name syntax. The following gets the list of departments.
|
|
</para>
|
|
<programlisting role="php" id="sdo.examples.mvpname">
|
|
<![CDATA[
|
|
<?php
|
|
$departments = $company->departments;
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
|
|
<para>
|
|
<example>
|
|
<title>Many-valued element access</title>
|
|
<para>
|
|
We can access individual elements of many-valued properties using array
|
|
syntax. The following accesses the first department in the company.
|
|
</para>
|
|
<programlisting role="php" id="sdo.examples.mvaccess">
|
|
<![CDATA[
|
|
<?php
|
|
$ad_tech_dept = $company->departments[0];
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
|
|
<para>
|
|
<example>
|
|
<title>Many-valued property iteration</title>
|
|
<para>
|
|
Many-valued properties can also be iterated over using
|
|
foreach. The following iterates over the company's departments.
|
|
</para>
|
|
<programlisting role="php" id="sdo.examples.mvpiter">
|
|
<![CDATA[
|
|
<?php
|
|
foreach ($company->departments as $department) {
|
|
// ...
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
Each iteration will assign the next department in the
|
|
list to the variable <command>$department</command>.
|
|
</para>
|
|
</example>
|
|
</para>
|
|
|
|
<para>
|
|
<example>
|
|
<title>Chained property access</title>
|
|
<para> We can chain property references on a single line.
|
|
The following sets and gets the name of the first department.
|
|
</para>
|
|
<programlisting role="php" id="sdo.examples.nestedprop">
|
|
<![CDATA[
|
|
<?php
|
|
$company->departments[0]->name = 'Emerging Technologies';
|
|
$dept_name = $company->departments[0]->name;
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
<para>Using the associative array syntax, this is equivalent to</para>
|
|
<programlisting role="php" id="sdo.examples.chainarray">
|
|
<![CDATA[
|
|
<?php
|
|
$company['departments'][0]['name'] = 'Emerging Technologies';
|
|
$dept_name = $company['departments'][0]['name'];
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
<para> In either case, the dept_name variable is set to 'Emerging Technologies'.
|
|
</para>
|
|
</example>
|
|
</para>
|
|
|
|
<para>
|
|
<example>
|
|
<title>XPath navigation</title>
|
|
<para> The associative array index can be an XPath-like expression. Valid
|
|
expressions are defined by an augmented sub-set of XPath.
|
|
</para>
|
|
<para>
|
|
Two forms of indexing into many-valued properties are supported.
|
|
The first is the standard XPath array syntax with the indexing
|
|
starting at one, the second is an SDO extension to XPath with an index
|
|
starting at zero. The standard syntax is:
|
|
</para>
|
|
<programlisting role="php" id="sdo.examples.xpath1nav">
|
|
<![CDATA[
|
|
<?php
|
|
$jane_doe = $company["departments[1]/employees[2]"];
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
<para>and the SDO XPath extension syntax is:</para>
|
|
<programlisting role="php" id="sdo.examples.xpath0nav">
|
|
<![CDATA[
|
|
<?php
|
|
$jane_doe = $company["departments.0/employees.1"];
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
Both these examples get the second employee from the first department.
|
|
</para>
|
|
</example>
|
|
</para>
|
|
|
|
<para>
|
|
<example>
|
|
<title>XPath querying</title>
|
|
<para>
|
|
We can use XPath to query and identify parts of a data object based
|
|
on instance data. The following retrieves the manager from the
|
|
'Advanced Technologies' department.
|
|
</para>
|
|
<programlisting role="php" id="sdo.examples.xpathquery">
|
|
<![CDATA[
|
|
<?php
|
|
$ad_tech_mgr =
|
|
$company["departments[name='Advanced Technologies']/employees[manager=true]"];
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
|
|
<para>
|
|
<example>
|
|
<title>Creating child data objects</title>
|
|
<para>
|
|
A data object can be a factory for its child data objects.
|
|
A child data object is automatically part of the data graph.
|
|
The following add a new employee to the 'Advanced Technologies'
|
|
department.
|
|
</para>
|
|
<programlisting role="php" id="sdo.examples.create">
|
|
<![CDATA[
|
|
<?php
|
|
$ad_tech_dept = $company["departments[name='Advanced Technologies']"];
|
|
$new_hire = $ad_tech_dept->createDataObject('employees');
|
|
$new_hire->name = 'John Johnson';
|
|
$new_hire->SN = 'E0005';
|
|
$new_hire->manager = false;
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
|
|
<para>
|
|
<example>
|
|
<title>Unset a primitive property</title>
|
|
<para>
|
|
We can use the <function>isset</function> and
|
|
<function>unset</function> functions to test and remove items
|
|
from the data object.
|
|
</para>
|
|
<para>
|
|
The following clears the name of the first department.
|
|
</para>
|
|
<programlisting role="php" id="sdo.examples.unsetprim">
|
|
<![CDATA[
|
|
<?php
|
|
unset($company->departments[0]->name);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
|
|
<para>
|
|
<example>
|
|
<title>Unset a data object</title>
|
|
<para>
|
|
unset can also be used to remove a data object from the tree.
|
|
The following example shows John Jones leaving the company.
|
|
</para>
|
|
<programlisting role="php" id="sdo.examples.unsetdo">
|
|
<![CDATA[
|
|
<?php
|
|
unset($company->departments[0]->employees[0]);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
|
|
<para>
|
|
<example>
|
|
<title>Unset a referenced data object</title>
|
|
<para>
|
|
The following removes the 'employeeOfTheMonth' from the company.
|
|
If this were a containment relationship then the
|
|
employee would be removed from the company
|
|
(probably not a good idea to sack your best employee each month!),
|
|
but since this is a non-containment reference,
|
|
the employee being referenced will remain in the
|
|
department in the company,
|
|
but will no longer be accessible via the employeeOfTheMonth property.
|
|
</para>
|
|
<programlisting role="php" id="sdo.examples.unsetrefdo">
|
|
<![CDATA[
|
|
<?php
|
|
if (isset($company->employeeOfTheMonth)) {
|
|
unset($company->employeeOfTheMonth);
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
|
|
<para>
|
|
<example>
|
|
<title>Access via property index</title>
|
|
<para> Data object properties can be accessed via their property index using array
|
|
syntax. The property index is the position at which the property's definition
|
|
appears in the model (in this case the xml schema). We can see from the schema listing
|
|
above that the company name attribute is the second company property (the SDO
|
|
interface makes no distinction between XML attributes and elements). The following
|
|
sets the company name to 'Acme', with the same result as
|
|
<link linkend="sdo.examples.propname">Access via property name</link>
|
|
</para>
|
|
<programlisting role="php" id="sdo.examples.propindex">
|
|
<![CDATA[
|
|
<?php
|
|
$company[1] = 'Acme';
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
<para> Using the index directly in this way is likely to be fragile. Normally the
|
|
property name syntax should be preferred, but the property index may be required
|
|
in special cases.
|
|
</para>
|
|
</example>
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section id="sdo.sample.sequence">
|
|
<title>Working with Sequenced Data Objects</title>
|
|
<para>
|
|
Sequenced data objects are SDOs which can track property
|
|
ordering across the properties of a data object. They can also
|
|
contain unstructured text elements (text element which do not
|
|
belong to any of the SDO's properties). Sequenced data objects are
|
|
useful for working with XML documents which allow unstructured text (i.e.
|
|
mixed=true) or if the elements can be interleaved (
|
|
<![CDATA[<A/><B/><A/>]]>). This can occur for example when
|
|
the schema defines maxOccurs>1 on a
|
|
element which is a complexType with a choice order indicator.
|
|
</para>
|
|
<para>
|
|
The examples below assume an SDO created with the following schema
|
|
and instance information, using the XML Data Access Service.
|
|
</para>
|
|
<para>
|
|
The schema below describes the format of a letter. The letter can
|
|
optionally contain three properties; date, firstName, and lastName.
|
|
The schema states <command>mixed="true"</command> which means that
|
|
unstructured text can be interspersed between the three properties.
|
|
</para>
|
|
<para>
|
|
<programlisting role="xml">
|
|
<![CDATA[
|
|
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
|
|
xmlns:letter="http://letterSchema"
|
|
targetNamespace="http://letterSchema">
|
|
<xsd:element name="letters" type="letter:FormLetter"/>
|
|
<xsd:complexType name="FormLetter" mixed="true">
|
|
<xsd:sequence>
|
|
<xsd:element name="date" minOccurs="0" type="xsd:string"/>
|
|
<xsd:element name="firstName" minOccurs="0" type="xsd:string"/>
|
|
<xsd:element name="lastName" minOccurs="0" type="xsd:string"/>
|
|
</xsd:sequence>
|
|
</xsd:complexType>
|
|
</xsd:schema>
|
|
]]>
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
The following is an instance letter document. It contains the
|
|
three letter properties; date, firstName and lastName, and has
|
|
unstructured text elements for the address and letter body.
|
|
</para>
|
|
<para>
|
|
<programlisting role="xml">
|
|
<![CDATA[
|
|
<letter:letters xmlns:letter="http://letterSchema">
|
|
<date>March 1, 2005</date>
|
|
Mutual of Omaha
|
|
Wild Kingdom, USA
|
|
Dear
|
|
<firstName>Casy</firstName>
|
|
<lastName>Crocodile</lastName>
|
|
Please buy more shark repellent.
|
|
Your premium is past due.
|
|
</letter:letters>
|
|
]]>
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
When loaded, the letter data object will have the sequence and
|
|
property indices shown in the table below:
|
|
<informaltable>
|
|
<tgroup cols='3'>
|
|
<thead>
|
|
<row>
|
|
<entry>Sequence Index</entry>
|
|
<entry>Property Index:Name</entry>
|
|
<entry>Value</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>0</entry>
|
|
<entry>0:date</entry>
|
|
<entry>March 1, 2005</entry>
|
|
</row>
|
|
<row>
|
|
<entry>1</entry>
|
|
<entry>-</entry>
|
|
<entry>Mutual of Omaha</entry>
|
|
</row>
|
|
<row>
|
|
<entry>2</entry>
|
|
<entry>-</entry>
|
|
<entry>Wild Kingdom, USA</entry>
|
|
</row>
|
|
<row>
|
|
<entry>3</entry>
|
|
<entry>-</entry>
|
|
<entry>Dear</entry>
|
|
</row>
|
|
<row>
|
|
<entry>4</entry>
|
|
<entry>1:firstName</entry>
|
|
<entry>Casy</entry>
|
|
</row>
|
|
<row>
|
|
<entry>5</entry>
|
|
<entry>2:lastName</entry>
|
|
<entry>Crocodile</entry>
|
|
</row>
|
|
<row>
|
|
<entry>6</entry>
|
|
<entry>-</entry>
|
|
<entry>Please buy more shark repellent.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>7</entry>
|
|
<entry>-</entry>
|
|
<entry>Your premium is past due.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
|
|
<para>
|
|
To ensure sequence indices are maintained, sequenced data objects
|
|
should be manipulated through the SDO_Sequence interface.
|
|
This allows the data object's instance data to be manipulated
|
|
in terms of the sequence index as opposed to the property index
|
|
(shown in the table above).
|
|
The following examples assume the letter instance has been
|
|
loaded into a data object referenced by the variable
|
|
<command>$letter</command>.
|
|
<example>
|
|
<title>Getting the SDO_Sequence interface</title>
|
|
<para>
|
|
We obtain a data object's sequence using the
|
|
<function>getSequence</function>
|
|
method. The follow gets the
|
|
sequence for the letter data object.
|
|
</para>
|
|
<programlisting role="php" id="sdo.examples.seqinterface">
|
|
<![CDATA[
|
|
<?php
|
|
$letter_seq = $letter->getSequence();
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
All subsequent examples assume that the
|
|
<command>$letter_seq</command>
|
|
variable has been assigned the sequence for the letter data object.
|
|
</para>
|
|
|
|
<para>
|
|
<example>
|
|
<title>Get/set sequence values</title>
|
|
<para>
|
|
We can get and set individual values (including unstructured text)
|
|
using the sequence index.
|
|
The following sets the firstName to 'Snappy' and gets the last
|
|
sequence values (the unstructured text, 'Your premium is past due.').
|
|
</para>
|
|
<programlisting role="php" id="sdo.examples.getsetseq">
|
|
<![CDATA[
|
|
<?php
|
|
$letter_seq[4] = 'Snappy';
|
|
$text = $letter_seq[count($letter_seq) - 1];
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
|
|
<para>
|
|
<example>
|
|
<title>Sequence iteration</title>
|
|
<para>
|
|
We can iterate through the individual sequence values using foreach.
|
|
The following runs through the individual values in sequence order.
|
|
</para>
|
|
<programlisting role="php" id="sdo.examples.seqiter">
|
|
<![CDATA[
|
|
<?php
|
|
foreach ($letter->getSequence() as $value) {
|
|
// ...
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
|
|
<para>
|
|
<example>
|
|
<title>Sequence versus Data Object</title>
|
|
<para>
|
|
Setting values through the data object interface may result in the
|
|
value not being part of the sequence. A value set through the data
|
|
object will only be accessible through the sequence if the property was
|
|
already part of the sequence. The following example sets the
|
|
lastName through the data object and gets it through the sequence.
|
|
This is fine because lastName already exists in the sequence. If
|
|
it had not previously been set, then lastName would be set to
|
|
'Smith', but would not be part of the sequence.
|
|
</para>
|
|
<programlisting role="php" id="sdo.examples.seqvsdo">
|
|
<![CDATA[
|
|
<?php
|
|
$letter[2] = 'Smith';
|
|
$last_name = $letter_seq[5];
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
|
|
<para>
|
|
<example>
|
|
<title>Adding to a sequence</title>
|
|
<para>
|
|
We can add new values to a sequence using the
|
|
<link linkend='function.SDO-Sequence-insert'><function>SDO_Sequence::insert</function></link>
|
|
method. The following examples assume that the 'firstName' and
|
|
'lastName' properties are initially unset.
|
|
</para>
|
|
<programlisting role="php" id="sdo.examples.seqadd">
|
|
<![CDATA[
|
|
<?php
|
|
// Append a firstName value to the sequence
|
|
// value: 'Smith'
|
|
// sequence index: NULL (append)
|
|
// propertyIdentifier: 1 (firtName property index)
|
|
$letter_seq->insert('Smith', NULL, 1);
|
|
|
|
// Append a lastName value to the sequence
|
|
// value: 'Jones'
|
|
// sequence index: NULL (append)
|
|
// propertyIdentifier: 'lastName' (lastName property name)
|
|
$letter_seq->insert('Jones', NULL, 'lastName');
|
|
|
|
// Append unstructured text
|
|
// value: 'Cancel Subscription.'
|
|
// sequence index: absent (append)
|
|
// propertyIdentifier: absent (unstructured text)
|
|
$letter_seq->insert('Cancel Subscription.');
|
|
|
|
// Insert new unstructured text. Subsequent sequence values
|
|
// are shifted up.
|
|
// value: 'Care of:'
|
|
// sequence index: 1 (insert as second element)
|
|
// propertyIdentifier: absent (unstructured text)
|
|
$letter_seq->insert('Care of:', 1);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
|
|
<para>
|
|
<example>
|
|
<title>Removing from a sequence</title>
|
|
<para>
|
|
We can use the <function>isset</function> and
|
|
<function>unset</function> functions to test and remove items
|
|
from the sequence (Note: <function>unset</function> currently
|
|
leaves the values in the data object, but this behaviour is
|
|
likely to change to also remove the data from the data object).
|
|
A sequence behaves like a contiguous list; therefore, removing
|
|
items from the middle will shift entries at higher indices
|
|
down. The following example tests to see if the first sequence
|
|
element is set and unsets it if is.
|
|
</para>
|
|
<programlisting role="php" id="sdo.examples.seqremove">
|
|
<![CDATA[
|
|
<?php
|
|
if (isset($letter_seq[0])) {
|
|
unset($letter_seq[0]);
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
<section id="sdo.sample.reflection">
|
|
<title>Reflecting on Service Data Objects</title>
|
|
<para>
|
|
SDOs have a knowledge of the structure they have been created to
|
|
represent (the model). For example, a Company SDO created using
|
|
<link linkend="sdo.examples">the Company XML schema</link> above
|
|
would only be permitted to contain DepartmentType data objects
|
|
which in turn could only contain EmployeeType data objects.
|
|
</para>
|
|
<para>
|
|
Sometimes it is useful to be able to access this model information at
|
|
runtime. For example, this could be used to automatically generate
|
|
a user interface for populating a data object. The model information
|
|
is accessed using reflection.
|
|
</para>
|
|
|
|
<para>
|
|
<example>
|
|
<title>Reflecting on a Data Object</title>
|
|
<para>
|
|
The following example shows how we can reflect on an empty Employee
|
|
data object.
|
|
</para>
|
|
<programlisting role="php" id="sdo.examples.reflection">
|
|
<![CDATA[
|
|
<?php
|
|
// Create the employee data object (e.g. from an XML Data Access Service)
|
|
$employee = ...;
|
|
$reflection = new SDO_Model_ReflectionDataObject($employee);
|
|
print($reflection);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
|
|
<screen>
|
|
<![CDATA[
|
|
object(SDO_Model_ReflectionDataObject)#4 { - ROOT OBJECT - Type {
|
|
companyNS:EmployeeType[3] { commonj.sdo:String $name;
|
|
commonj.sdo:String $SN; commonj.sdo:Boolean $manager; } }
|
|
]]>
|
|
</screen>
|
|
<para>
|
|
Using print on the SDO_Model_ReflectionDataObject writes out the data
|
|
object's model. We can see from the output how the type
|
|
companyNS:EmployeeType has three properties and we can see the names
|
|
of the properties along with their types. Note, the primitive types
|
|
are listed as SDO types (e.g. commonj.sdo namespace, String type).
|
|
It is worth noting that this is the SDO model and when these are
|
|
surfaced to an application they can be treated as the PHP equivalent
|
|
types (e.g. string and boolean).
|
|
</para>
|
|
</example>
|
|
</para>
|
|
|
|
<para>
|
|
<example>
|
|
<title>Accessing the type information</title>
|
|
<para>
|
|
We can query the type information of a data object using reflection.
|
|
The following example checks the type corresponds to a data object
|
|
rather than a primitive and then iterates through the properties of
|
|
the type, writing out the name of each property ($type and $property
|
|
are SDO_Model_Type and SDO_Model_Property objects, respectively).
|
|
</para>
|
|
<programlisting role="php" id="sdo.examples.reflection.type">
|
|
<![CDATA[
|
|
<?php
|
|
// Create the employee data object (e.g. from an XML Data Access Service)
|
|
$employee = ...;
|
|
$reflection = new SDO_Model_ReflectionDataObject($employee);
|
|
$type = $reflection->getType();
|
|
if (! $type->isDataType()) {
|
|
foreach ($type->getProperties() as $property) {
|
|
print $property->getName() . "\n";
|
|
}
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
name
|
|
SN
|
|
manager
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
|
|
|
|
<!-- class definition section -->
|
|
<section id='sdo.classes'>
|
|
&reftitle.classes;
|
|
<para>
|
|
SDO consists of three sets of interfaces. The first set covers those
|
|
interfaces for use by typical SDO applications. These are identified
|
|
by the package prefix 'SDO_'. The second set is those used to reflect
|
|
on, and work with, the model of a data object. These are identified
|
|
by the package prefix 'SDO_Model_'. Finally, the third set are those
|
|
use by Data Access Service implementations and are identified by the
|
|
package prefix 'SDO_DAS_'. The majority of SDO users will not need to
|
|
use or understand the 'SDO_Model_' and 'SDO_DAS_' interfaces.
|
|
</para>
|
|
|
|
<section id='sdo.class.sdo-apis'>
|
|
<title>SDO Application Programmer Interface</title>
|
|
|
|
<section id='sdo.class.sdo-dataobject'>
|
|
<title>
|
|
<classname>SDO_DataObject</classname>
|
|
</title>
|
|
<para>
|
|
The main interface through which data objects are manipulated. In
|
|
addition to the methods below, SDO_DataObject extends the
|
|
ArrayAccess, SDO_PropertyAccess (defines <function>__get</function> /
|
|
<function>__set</function> methods for property access overloading),
|
|
Iterator, and Countable interfaces.
|
|
</para>
|
|
<section id='sdo.class.SDO_DataObject.methods'> &reftitle.methods;
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-DataObject-getSequence'>getSequence</link>
|
|
- get the sequence for the data object
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-DataObject-createDataObject'>createDataObject</link>
|
|
- create a child data object
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-DataObject-clear'>clear</link>
|
|
- unset the properties of a data object
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-DataObject-getContainer'>getContainer</link>
|
|
- get the container (also known as 'parent') of this data object
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-DataObject-getTypeName'>getTypeName</link>
|
|
- get the name of the type for this data object
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-DataObject-getTypeNamespaceURI'>getTypeNamespaceURI</link>
|
|
- get the namespace URI of the type for this data object
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
</section>
|
|
|
|
<section id='sdo.class.sdo-sequence'>
|
|
<title>
|
|
<classname>SDO_Sequence</classname>
|
|
</title>
|
|
<para>
|
|
The interface through which sequenced data objects can be accessed
|
|
to preserve ordering across a data object's properties and
|
|
to allow unstructured text.
|
|
SDO_Sequence preserves contiguous indices and therefore inserting
|
|
or removing elements may shift other elements up or
|
|
down. In addition to the methods below, SDO_Sequence extends the
|
|
ArrayAccess, Iterator and Countable interface.
|
|
</para>
|
|
<section id='sdo.class.SDO_Sequence.methods'>
|
|
&reftitle.methods;
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-Sequence-getProperty'>getProperty</link>
|
|
- get the property for a given sequence index
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-Sequence-move'>move</link>
|
|
- move an element from one property index to another
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-Sequence-insert'>insert</link>
|
|
- insert a new value into the sequence
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
</section>
|
|
|
|
<section id='sdo.class.sdo-list'>
|
|
<title>
|
|
<classname>SDO_List</classname>
|
|
</title>
|
|
<para>
|
|
The interface through which many-valued properties are manipulated.
|
|
In addition to the method defined below, SDO_List extends ArrayAccess,
|
|
Iterator and Countable. SDO_List preserves contiguous indices and
|
|
therefore inserting or removing elements may shift other elements
|
|
up or down.
|
|
</para>
|
|
<section id='sdo.class.SDO-List.methods'>
|
|
&reftitle.methods;
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-List-insert'>insert</link>
|
|
- insert a new value into the list
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
</section>
|
|
|
|
<section id='sdo.class.sdo-datafactory'>
|
|
<title>
|
|
<classname>SDO_DataFactory</classname>
|
|
</title>
|
|
<para>
|
|
The interface through which data objects can be created.
|
|
A Data Access Service is responsible for populating the model
|
|
(i.e. configuring the data factory with the type and structure
|
|
information for the data objects it can create.)
|
|
for the factory and can then optionally return an instance of,
|
|
or implement, the SDO_DataFactory interface.
|
|
</para>
|
|
<section id='sdo.class.SDO-DataFactory.methods'>
|
|
&reftitle.methods;
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-DataFactory-create'>create</link>
|
|
- create a new data object
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
</section>
|
|
|
|
<section id='sdo.class.sdo-exception'>
|
|
<title>
|
|
<classname>SDO_Exception</classname>
|
|
</title>
|
|
<para>
|
|
An SDO_Exception is thrown when the caller's request cannot be completed.
|
|
The subclasses of SDO_Exception are:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>SDO_PropertyNotSetException -
|
|
the property specified exists but has not been set or does not have a
|
|
default value
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>SDO_PropertyNotFoundException -
|
|
the property specified is not part of the data object's type
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>SDO_TypeNotFoundException -
|
|
the specified namespace URI or type name is unknown
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>SDO_InvalidConversionException -
|
|
conversion between the types of the assignment is not possible
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>SDO_IndexOutOfBoundsException -
|
|
the numeric index into a data object, sequence or list is not in the
|
|
valid range
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>SDO_UnsupportedOperationException -
|
|
the request cannot be completed because it is not allowed,
|
|
for example an attempt to set a read-only property.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<section id='sdo.class.SDO_Exception.methods'> &reftitle.methods;
|
|
<para>One method is added to those inherited from the built in
|
|
<link linkend='language.exceptions.extending'>Exception</link> class:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-Exception-getCause'>getCause</link>
|
|
- get the cause of this SDO_Exception
|
|
</para>
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
</section>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='sdo.class.sdo-model-apis'>
|
|
<title>SDO Reflection Application Programmer Interfaces</title>
|
|
|
|
<section id='sdo.class.sdo-reflectiondataobject'>
|
|
<title>
|
|
<classname>SDO_Model_ReflectionDataObject</classname>
|
|
</title>
|
|
<para>
|
|
The main interface used to reflect on a data object instance
|
|
to obtain its model type and property information.
|
|
It is designed to follow the reflection pattern introduced in PHP 5.
|
|
</para>
|
|
<section id='sdo.class.SDO_Model_ReflectionDataObject.constructor'>
|
|
&reftitle.constructor;
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-Model-ReflectionDataObject-construct'>__construct</link>
|
|
- construct a new SDO_Model_ReflectionDataObject.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<section id='sdo.class.SDO_Model_ReflectionDataObject.methods'>
|
|
&reftitle.methods;
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-Model-ReflectionDataObject-export'>export</link>
|
|
- get a string describing the data object.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-Model-ReflectionDataObject-getType'>getType</link>
|
|
- get the SDO_Model_Type for the data object.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend=
|
|
'function.SDO-Model-ReflectionDataObject-getInstanceProperties'>getInstanceProperties</link>
|
|
- get the instance properties of the data object.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend=
|
|
'function.SDO-Model-ReflectionDataObject-getContainmentProperty'>getContainmentProperty</link>
|
|
- get the property which defines the containment relationship to the data object.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
</section>
|
|
|
|
<section id='sdo.class.sdo-type'>
|
|
<title>
|
|
<classname>SDO_Model_Type</classname>
|
|
</title>
|
|
<para>
|
|
The interface through which a data object's type information can be
|
|
retrieved. This interface can be used to find out the type name and
|
|
namespace URI of the type, whether the type allow open content, and so
|
|
on.
|
|
</para>
|
|
<section id='sdo.class.SDO_Model_Type.methods'> &reftitle.methods;
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-Model-Type-getName'>getName</link>
|
|
- get the name of the type.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-Model-Type-getNamespaceURI'>getNamespaceURI</link>
|
|
- get the namespace URI of the type.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-Model-Type-isInstance'>isInstance</link>
|
|
- test for a data object being an instance of the type.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-Model-Type-getProperties'>getProperties</link>
|
|
- get the properties of the type.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-Model-Type-getProperty'>getProperty</link>
|
|
- get a property of the type.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-Model-Type-isDataType'>isDataType</link>
|
|
- test to see if this type is a primitive scalar type.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-Model-Type-isSequencedType'>isSequencedType</link>
|
|
- test to see if this is a sequenced type.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-Model-Type-isOpenType'>isOpenType</link>
|
|
- test to see if this is an open type.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-Model-Type-isAbstractType'>isAbstractType</link>
|
|
- test to see if this is an abstract type.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-Model-Type-getBaseType'>getBaseType</link>
|
|
- get the base type of this type (if one exists).
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
</section>
|
|
|
|
<section id='sdo.class.sdo-property'>
|
|
<title>
|
|
<classname>SDO_Model_Property</classname>
|
|
</title>
|
|
<para>
|
|
The interface through which a data object's property information can
|
|
be retrieved. This interface can be used to find out the type of a
|
|
property, whether a property has a default value, whether the
|
|
property is contained or reference by its parent, its cardinality,
|
|
and so on.
|
|
</para>
|
|
<section id='sdo.class.SDO_Model_Property.methods'> &reftitle.methods;
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-Model-Property-getName'>getName</link>
|
|
- get the name of the property.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-Model-Property-getType'>getType</link>
|
|
- get the type of the property.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-Model-Property-isMany'>isMany</link>
|
|
- test to see if the property is many-valued.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-Model-Property-isContainment'>isContainment</link>
|
|
- test to see if the property describes a containment relationship.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-Model-Property-getContainingType'>getContainingType</link>
|
|
- get the type which contains this property.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-Model-Property-getDefault'>getDefault</link>
|
|
- get the default value for a property.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
</section>
|
|
|
|
|
|
|
|
</section>
|
|
|
|
<section id='sdo.class.sdo-das-spis'>
|
|
<title>
|
|
SDO Data Access Service Developer Interfaces
|
|
</title>
|
|
|
|
<section id='sdo.class.sdodas-dataobject'>
|
|
<title>
|
|
<classname>SDO_DAS_DataObject</classname>
|
|
</title>
|
|
<para>
|
|
The interface through which a Data Access Service can access
|
|
a data object's
|
|
<link linkend='sdo.class.sdodas-changesummary'>SDO_DAS_ChangeSummary</link>.
|
|
The change summary is used by the Data Access Service to check for
|
|
conflicts when applying changes back to a data source.
|
|
</para>
|
|
<section id='sdo.class.SDO_DAS_DataObject.methods'> &reftitle.methods;
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-DAS-DataObject-getChangeSummary'>getChangeSummary</link>
|
|
- get the change summary for a data object
|
|
</para>
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
</section>
|
|
</section>
|
|
|
|
<section id='sdo.class.sdodas-changesummary'>
|
|
<title>
|
|
<classname>SDO_DAS_ChangeSummary</classname>
|
|
</title>
|
|
<para>
|
|
The interface through which the change history of a data
|
|
object is accessed. The change summary holds information for any
|
|
modifications on a data object which occurred since logging
|
|
was activated. In the case of deletions and modifications, the old
|
|
values are also held in the change summary.
|
|
</para>
|
|
<para>
|
|
If logging is no longer active
|
|
then the change summary only holds changes made up to the point when
|
|
logging was deactivated.
|
|
Reactivating logging clears the change summary.
|
|
This is useful when a set of changes have been written out by a
|
|
DAS and the data object is to be reused.
|
|
</para>
|
|
<section id='sdo.class.SDO_DAS_ChangeSummary.methods'>
|
|
&reftitle.methods;
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-DAS-ChangeSummary-beginLogging'>beginLogging</link>
|
|
- begin logging changes made to a data object
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-DAS-ChangeSummary-endLogging'>endLogging</link>
|
|
- end logging changes made to a data object
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-DAS-ChangeSummary-isLogging'>isLogging</link>
|
|
- test to see if change logging is on
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-DAS-ChangeSummary-getChangedDataObjects'>getChangedDataObjects</link>
|
|
- get a list of the data objects which have been changed
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-DAS-ChangeSummary-getChangeType'>getChangeType</link>
|
|
- get the type of change which has been made to a data object
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-DAS-ChangeSummary-getOldValues'>getOldValues</link>
|
|
- get a list of old values for a data object
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-DAS-ChangeSummary-getOldContainer'>getOldContainer</link>
|
|
- get the old container data object for a deleted data object
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
</section>
|
|
|
|
<section id='sdo.class.sdodas-setting'>
|
|
<title>
|
|
<classname>SDO_DAS_Setting</classname>
|
|
</title>
|
|
<para>
|
|
The interface through which the old value for a property is
|
|
accessed. A list of settings is returned by the change summary method
|
|
<link linkend='function.SDO-DAS-ChangeSummary-getOldValues'>
|
|
<function>getOldValues</function>
|
|
</link>.
|
|
</para>
|
|
<section id='sdo.class.SDO_DAS_Setting.methods'>
|
|
&reftitle.methods;
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-DAS-Setting-getPropertyIndex'>getPropertyIndex</link>
|
|
- get the property index for the changed property
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-DAS-Setting-getPropertyName'>getPropertyName</link>
|
|
- get the property name for the changed property
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-DAS-Setting-getValue'>getValue</link>
|
|
- get the old value for the changed property
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-DAS-Setting-getListIndex'>getListIndex</link>
|
|
- get the list index for the old value if it was part of a
|
|
many-valued property
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-DAS-Setting-isSet'>isSet</link>
|
|
- test to see if the property was set prior to being modified
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
</section>
|
|
|
|
<section id='sdo.class.sdodas-datafactory'>
|
|
<title>
|
|
<classname>SDO_DAS_DataFactory</classname>
|
|
</title>
|
|
<para>
|
|
The interface for constructing the model for an SDO_DataObject.
|
|
The SDO_DAS_DataFactory is an abstract class providing a static
|
|
method which returns a concrete data factory implementation.
|
|
The implementation is used by Data Access Services to create an
|
|
SDO model from their model.
|
|
For example, a Relational Data Access Service might create and populate
|
|
an SDO_DAS_DataFactory model based on a schema for a relational
|
|
database.
|
|
</para>
|
|
<section id='sdo.class.SDO_DAS_DataFactory.methods'>
|
|
&reftitle.methods;
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-DAS-DataFactory-getDataFactory'>getDataFactory</link>
|
|
- static methods for getting a concrete data factory instance
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-DAS-DataFactory-addType'>addType</link>
|
|
- add a new type to the SDO model
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<link linkend='function.SDO-DAS-DataFactory-addPropertyToType'>addPropertyToType</link>
|
|
- add a new property to a type definition in the SDO model
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
|
|
&reference.sdo.constants;
|
|
|
|
</partintro>
|
|
|
|
&reference.sdo.functions;
|
|
|
|
</reference>
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
indent-tabs-mode:nil
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"../../../manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|