diff --git a/reference/sdo/book.xml b/reference/sdo/book.xml
new file mode 100644
index 0000000000..accf980317
--- /dev/null
+++ b/reference/sdo/book.xml
@@ -0,0 +1,101 @@
+
+
+
+
+
+
+ SDO
+
+
+
+ &reftitle.intro;
+
+ 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.
+
+
+ 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.
+
+
+ See the
+ list of Data Access Services
+ 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 SDO Data
+ Access Services Interface for more details).
+
+
+ This extension is derived from concepts taken from the
+ Service Data Objects specification.
+ It includes a version of the
+ Apache Tuscany SDO for C++ project.
+
+
+ The Structure of a Service Data Object
+
+ 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.
+
+ 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.
+
+
+ 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").
+
+ 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.
+
+ 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.
+
+
+
+
+
+ &reference.sdo.setup;
+ &reference.sdo.constants;
+ &reference.sdo.limitations;
+ &reference.sdo.examples;
+ &reference.sdo.reference;
+
+
+
+
+
diff --git a/reference/sdo/constants.xml b/reference/sdo/constants.xml
index f9136b2194..71ae3514b9 100644
--- a/reference/sdo/constants.xml
+++ b/reference/sdo/constants.xml
@@ -1,7 +1,7 @@
-
+
-
+
&reftitle.constants;
&extension.constants;
@@ -50,7 +50,7 @@
-
+
+
+
+ &reftitle.examples;
+
+ Basic Usage
+
+ The examples below assume an SDO created with the schema
+ and instance information shown below, using the XML Data Access Service.
+
+
+ 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'.
+
+
+
+
+
+
+
+
+
+
+
+]]>
+
+
+ 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'.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+]]>
+
+
+ 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
+ sdoxml:propertyType attribute specifying the type of the
+ non-containment reference.
+
+
+
+
+ Setting and Getting Property Values
+ The following examples assume
+ $company is the root of a tree of data objects created from the
+ schema and instance document shown above.
+
+
+
+ Access via property name
+
+ Data object properties can be accessed using the object property
+ access syntax. The following sets the company name to 'Acme'.
+
+
+name = 'Acme';
+?>
+]]>
+
+
+
+
+
+
+ Access via property name as array index
+ 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.
+
+
+
+]]>
+
+
+
+
+
+
+ Data Object iteration
+
+ We can iterate over the properties of a data object using foreach.
+ The following iterates over the properties of the employee of the month.
+
+
+employeeOfTheMonth;
+ foreach ($eotm as $name => $value) {
+ echo "$name: $value\n";
+ }
+?>
+]]>
+
+
+ which will output:
+
+
+
+
+
+ The 'manager' property is not output, because it has not been set.
+
+
+
+
+
+
+ Access many-valued property by name
+ Many-valued data object properties can also be accessed using the object
+ property name syntax. The following gets the list of departments.
+
+
+departments;
+?>
+]]>
+
+
+
+
+
+
+ Many-valued element access
+
+ We can access individual elements of many-valued properties using array
+ syntax. The following accesses the first department in the company.
+
+
+departments[0];
+?>
+]]>
+
+
+
+
+
+
+ Many-valued property iteration
+
+ Many-valued properties can also be iterated over using
+ foreach. The following iterates over the company's departments.
+
+
+departments as $department) {
+ // ...
+ }
+?>
+]]>
+
+
+ Each iteration will assign the next department in the
+ list to the variable $department.
+
+
+
+
+
+
+ Chained property access
+ We can chain property references on a single line.
+ The following sets and gets the name of the first department.
+
+
+departments[0]->name = 'Emerging Technologies';
+ $dept_name = $company->departments[0]->name;
+?>
+]]>
+
+ Using the associative array syntax, this is equivalent to
+
+
+]]>
+
+ In either case, the dept_name variable is set to 'Emerging Technologies'.
+
+
+
+
+
+
+ XPath navigation
+ The associative array index can be an XPath-like expression. Valid
+ expressions are defined by an augmented sub-set of XPath.
+
+
+ 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:
+
+
+
+]]>
+
+ and the SDO XPath extension syntax is:
+
+
+]]>
+
+
+ Both these examples get the second employee from the first department.
+
+
+
+
+
+
+ XPath querying
+
+ 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.
+
+
+
+]]>
+
+
+
+
+
+
+ Creating child data objects
+
+ 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.
+
+
+createDataObject('employees');
+ $new_hire->name = 'John Johnson';
+ $new_hire->SN = 'E0005';
+ $new_hire->manager = false;
+?>
+]]>
+
+
+
+
+
+
+ Unset a primitive property
+
+ We can use the isset and
+ unset functions to test and remove items
+ from the data object.
+
+
+ The following clears the name of the first department.
+
+
+departments[0]->name);
+?>
+]]>
+
+
+
+
+
+
+ Unset a data object
+
+ unset can also be used to remove a data object from the tree.
+ The following example shows John Jones leaving the company.
+
+
+departments[0]->employees[0]);
+?>
+]]>
+
+
+
+
+
+
+ Unset a referenced data object
+
+ 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.
+
+
+employeeOfTheMonth)) {
+ unset($company->employeeOfTheMonth);
+ }
+?>
+]]>
+
+
+
+
+
+
+ Access via property index
+ 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
+ Access via property name
+
+
+
+]]>
+
+ 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.
+
+
+
+
+
+
+
+ Working with Sequenced Data Objects
+
+ 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 (
+ ]]>). This can occur for example when
+ the schema defines maxOccurs>1 on a
+ element which is a complexType with a choice order indicator.
+
+
+ The examples below assume an SDO created with the following schema
+ and instance information, using the XML Data Access Service.
+
+
+ The schema below describes the format of a letter. The letter can
+ optionally contain three properties; date, firstName, and lastName.
+ The schema states mixed="true" which means that
+ unstructured text can be interspersed between the three properties.
+
+
+
+
+
+
+
+
+
+
+
+
+
+]]>
+
+
+
+
+ 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.
+
+
+
+
+ March 1, 2005
+ Mutual of Omaha
+ Wild Kingdom, USA
+ Dear
+ Casy
+ Crocodile
+ Please buy more shark repellent.
+ Your premium is past due.
+
+]]>
+
+
+
+ When loaded, the letter data object will have the sequence and
+ property indices shown in the table below:
+
+
+
+
+ Sequence Index
+ Property Index:Name
+ Value
+
+
+
+
+ 0
+ 0:date
+ March 1, 2005
+
+
+ 1
+ -
+ Mutual of Omaha
+
+
+ 2
+ -
+ Wild Kingdom, USA
+
+
+ 3
+ -
+ Dear
+
+
+ 4
+ 1:firstName
+ Casy
+
+
+ 5
+ 2:lastName
+ Crocodile
+
+
+ 6
+ -
+ Please buy more shark repellent.
+
+
+ 7
+ -
+ Your premium is past due.
+
+
+
+
+
+
+
+ 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
+ $letter.
+
+ Getting the SDO_Sequence interface
+
+ We obtain a data object's sequence using the
+ getSequence
+ method. The follow gets the
+ sequence for the letter data object.
+
+
+getSequence();
+?>
+]]>
+
+
+
+
+ All subsequent examples assume that the
+ $letter_seq
+ variable has been assigned the sequence for the letter data object.
+
+
+
+
+ Get/set sequence values
+
+ 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.').
+
+
+
+]]>
+
+
+
+
+
+
+ Sequence iteration
+
+ We can iterate through the individual sequence values using foreach.
+ The following runs through the individual values in sequence order.
+
+
+getSequence() as $value) {
+ // ...
+}
+?>
+]]>
+
+
+
+
+
+
+ Sequence versus Data Object
+
+ 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.
+
+
+
+]]>
+
+
+
+
+
+
+ Adding to a sequence
+
+ We can add new values to a sequence using the
+ SDO_Sequence::insert
+ method. The following examples assume that the 'firstName' and
+ 'lastName' properties are initially unset.
+
+
+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);
+?>
+]]>
+
+
+
+
+
+
+ Removing from a sequence
+
+ We can use the isset and
+ unset functions to test and remove items
+ from the sequence (Note: unset 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.
+
+
+
+]]>
+
+
+
+
+
+
+
+
+ Reflecting on Service Data Objects
+
+ SDOs have a knowledge of the structure they have been created to
+ represent (the model). For example, a Company SDO created using
+ the Company XML schema above
+ would only be permitted to contain DepartmentType data objects
+ which in turn could only contain EmployeeType data objects.
+
+
+ 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.
+
+
+
+
+ Reflecting on a Data Object
+
+ The following example shows how we can reflect on an empty Employee
+ data object.
+
+
+
+]]>
+
+ &example.outputs;
+
+
+
+
+
+ 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).
+
+
+
+
+
+
+ Accessing the type information
+
+ 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).
+
+
+getType();
+ if (! $type->isDataType()) {
+ foreach ($type->getProperties() as $property) {
+ print $property->getName() . "\n";
+ }
+ }
+?>
+]]>
+
+ &example.outputs;
+
+
+
+
+
+
+
+
+
+
+
diff --git a/reference/sdo/limitations.xml b/reference/sdo/limitations.xml
new file mode 100644
index 0000000000..a2a69fb25a
--- /dev/null
+++ b/reference/sdo/limitations.xml
@@ -0,0 +1,73 @@
+
+
+
+
+ Limitations
+
+ Implementation Limitations
+
+ The following are limitations in the current SDO implementation:
+
+
+
+ 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 Unicode Functions.
+
+
+
+
+ SDO Limitations
+
+ 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.
+
+
+
+ Bi-directional relationships.
+
+
+
+
+ Type and property alias names.
+
+
+
+
+ Read-only properties.
+
+
+
+
+ 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 CopyHelper::copy()
+ is provided by applying the PHP
+ clone keyword to a data object.
+
+
+
+
+
diff --git a/reference/sdo/reference.xml b/reference/sdo/reference.xml
index 0d63530ccc..146437e979 100644
--- a/reference/sdo/reference.xml
+++ b/reference/sdo/reference.xml
@@ -1,247 +1,10 @@
-
-
-
+
- SDO Functions
- SDO
+ SDO &Functions;
-
- &reftitle.intro;
-
- 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.
-
-
- 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.
-
-
- See the
- list of Data Access Services
- 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 SDO Data
- Access Services Interface for more details).
-
-
- This extension is derived from concepts taken from the
- Service Data Objects specification.
- It includes a version of the
- Apache Tuscany SDO for C++ project.
-
-
-
- The Structure of a Service Data Object
-
- 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.
-
- 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.
-
-
- 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").
-
- 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.
-
- 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.
-
-
-
-
-
- &reftitle.required;
-
- The SDO extension requires PHP 5.1.0 or higher. It also requires the
- libxml2 library. Normally libxml2 will already be installed, but if
- not, it can be downloaded from
-
- &url.libxml;
-
- .
-
-
-
-
- &reftitle.install;
-
-
- Earlier versions of the SDO extension required a separate shared
- library for the XML DAS. This is now obsolete and any references to
- php_sdo_das_xml.dll
- or
- sdo_das_xml.so
- should be removed from your
- &php.ini;
- .
-
-
-
- Unix systems
-
-
- The three SDO components - the SDO core, the XML DAS and the
- Relational DAS - are packaged together with Service Component
- Architecture (SCA) into one PECL project, SCA_SDO, so you can
- download SCA and all three parts of SDO with the command:
-
-
-
-
-
- This command will build the SDO shared library as well as
- installing the PHP files that make up SCA and the SDO
- Relational DAS.
-
-
- If you want to use the latest beta version, then instead run:
-
-
-
-
-
-
-
- The
- pecl
- command automatically installs the SDO module into your PHP
- extensions directory. To enable the SDO extension you must add the
- following line to
- &php.ini;
- :
-
-
-
-
-
- For more information about building PECL packages, consult the
- PECL installation
- section of the manual.
-
-
-
-
-
- Windows
-
-
- The latest SDO DLL can be downloaded from
- php_sdo.dll
- .
-
-
- Note that currently the
- pecl4win
- site does not provide this binary at the current release level;
- you can only download the latest level.
-
-
-
-
- The
- pecl
- command automatically installs the SDO module into your PHP
- extensions directory. To enable the SDO extension you must add the
- following line to
- &php.ini;
- :
-
-
-
-
-
-
-
- The Relational DAS can be downloaded and installed with the
- command:
-
-
-
-
-
- The Relational DAS is written in PHP. You may need to update your
- include_path
- in
- &php.ini;
- to point to the directory that contains
- sdo/DAS/Relational
- .
-
-
-
-
-
- Building SDO on Linux
-
- 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.
-
-
-
- Change to the main extension directory:
- cd < wherever your sdo code is >
-
-
-
-
- Run
- phpize
- , which will set up the environment to compile SDO.
-
-
-
-
- Next, run
- ./configure; make; make install
- . Please note, you may need to login as root to install the
- extension.
-
-
-
-
- Make sure that the module is loaded by PHP, by adding
- extension=sdo.so
- to your
- &php.ini;
- file.
-
-
-
-
-
Data Access Services
@@ -280,843 +43,7 @@ pecl install -B sdo
-
- Limitations
-
- Implementation Limitations
-
- The following are limitations in the current SDO implementation:
-
-
-
- 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 Unicode Functions.
-
-
-
-
- SDO Limitations
-
- 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.
-
-
-
- Bi-directional relationships.
-
-
-
-
- Type and property alias names.
-
-
-
-
- Read-only properties.
-
-
-
-
- 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 CopyHelper::copy()
- is provided by applying the PHP
- clone keyword to a data object.
-
-
-
-
-
-
- &reftitle.examples;
-
- The examples below assume an SDO created with the schema
- and instance information shown below, using the XML Data Access Service.
-
-
- 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'.
-
-
-
-
-
-
-
-
-
-
-
-]]>
-
-
- 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'.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-]]>
-
-
- 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
- sdoxml:propertyType attribute specifying the type of the
- non-containment reference.
-
-
-
-
- Setting and Getting Property Values
- The following examples assume
- $company is the root of a tree of data objects created from the
- schema and instance document shown above.
-
-
-
- Access via property name
-
- Data object properties can be accessed using the object property
- access syntax. The following sets the company name to 'Acme'.
-
-
-name = 'Acme';
-?>
-]]>
-
-
-
-
-
-
- Access via property name as array index
- 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.
-
-
-
-]]>
-
-
-
-
-
-
- Data Object iteration
-
- We can iterate over the properties of a data object using foreach.
- The following iterates over the properties of the employee of the month.
-
-
-employeeOfTheMonth;
- foreach ($eotm as $name => $value) {
- echo "$name: $value\n";
- }
-?>
-]]>
-
-
- which will output:
-
-
-
-
-
- The 'manager' property is not output, because it has not been set.
-
-
-
-
-
-
- Access many-valued property by name
- Many-valued data object properties can also be accessed using the object
- property name syntax. The following gets the list of departments.
-
-
-departments;
-?>
-]]>
-
-
-
-
-
-
- Many-valued element access
-
- We can access individual elements of many-valued properties using array
- syntax. The following accesses the first department in the company.
-
-
-departments[0];
-?>
-]]>
-
-
-
-
-
-
- Many-valued property iteration
-
- Many-valued properties can also be iterated over using
- foreach. The following iterates over the company's departments.
-
-
-departments as $department) {
- // ...
- }
-?>
-]]>
-
-
- Each iteration will assign the next department in the
- list to the variable $department.
-
-
-
-
-
-
- Chained property access
- We can chain property references on a single line.
- The following sets and gets the name of the first department.
-
-
-departments[0]->name = 'Emerging Technologies';
- $dept_name = $company->departments[0]->name;
-?>
-]]>
-
- Using the associative array syntax, this is equivalent to
-
-
-]]>
-
- In either case, the dept_name variable is set to 'Emerging Technologies'.
-
-
-
-
-
-
- XPath navigation
- The associative array index can be an XPath-like expression. Valid
- expressions are defined by an augmented sub-set of XPath.
-
-
- 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:
-
-
-
-]]>
-
- and the SDO XPath extension syntax is:
-
-
-]]>
-
-
- Both these examples get the second employee from the first department.
-
-
-
-
-
-
- XPath querying
-
- 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.
-
-
-
-]]>
-
-
-
-
-
-
- Creating child data objects
-
- 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.
-
-
-createDataObject('employees');
- $new_hire->name = 'John Johnson';
- $new_hire->SN = 'E0005';
- $new_hire->manager = false;
-?>
-]]>
-
-
-
-
-
-
- Unset a primitive property
-
- We can use the isset and
- unset functions to test and remove items
- from the data object.
-
-
- The following clears the name of the first department.
-
-
-departments[0]->name);
-?>
-]]>
-
-
-
-
-
-
- Unset a data object
-
- unset can also be used to remove a data object from the tree.
- The following example shows John Jones leaving the company.
-
-
-departments[0]->employees[0]);
-?>
-]]>
-
-
-
-
-
-
- Unset a referenced data object
-
- 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.
-
-
-employeeOfTheMonth)) {
- unset($company->employeeOfTheMonth);
- }
-?>
-]]>
-
-
-
-
-
-
- Access via property index
- 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
- Access via property name
-
-
-
-]]>
-
- 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.
-
-
-
-
-
-
-
- Working with Sequenced Data Objects
-
- 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 (
- ]]>). This can occur for example when
- the schema defines maxOccurs>1 on a
- element which is a complexType with a choice order indicator.
-
-
- The examples below assume an SDO created with the following schema
- and instance information, using the XML Data Access Service.
-
-
- The schema below describes the format of a letter. The letter can
- optionally contain three properties; date, firstName, and lastName.
- The schema states mixed="true" which means that
- unstructured text can be interspersed between the three properties.
-
-
-
-
-
-
-
-
-
-
-
-
-
- ]]>
-
-
-
-
- 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.
-
-
-
-
- March 1, 2005
- Mutual of Omaha
- Wild Kingdom, USA
- Dear
- Casy
- Crocodile
- Please buy more shark repellent.
- Your premium is past due.
-
- ]]>
-
-
-
- When loaded, the letter data object will have the sequence and
- property indices shown in the table below:
-
-
-
-
- Sequence Index
- Property Index:Name
- Value
-
-
-
-
- 0
- 0:date
- March 1, 2005
-
-
- 1
- -
- Mutual of Omaha
-
-
- 2
- -
- Wild Kingdom, USA
-
-
- 3
- -
- Dear
-
-
- 4
- 1:firstName
- Casy
-
-
- 5
- 2:lastName
- Crocodile
-
-
- 6
- -
- Please buy more shark repellent.
-
-
- 7
- -
- Your premium is past due.
-
-
-
-
-
-
-
- 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
- $letter.
-
- Getting the SDO_Sequence interface
-
- We obtain a data object's sequence using the
- getSequence
- method. The follow gets the
- sequence for the letter data object.
-
-
-getSequence();
-?>
-]]>
-
-
-
-
- All subsequent examples assume that the
- $letter_seq
- variable has been assigned the sequence for the letter data object.
-
-
-
-
- Get/set sequence values
-
- 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.').
-
-
-
-]]>
-
-
-
-
-
-
- Sequence iteration
-
- We can iterate through the individual sequence values using foreach.
- The following runs through the individual values in sequence order.
-
-
-getSequence() as $value) {
- // ...
- }
-?>
-]]>
-
-
-
-
-
-
- Sequence versus Data Object
-
- 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.
-
-
-
-]]>
-
-
-
-
-
-
- Adding to a sequence
-
- We can add new values to a sequence using the
- SDO_Sequence::insert
- method. The following examples assume that the 'firstName' and
- 'lastName' properties are initially unset.
-
-
-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);
-?>
-]]>
-
-
-
-
-
-
- Removing from a sequence
-
- We can use the isset and
- unset functions to test and remove items
- from the sequence (Note: unset 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.
-
-
-
-]]>
-
-
-
-
-
-
-
-
- Reflecting on Service Data Objects
-
- SDOs have a knowledge of the structure they have been created to
- represent (the model). For example, a Company SDO created using
- the Company XML schema above
- would only be permitted to contain DepartmentType data objects
- which in turn could only contain EmployeeType data objects.
-
-
- 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.
-
-
-
-
- Reflecting on a Data Object
-
- The following example shows how we can reflect on an empty Employee
- data object.
-
-
-
-]]>
-
- &example.outputs;
-
-
-
-
-
- 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).
-
-
-
-
-
-
- Accessing the type information
-
- 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).
-
-
-getType();
- if (! $type->isDataType()) {
- foreach ($type->getProperties() as $property) {
- print $property->getName() . "\n";
- }
- }
-?>
-]]>
-
- &example.outputs;
-
-
-
-
-
-
-
-
-
-
-
+
@@ -1718,8 +645,6 @@ manager
- &reference.sdo.constants;
-
&reference.sdo.entities.functions;
diff --git a/reference/sdo/setup.xml b/reference/sdo/setup.xml
new file mode 100644
index 0000000000..518325559a
--- /dev/null
+++ b/reference/sdo/setup.xml
@@ -0,0 +1,208 @@
+
+
+
+
+ &reftitle.setup;
+
+
+
+ &reftitle.required;
+
+ The SDO extension requires PHP 5.1.0 or higher. It also requires the
+ libxml2 library. Normally libxml2 will already be installed, but if
+ not, it can be downloaded from
+ &url.libxml;.
+
+
+
+
+
+
+ &reftitle.install;
+
+
+ Earlier versions of the SDO extension required a separate shared
+ library for the XML DAS. This is now obsolete and any references to
+ php_sdo_das_xml.dll
+ or
+ sdo_das_xml.so
+ should be removed from your &php.ini;.
+
+
+
+ Unix systems
+
+
+ The three SDO components - the SDO core, the XML DAS and the
+ Relational DAS - are packaged together with Service Component
+ Architecture (SCA) into one PECL project, SCA_SDO, so you can
+ download SCA and all three parts of SDO with the command:
+
+
+
+
+
+ This command will build the SDO shared library as well as
+ installing the PHP files that make up SCA and the SDO
+ Relational DAS.
+
+
+ If you want to use the latest beta version, then instead run:
+
+
+
+
+
+
+
+ The
+ pecl
+ command automatically installs the SDO module into your PHP
+ extensions directory. To enable the SDO extension you must add the
+ following line to
+ &php.ini;:
+
+
+
+
+
+ For more information about building PECL packages, consult the
+ PECL installation
+ section of the manual.
+
+
+
+
+
+ Windows
+
+
+ The latest SDO DLL can be downloaded from
+ php_sdo.dll
+ .
+
+
+ Note that currently the
+ pecl4win
+ site does not provide this binary at the current release level;
+ you can only download the latest level.
+
+
+
+
+ The
+ pecl
+ command automatically installs the SDO module into your PHP
+ extensions directory. To enable the SDO extension you must add the
+ following line to
+ &php.ini;:
+
+
+
+
+
+
+
+ The Relational DAS can be downloaded and installed with the
+ command:
+
+
+
+
+
+ The Relational DAS is written in PHP. You may need to update your
+ include_path
+ in
+ &php.ini;
+ to point to the directory that contains
+ sdo/DAS/Relational.
+
+
+
+
+
+ Building SDO on Linux
+
+ 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.
+
+
+
+ Change to the main extension directory:
+ cd < wherever your sdo code is >
+
+
+
+
+ Run
+ phpize
+ , which will set up the environment to compile SDO.
+
+
+
+
+ Next, run
+ ./configure; make; make install
+ . Please note, you may need to login as root to install the
+ extension.
+
+
+
+
+ Make sure that the module is loaded by PHP, by adding
+ extension=sdo.so
+ to your &php.ini; file.
+
+
+
+
+
+
+
+
+ &reftitle.runtime;
+ &no.config;
+
+
+
+
+
+ &reftitle.resources;
+ &no.resource;
+
+
+
+
+
+
+