diff --git a/reference/sdo/reference.xml b/reference/sdo/reference.xml index 11169aa301..f41deccec3 100644 --- a/reference/sdo/reference.xml +++ b/reference/sdo/reference.xml @@ -1,5 +1,5 @@ - + @@ -10,12 +10,7 @@
- &reftitle.intro; - - - &warn.experimental; - - + &reftitle.intro; Service Data Objects (SDOs) enable PHP applications to work with data from different sources (like a database query, an XML file, @@ -28,7 +23,7 @@ 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). + to a data source, typically the same one. See the @@ -40,10 +35,10 @@ Access Services Interface for more details). - This extension is derived from concepts taken from the - - Service Data Objects specification - + This extension is derived from concepts taken from the + Service Data Objects specification. + It includes a version of the + Apache Tuscany SDO 2.0 for C++ project.
@@ -54,16 +49,10 @@ 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. - Deleting a data object which has a containment relationship to another - data object will also delete the contained data object. For example, - deleting the Company data object will also delete 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. Deleting a data object - which has a non-containment reference to another data object does - not delete the referenced data object. + 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 @@ -71,187 +60,115 @@ 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 or higher. - - - SDO XML Data Access Service, - which is built as part of this extension, requires libxml2 - (Tested with libxml2 2.6.19) which can be downloaded from + 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 &url.libxml;.
&reftitle.install; - - There are several options, depending on whether you are installing on - Windows or Linux, and depending on whether you are installing a released - version (a .tgz file from the PECL site) or the latest from CVS. - The Relational DAS also needs special attention as it is written in - PHP. - - The instructions are likely to change as PHP 5.1 progresses in status from beta to - stable release. The instructions here were correct on 6th October 2005, when PHP - 5.1.0RC1 was the current release candidate for PHP, and 0.5.2 was the current beta - release of SDO. - - - The options are summarised in the following table: - - - - - latest/Release - Windows - Linux - - - - - - latest CVS - - - - - - The latest DLLs for the SDO core and the XML DAS can be - downloaded from - php_sdo and - php_sdo_das_xml - respectively. - - - - - Check out the Relational DAS from CVS to somewhere on the - PHP - include_path. - - - - - - - - - Check out the SDO core and the XML DAS from CVS - and build according to the instructions - below for building on Linux. - - - - - Check out the Relational DAS from CVS to somewhere on the - PHP - include_path. - - - - - - - - Release - - - - - - There is currently no way provided for building the release - version of the SDO core and XML DAS on a user's machine. - You will only be able to pick up the latest DLLs from the - snaps site (see previous row of this table). - - - - - The Relational DAS can be downloaded and installed with - the command: - - - - pear install -B <package name and level> - - - - Substitute the desired package name and level, for example - sdo-0.5.2, in the command above. - - - - - - - - - You can download and install all three SDO components - the - SDO core, the XML DAS and the Relational DAS - with the - command: - - - - pear install <package name and level> - - - - Substitute the desired package name and level, for example - sdo-0.5.2, in the command above. - - - This command will build the SDO and XML shared libraries as well - as installing the PHP files that make the Relational DAS. - - - - - - - - - - - Regardless of which platform or which level of the code you have installed - you will need add the two extension libraries to your &php.ini; file. - On Windows, add: - - - - On Linux, add: - + + Unix systems + + 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: + + + + This command will build the SDO and XML shared libraries as well as installing + the PHP files that make the Relational DAS. + + + If you want to use the latest beta version, then instead run: + + + + + + The + pear 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;: + - - You may also need to update your - extension_dir - in &php.ini; to point to the location of these libraries. - + + + For more information about building PECL packages, consult the + PECL installation section of the manual. + + + + + + Windows + + + The latest DLLs for the SDO core and the XML DAS can be + downloaded from + php_sdo.dll and + php_sdo_das_xml.dll respectively. + + + Note that currently the pecl4win site does not provide + these binaries at the current release level; you can only download the latest level. + + + + The + pear 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;: + + + + + + + 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. + + + - - 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. - Currently 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. + 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. @@ -267,8 +184,8 @@ extension=sdo_das_xml.so - Next, run ./configure; make; make install. Please - note, you may need to login as root to install the extension. + Next, run ./configure; make; make install. + Please note, you may need to login as root to install the extension. @@ -276,7 +193,7 @@ extension=sdo_das_xml.so Make sure that these modules are loaded by PHP, by adding extension=sdo.so and extension=sdo_das_xml.so to your - php.ini file in the same order. + &php.ini; file in the same order. @@ -301,8 +218,7 @@ extension=sdo_das_xml.so An XML Data Access Service supporting reading/writing - SDOs as XML documents or via a Web URL to supporting things like - RSS feeds. + SDOs as XML documents. @@ -311,7 +227,7 @@ extension=sdo_das_xml.so A PDO-based Data Access Service supporting reading/writing SDO - to relational data sources. + to relational databases. Implements an optimistic concurrency policy for updates. @@ -331,6 +247,9 @@ extension=sdo_das_xml.so 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. @@ -342,16 +261,6 @@ extension=sdo_das_xml.so It is not necessarily the case that these will all be added over time. Their inclusion will depend on community requirements. - - - Abstract types and type derivation. - - - - - Open types. - - Bi-directional relationships. @@ -368,13 +277,12 @@ extension=sdo_das_xml.so - - XMLHelper/XSDHelper (the XML DAS provides a lot of this functionality) - - - - - TypeHelper (the SDO_DAS_DataFactory provides this functionality) + + 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. @@ -387,14 +295,32 @@ extension=sdo_das_xml.so and instance information shown below, using the XML Data Access Service. - The schema describes a company data object. - The company contains department data objects, and - each department contains employee data objects. - Each data object has a number of primitive properties to describe things - like name, serial number, etc. - Finally, the company data object also has a non-containment reference - to one of the employee data objects to identify them as the - 'employeeOfTheMonth'. + 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'. @@ -409,15 +335,16 @@ extension=sdo_das_xml.so + maxOccurs="unbounded"/> + sdoxml:propertyType="company:EmployeeType"/> + + maxOccurs="unbounded"/> @@ -432,52 +359,32 @@ sdoxml:propertyType="company:EmployeeType"/> ]]> - - - 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 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 a data - object created from the schema and instance document shown above. + 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 names + Access via property name Data object properties can be accessed using the object property - access syntax. The following gets the list of departments - (containing a single department), and sets the company name to 'Acme'. + access syntax. The following sets the company name to 'Acme'. departments; $company->name = 'Acme'; ?> ]]> @@ -487,24 +394,16 @@ sdoxml:propertyType="company:EmployeeType"/> - 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 departments element - is the first company property defined and the company name attribute - is the second company property (the SDO interface makes no distinction - between XML attributes and elements). - The following gets the list of departments (containing a single - department), and sets the company name to '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. - + ]]> @@ -513,36 +412,72 @@ sdoxml:propertyType="company:EmployeeType"/> - Data Object Iteration + Data Object iteration We can iterate over the properties of a data object using foreach. - The following iterates over the company properties; name, - departments and employeeOfTheMonth. + The following iterates over the properties of the employee of the month. $value) { - // ... + $eotm = $company->employeeOfTheMonth; + foreach ($eotm as $name => $value) { + echo "$name: $value\n"; } ?> ]]> - - For the first iteration, $name will be 'name' and $value - will be 'Acme'. For the second iteration, $name will be - 'departments' and $value will be an SDO_List (because departments is a - many-valued property (stated maxOccurs="unbouded" - in the schema)) containing a single data object of type DepartmentType. - For the third iteration, $name will be 'employeeOfTheMonth' and $value - will be a data object of type EmployeeType. + + 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 property iteration Many-valued properties can also be iterated over using foreach. The following iterates over the company's departments. @@ -565,115 +500,78 @@ sdoxml:propertyType="company:EmployeeType"/> - 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]; -?> -]]> - - - - - - - Nested Property Access - - We can use nested property access to navigate the data object - instance structure. The following gets and sets the name of the first - 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; $company->departments[0]->name = 'Emerging Technologies'; + $dept_name = $company->departments[0]->name; ?> ]]> - - - - - - Simple XPath support - - We can access properties using XPath-like (an augmented - sub-set of XPath) expressions, the simplest form of which is the - property name. - The following sets the company name and gets the employeeOfTheMonth. - - - -]]> - - - - - - - Simple XPath support - - We can use chained array access calls to navigate the data - object instance structure. The following gets and sets the name of the - first department. - + Using the associative array syntax, this is equivalent to ]]> + In either case, the dept_name variable is set to 'Emerging Technologies'. + - XPath Navigation + XPath navigation + The associative array index can be an XPath-like expression. Valid + expressions are defined by an augmented sub-set of XPath. + - We can use XPath expressions to navigate the data object - instance structure. Two forms of indexing into many-valued - properties are supported. + 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 following both get the second employee from the - first department. + 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 + 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. - ]]> @@ -682,7 +580,7 @@ sdoxml:propertyType="company:EmployeeType"/> - Creating child data object + 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. @@ -692,7 +590,7 @@ sdoxml:propertyType="company:EmployeeType"/> createDataObject('employees'); $new_hire->name = 'John Johnson'; $new_hire->SN = 'E0005'; @@ -705,12 +603,45 @@ sdoxml:propertyType="company:EmployeeType"/> - Unset referenced data object + 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 @@ -732,6 +663,32 @@ sdoxml:propertyType="company:EmployeeType"/> + + + + 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. + + + +