From 56d2bc5bf7a30f5d8ca3668dee33053f525c1672 Mon Sep 17 00:00:00 2001 From: Hannes Magnusson Date: Wed, 26 Dec 2007 14:57:57 +0000 Subject: [PATCH] MFB: Upgrade to the new-reference-structure - (Created missing setup sections in setup.xml, if any) - Moved the intro to book.xml - Changed the intro ID from .intro to intro. - Moved the constants entity to book.xml - Changed constants.xml to be an appendix - Moved sdo.examples into its own chapter (examples.xml) NOTE: The orginal sdo.examples section ID was renamed to sdo.examples-basic Added title to the sdo.examples-basic section - Moved the requirements & installation sections to setup.xml - Moved sdo.limitations into its own chapter (limitations.xml) NOTE: The partintro still containts the sdo.das.table section and the classlisting git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@249023 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/sdo/book.xml | 101 +++ reference/sdo/constants.xml | 6 +- reference/sdo/examples.xml | 810 ++++++++++++++++++++++++ reference/sdo/limitations.xml | 73 +++ reference/sdo/reference.xml | 1081 +-------------------------------- reference/sdo/setup.xml | 208 +++++++ 6 files changed, 1198 insertions(+), 1081 deletions(-) create mode 100644 reference/sdo/book.xml create mode 100644 reference/sdo/examples.xml create mode 100644 reference/sdo/limitations.xml create mode 100644 reference/sdo/setup.xml 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; +
+ + + + + +