Внимание. Это расширение является ЭКСПЕРИМЕНТАЛЬНЫМ. Поведение этого расширения, включая имена его функций и относящуюся к нему документацию, может измениться в последующих версиях PHP без уведомления. Используйте это расширение на свой страх и риск.

- 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).

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 references 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 reference to the Departments. Deleting a data object which has a containment reference to another data object will delete the referenced 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.

- 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").

Требования

Установка

- 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 PHP5.1 progresses in status from beta to stable release. The instructions here were correct on 3rd August 2005, when PHP5.1.0b3 was the current beta release of PHP, and 0.5.0 was the current beta release of SDO.

latest/Release	Windows	Linux
- latest CVS	- You will find the latest DLLs for the SDO core and the XML DAS at the PHP snaps site. Follow the link to - "PECL extensions for the unstable win32 branch" for the list of recently built DLLs. The latest sdo core DLL is php_sdo.dll and the latest XML DAS DLL is php_sdo_das_xml.dll . 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 - - pear -B install sdo-0.5.0	- You can download and install all three SDO components - the SDO core, the XML DAS and the Relational DAS - with the command - pear install sdo-0.5.0 . This 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:


extension=php_sdo.dll

extension=php_sdo_das_xml.dll

You may also need to update your extension_dir in php.ini to point to the location of these libraries.

- 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.

Change to the main extension directory: cd < wherever your sdo code is >
Run phpize, which will set up the environment to compile both SDO and the XML Data Access Service.
Next, run ./configure; make; make install. Please note, you may need to login as root to install the extension.
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.

Data Access Services

- The table below lists the currently provided SDO Data Access Services:

DAS Name Description
- SDO_DAS_XML - An XML Data Access Service supporting reading/writing SDOs as XML documents or via a Web URL to supporting things like RSS feeds.
- SDO_DAS_Relational - A PDO-based Data Access Service supporting reading/writing SDO to relational data sources. Implements an optimistic concurrency policy for updates.

DAS Name	Description
- SDO_DAS_XML	- An XML Data Access Service supporting reading/writing SDOs as XML documents or via a Web URL to supporting things like RSS feeds.
- SDO_DAS_Relational	- A PDO-based Data Access Service supporting reading/writing SDO to relational data sources. Implements an optimistic concurrency policy for updates.

Limitations

Implementation Limitations

- The following are limitations in the current SDO implementation:

There is no support for multi-byte character sets.
The class constants SDO_DAS_ChangeSummary::NONE, SDO_DAS_ChangeSummary::MODIFICATION, SDO_DAS_ChangeSummary::ADDITION, SDO_DAS_ChangeSummary::DELETION are unavailable, because of an outstanding problem.
- As a bypass, the global constants SDO_DAS_CHANGE_SUMMARY_NONE, SDO_DAS_CHANGE_SUMMARY_MODIFICATION, SDO_DAS_CHANGE_SUMMARY_ADDITION, SDO_DAS_CHANGE_SUMMARY_DELETION are provided.
You may see problems when serializing and unserializing graphs which include non-containment references. We are working on these.

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.

Abstract types and type derivation.
Open types.
Bi-directional relationships.
Type and property alias names.
Default property values.
Read-only properties.
Model introspection.
XMLHelper/XSDHelper (the XML DAS provide a lot of this functionality)
TypeHelper (the SDO_DAS_DataFactory provides this functionality)

Примеры

- The examples below assume an SDO created with the schema 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'.

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:sdo="commonj.sdo" xmlns:sdoxml="commonj.sdo/xml" xmlns:company="companyNS" targetNamespace="companyNS"> <xsd:element name="company" type="company:CompanyType"/> <xsd:complexType name="CompanyType"> <xsd:sequence> <xsd:element name="departments" type="company:DepartmentType" maxOccurs="unbounded"/> </xsd:sequence> <xsd:attribute name="name" type="xsd:string"/> <xsd:attribute name="employeeOfTheMonth" type="xsd:IDREF"
sdoxml:propertyType="company:EmployeeType"/> </xsd:complexType> <xsd:complexType name="DepartmentType"> <xsd:sequence> <xsd:element name="employees" type="company:EmployeeType" maxOccurs="unbounded"/> </xsd:sequence> <xsd:attribute name="name" type="xsd:string"/> <xsd:attribute name="location" type="xsd:string"/> <xsd:attribute name="number" type="xsd:int"/> </xsd:complexType> <xsd:complexType name="EmployeeType"> <xsd:attribute name="name" type="xsd:string"/> <xsd:attribute name="SN" type="xsd:ID"/> <xsd:attribute name="manager" type="xsd:boolean"/> </xsd:complexType>
</xsd:schema>

- 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'.

<?xml version="1.0" encoding="UTF-8" ?>
<company xmlns="companyNS" name="MegaCorp" employeeOfTheMonth="#/departments.0/employees.1"> <departments name="Advanced Technologies" location="NY" number="123"> <employees name="John Jones" SN="E0001"/> <employees name="Jane Doe" SN="E0003"/> <employees name="Al Smith" SN="E0004" manager="true"/> </departments>
</company>

Setting and Getting Property Values

- The following examples assume $company is a data object created from the schema and instance document shown above.

Пример 1. Access via Property names
- 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'.

<? $departments = $company->departments; $company->name = 'Acme';
?>

Пример 2. 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'.

<? $departments = $company[0]; $company[1] = 'Acme';
?>

Пример 3. 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.

<? foreach ($company as $name => $value) { ... }
?>

- 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.

Пример 4. Many-valued Property Iteration
- Many-valued properties can also be iterated over using foreach. The following iterates over the company's departments.

<? foreach ($company->departments as $department) { ... }
?>

- Each iteration will assign the next department in the list to the variable $department.

Пример 5. 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.

<? $ad_tech_dept = $company->departments[0];
?>

Пример 6. 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.

<? $dept_name = $company->departments[0]->name; $company->departments[0]->name = 'Emerging Technologies';
?>

Пример 7. 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.

<? $company['name'] = 'UltraCorp'; $eotm = $company['employeeOfTheMonth'];
?>

Пример 8. 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.

<? $dept_name = $company['departments'][0]['name']; $company['departments'][0]['name'] = 'Emerging Technologies';
?>

Пример 9. XPath Navigation
- We can use XPath expressions to navigate the data object instance structure. 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.

<? $jane_doe = $company["departments[1]/employees[2]"]; $jane_doe = $company["departments.0/employees.1"];
?>

Пример 10. 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.

<? $ad_tech_mgr = $company["departments[name=\"Advanced Technologies\"]/employees[manager=\"true\"]"];
?>

Пример 11. Creating child data object
- 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.

<? $ad_tech_dept = $company["departments[name=\"Advanced Technologoies\"]"]; $new_hire = $ad_tech_dept->createDataObject('employees'); $new_hire->name = 'John Johnson'; $new_hire->SN = 'E0005'; $new_hire->manager = false;
?>

Пример 12. Unset referenced data object
- We can use the isset() and unset() functions to test and remove items from the data object.
- The following removes the 'employeeOfTheMonth' from the company. If this were a containment reference 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.

<? if (isset($company->employeeOfTheMonth) { unset($company->employeeOfTheMonth); }
?>

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 ( <A/><B/><A/>). This can occur for example when the schema defines maxOccurs>1 on a element which is a complexType with a choice order indicator.

- 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.

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:letter="http://letterSchema" targetNamespace="http://letterSchema"> <xsd:element name="letters" type="letter:FormLetter"/> <xsd:complexType name="FormLetter" mixed="true"> <xsd:sequence> <xsd:element name="date" minOccurs="0" type="xsd:string"/> <xsd:element name="firstName" minOccurs="0" type="xsd:string"/> <xsd:element name="lastName" minOccurs="0" type="xsd:string"/> </xsd:sequence> </xsd:complexType>
</xsd:schema>

- 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.

<letter:letters xmlns:letter="http://letterSchema"> <date>March 1, 2005</date> Mutual of Omaha Wild Kingdom, USA Dear <firstName>Casy</firstName> <lastName>Crocodile</lastName> Please buy more shark repellent. Your premium is past due.
</letter:letters>

- 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.

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.

Пример 13. 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.

<? $letter_seq = $letter->getSequence();
?>

- All subsequent examples assume that the $letter_seq variable has been assigned the sequence for the letter data object.

Пример 14. 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.').

<? $letter_seq[4] = 'Snappy'; $text = $letter_seq[count($letter_seq) - 1];
?>

Пример 15. Sequence iteration
- We can iterate through the individual sequence values using foreach. The following runs through the individual values in sequence order.

<? foreach ($letter->getSequence() as $value) { ... }
?>

Пример 16. 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.

<? $letter[2] = 'Smith'; $last_name = $letter_seq[5];
?>

Пример 17. 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.

<? //Append a firstName value to the sequence //value: 'Smith' //sequence index: NULL (append) //propertyIdentifier: 1 (firtName property index) $letters_seq->insert('Smith', NULL, 1); //Append a lastName value to the sequence //value: 'Jones' //sequence index: NULL (append) //property identifier: 'lastName' (lastName property name) $letters_seq->insert('Jones', NULL, 'lastName'); //Append unstructured text //value: 'Cancel Subscription.' //sequence index: absent (append) //propertyIdentifier: absent (unstructured text) $letters_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) $letters_seq->insert('Care of:', 1);
?>

Пример 18. 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.

<? if (isset($letter_seq[0]) { unset($letter_seq[0]); }
?>

Предопределенные классы

- SDO consists of two sets of interfaces. The first set covers those interfaces for use by SDO client applications. These are identified by the package prefix 'SDO_'. The second set is those for use by Data Access Service implementations and are identified by the package prefix 'SDO_DAS_'. The majority of SDO users will not need to use or understand the 'SDO_DAS_' interfaces.

SDO Application Programmer Interface

SDO_DataObject

- The main interface through which data objects are manipulated. In addition to the methods below, SDO_DataObject extends the ArrayAccess, SDO_PropertyAccess (defines __get() / __set() methods for property access overloading), Iterator, and Countable interfaces.

Методы

getType - get the type of a data object

- getSequence - get the sequence for the data object

- createDataObject - create a child data object

clear - unset the properties of a data object

- getContainer - get the container (also known as 'parent') of this data object

- getContainmentPropertyName - get the name by which the parent refers to this data object

SDO_Sequence

- The interface through which sequenced data objects can be accessed to preserve ordering across a data object's properties and to allow unstructured text. SDO_Sequence preserves contiguous indices and therefore inserting or removing elements may shift other elements up or down. In addition to the methods below, SDO_Sequence extends the ArrayAccess, Iterator and Countable interface.

Методы

- getPropertyIndex - get the property index for a given sequence index

- getPropertyName - get the property name for a given sequence index

move - move an element from one property index to another

insert - insert a new value into the sequence

SDO_List

- The interface through which many-valued properties are manipulated. In addition to the method defined below, SDO_List extends ArrayAccess, Iterator and Countable. SDO_List preserves contiguous indices and therefore inserting or removing elements may shift other elements up or down.

Методы

insert - insert a new value into the list

SDO_DataFactory

- The interface through which data objects can be created. A Data Access Service is responsible for populating the model (i.e. configuring the data factory with the type and structure information for the data objects it can create.) for the factory and can then optionally return an instance of, or implement, the SDO_DataFactory interface.

Методы

create - create a new data object

SDO Data Access Service Developer Interfaces

SDO_DAS_DataObject

- The interface through which a Data Access Service can access a data object's - SDO_DAS_ChangeSummary. The change summary is used by the Data Access Service to check for conflicts when applying changes back to a data source.

Методы

- getChangeSummary - get the change summary for a data object

SDO_DAS_ChangeSummary

- The interface through which the change history of a data object is accessed. The change summary holds information for any modifications on a data object which occurred since logging was activated. In the case of deletions and modifications, the old values are also held in the change summary.

- If logging is no longer active then the change summary only holds changes made up to the point when logging was deactivated. Reactivating logging clears the change summary. This is useful when a set of changes have been written out by a DAS and the data object is to be reused.

Методы

- beginLogging - begin logging changes made to a data object

- endLogging - end logging changes made to a data object

- isLogging - test to see if change logging is on

- getChangedDataObjects - get a list of the data objects which have been changed

- getChangeType - get the type of change which has been made to a data object

- getOldValues - get a list of old values for a data object

- getOldContainer - get the old container data object for a deleted data object

SDO_DAS_Setting

- The interface through which the old value for a property is accessed. A list of settings is returned by the change summary method - getOldValues().

Методы

- getPropertyIndex - get the property index for the changed property

- getPropertyName - get the property name for the changed property

- getValue - get the old value for the changed property

- getListIndex - get the list index for the old value if it was part of a many-valued property

isSet - test to see if the property was set prior to being modified

SDO_DAS_DataFactory

- The interface for constructing the model for an SDO_DataObject. The SDO_DAS_DataFactory is an abstract class providing a static method which returns a concrete data factory implementation. The implementation is used by Data Access Services to create an SDO model from their model. For example, a Relational Data Access Service might create and populate an SDO_DAS_DataFactory model based on a schema for a relational database.

Методы

- getDataFactory - static methods for getting a concrete data factory instance

- addType - add a new type to the SDO model

- addPropertyToType - add a new property to a type definition in the SDO model

Предопределенные константы

-Перечисленные ниже константы определены данным расширением и могут быть

доступны только в том случае, если PHP был собран с

поддержкой этого расширения или же в том случае, если

данное расширение подгружается во время выполнения.

SDO_DAS_ChangeSummary::NONE=0 (integer)

- Represents a change type of 'none'.

SDO_DAS_ChangeSummary::MODIFICATION=1 (integer)

- Represents a change type of 'modification'.

SDO_DAS_ChangeSummary::ADDITION=2 (integer)

- Represents a change type of 'addition'.

SDO_DAS_ChangeSummary::DELETION=3 (integer)

- Represents a change type of 'deletion'.

Содержание

SDO_DAS_ChangeSummary::beginLogging -- Begin change logging.

SDO_DAS_ChangeSummary::endLogging -- End change logging.

SDO_DAS_ChangeSummary::getChangeType -- Get the type of change made to an SDO_DataObject.

SDO_DAS_ChangeSummary::getChangedDataObjects -- Get the changed data objects from a change summary.

SDO_DAS_ChangeSummary::getOldContainer -- Get the old container for a deleted SDO_DataObject.

SDO_DAS_ChangeSummary::getOldValues -- Get the old values for a given changed SDO_DataObject.

SDO_DAS_ChangeSummary::isLogging -- Test to see whether change logging is switched on.

SDO_DAS_DataFactory::addPropertyToType -- Adds a property to a type.

SDO_DAS_DataFactory::addType -- Add a new type to a model.

SDO_DAS_DataFactory::getDataFactory -- Get a data factory instance.

SDO_DAS_DataObject::getChangeSummary -- Get a data object's change summary.

SDO_DAS_Setting::getListIndex -- Get the list index for a changed many-valued property.

SDO_DAS_Setting::getPropertyIndex -- Get the property index for a changed property.

SDO_DAS_Setting::getPropertyName -- Get the property name for a changed property.

SDO_DAS_Setting::getValue -- Get the old value for the changed property.

SDO_DAS_Setting::isSet -- Test whether a property was set prior to being modified.

SDO_DataFactory::create -- Create an SDO_DataObject.

SDO_DataObject::clear -- Clear an SDO_DataObject's properties.

SDO_DataObject::createDataObject -- Create a child SDO_DataObject.

SDO_DataObject::getContainer -- Get a data object's container.

SDO_DataObject::getContainmentPropertyName -- Get the container's property name.

SDO_DataObject::getSequence -- Get the sequence for a data object.

SDO_DataObject::getType -- Get the type of a data object.

SDO_List::insert -- Insert into a list.

SDO_Sequence::getPropertyIndex -- Return the property index for the specified sequence index.

SDO_Sequence::getPropertyName -- Return the property name for the specified sequence index.

SDO_Sequence::insert -- Insert into a sequence.

SDO_Sequence::move -- Move an item to another sequence position.

Пред.

Начало

След.

SDO_DAS_XML::saveDocumentToString

Уровень выше

SDO_DAS_ChangeSummary::beginLogging 22222

CXIX. SDO Functions

Введение

The Structure of a Service Data Object

Требования

Установка

Data Access Services

Limitations

Примеры

Setting and Getting Property Values

Working with Sequenced Data Objects

Предопределенные классы

SDO Application Programmer Interface

SDO_DataObject

Методы

SDO_Sequence

Методы

SDO_List

Методы

SDO_DataFactory

Методы

SDO Data Access Service Developer Interfaces

SDO_DAS_DataObject

Методы

SDO_DAS_ChangeSummary

Методы

SDO_DAS_Setting

Методы

SDO_DAS_DataFactory

Методы

Предопределенные константы