16.1.4. XDTO data instances

XDTO data instances can be XDTO values (XDTODataValue) or XDTO objects (XDTODataObject).

16.1.4.1. XDTO value

XDTO values are simple indivisible values in which separate parts cannot be identified. These are, for example, various strings, numbers, dates, and so on. Instances of simple values are immutable.

A new XDTO value can be created using the Create() method of the XDTO factory:

Based on an XDTO value type and value.
Based on an XDTO value type and lexical value presentation.

Below you can see examples of how to create an XDTO value.

Example:

GlobalXDTOFactory = XDTOFactory;

// Create an XDTO value from the link
CatalogItemRef = Catalogs.Products.FindByCode("0000001");
XDTOValueTypeOfValueToCreate = GlobalXDTOFactory.Type("urn:schemas v8 1c ru:config data", "CatalogRef.Products");
NewXDTOValue = GlobalXDTOFactory.Create(XDTOValueTypeOfValueToCreate, CatalogItemRef);

// Create an XDTO value from the lexical value presentation
XDTOValueTypeOfValueToCreate = GlobalXDTOFactory.Type("http://www.w3.org/2001/XMLSchema", "dateTime");
NewXDTOValue = GlobalXDTOFactory.Create(XDTOValueTypeOfValueToCreate, "2006-04-20T12:00:30");

The new XDTO value can also be created by reading the XML file.

Example:

GlobalXDTOFactory = XDTOFactory;,

// Read XDTO value data from the XML file
NewXMLReader = New XMLReader;
NewXMLReader.OpenFile("D:/Exchange.xml");
…

NewXDTOValue = GlobalXDTOFactory.ReadXML(NewXMLReader);
XDTO value can be written to the XML file.
GlobalXDTOFactory = XDTOFactory;

// Write XDTO value data to the XML file
NewXMLWriter = New XMLWriter;
NewXMLWriter.OpenFile("D:/Exchange.xml");
…

GlobalXDTOFactory.WriteXML(NewXMLWriter, NewXDTOValue);

16.1.4.2. XDTO object

In contrast to the simple value, the state of XDTO object is the set of its properties values. Instances of XDTO object are mutable. It means that during the XDTO object lifetime its state can be changed by changing values of some of its properties. Any XDTO data instances can be stated as property values. It can be both an XDTO value and an XDTO object. When a property value is an XDTO object, the property value is an object link.

New XDTO object can be created using the Create() method of the XDTO factory, based on the XDTO object type. After this you should assign the values to XDTO object properties. Below you can see an example of how to create an XDTO object and fill its properties.

Example:

GlobalXDTOFactory = XDTOFactory;

// Create an empty XDTO object
XDTOObjectTypeOfObjectToCreate = GlobalXDTOFactory.Type("http://www.1c.ru/demos/products", "Products");
NewXDTODataObject = GlobalXDTOFactory.Create(XDTOObjectTypeOfObjectToCreate);

// Fill the XDTO object property values
CatalogObject = CatalogItemRef.GetObject();

NewXDTODataObject.Description = CatalogObject.Description;
NewXDTODataObject.FullDescr = CatalogObject.FullDescr;
NewXDTODataObject.PurchasePrice = CatalogObject.PurchasePrice;
NewXDTODataObject.Barcode = CatalogObject.Barcode;

Just like the XDTO value, the XDTO object data can be read from XML file or written the the XML file.

Example:

GlobalXDTOFactory = XDTOFactory;,

// Read an XDTO object data from the XML file
NewXMLReader = New XMLReader;
NewXMLReader.OpenFile("D:/Exchange.xml");
…

NewXDTOObject = GlobalXDTOFactory.ReadXML(NewXMLReader);
…

// Write XDTO object data to the XML file
NewXMLWriter = New XMLWriter;
NewXMLWriter.OpenFile("D:/Exchange.xml");
…

GlobalXDTOFactory.WriteXML(NewXMLWriter,NewXDTODataObject);

When reading untyped data, an element is read into XDTODataObject of the xsd:anyType type if there are attributes or child elements. This is an open type with the mixed content, so the text in the item is interpreted not as the __content property value but as a text and is placed in the object sequence.

For example, when reading the <element attr="attr_value">element value</element> item, the element value text can be retrieved in the following way: XDTODataObject.Sequence().GetText(0).

The XDTODataObject object contains the following methods:

Type(). Returns a type of this XDTO object (XDTOObjectType).
Set(<Expression>), Set(<Property>, <Value>). Allows you to set a property value.
Expression. An expression on XPath indicating a property.
Property. A property name.
Value. A property value to set.

If Expression is set incorrectly or Value cannot be assigned to the property (for example, the type is incompatible with the property type), an exception is thrown. If an undefined value is assigned to the property and the Nillable property is set to False, an exception is thrown. If a link to an XDTO object is assigned to the property and this link is already a value of another property, this link is no longer a value of the latter property.

Chains of links to XDTO objects in object properties cannot create cycles. That is why, when assigning links to an XDTO object that creates a cycle, an exception is thrown. If the property allows multiple values, the Set() method cannot be used and results in an exception. When assigning a value to the property, the application checks whether this value type can be assigned to the property. The value can be assigned if its type is the same as the property type, is inherited from the property type or is one of the types from merging. When assigning, if the property value presentation form in XML is Text or Attribute, the value is aligned with the property type. If the presentation form is Element, the value is assigned as is.

Get(<Property>), Get(<Expression>). Gets a property value:
- Property. A property name.
- Expression. An expression on XPath indicating a property. For properties with multiple values, this method returns the XDTOList list of property values. All property values modification operations must be performed via this list.
Unset(<Property>), Unset (<Expression>). Clears a property value:
- Property. A property name.
- Expression. An expression on XPath indicating a property. The Unset() method acts differently for different properties. For properties allowing multiple values (UpperBound > 1), the Unset() method clears the list of values.
IsSet(). Verifies whether a property value is set. After creating an object, the result of the IsSet() method will be False for all properties.
Sequence(). Returns a sequence object (XDTOSequence) that belongs to this XDTO object. The XDTO sequence is used to modify the object state. This method returns XDTO sequence only if the Sequenced property is set for the object type.
Validate(). Allows you to check whether XDTO object properties are filled correctly. The objects that are the property values are also verified. What is verified: a mapping between the number of property values and the LowerBound and UpperBound properties, validity of the property value order in XDTO sequence if the Ordered property is True. The verification is stopped after the first error. In this case, an exception is thrown.

16.1.4.3. XDTO sequence

The XDTOSequence object is used to model the order of items and text fragments as they look in XML presentation of the object. The sequence consists of the "property ‑ value" pairs. Only properties with the Element presentation form can be properties as the attribute order does not matter. The property in "property ‑ value" pair can have the undefined value. In this case, such sequence item is considered a text fragment. Appearance of the sequence items presenting the text fragments is only acceptable for the type objects with Mixed property set to True.

When generating the XDTO object content by assigning values to properties, the order of assignment is shown in XDTO sequence.

The XDTO sequence includes the following methods:

Count(). Returns the number of sequence items.
GetProperty(<Index>). Returns a property matching a value located by the Index index. If Index is outside the allowed values, an exception is thrown. The method can return the undefined value, if the sequence item corresponds to the text fragment from the mixed content (text and items).
GetValue(<Index>). Returns a value located by the Index index. If Index is outside the allowed values, an exception is thrown.
SetValue(<Index>, <Item>). Sets the Item value by the Index index. Index must have the value from within the acceptable indexes range. An item must have a value that is acceptable for the property, for which it is set, or for a text.
Add(<Property>, <Item>). Adds the "property ‑ value" pair to the sequence. Value must be acceptable for the property.
Add(<Text>). Adds a text fragment to the sequence. If the Mixed object type property is False, an exception is thrown.
Insert(<Index>, <Property>, <Item>). Inserts the "property ‑ value" pair into the Index sequence position. Index must have the value from within the index range. The item in the Index position and all items with a value greater than the index are shifted one position to the right.
Insert(<Index>, <Text>). Inserts the Text text into the Index sequence position. Index must have the value from within the index range. The item in the Index position and all items with a value greater than the index are shifted one position to the right.
Delete(<Index>). Deletes a sequence item in the Index position. Index must have the value from within the acceptable range.

16.1.4.4. XDTO list

The XDTOList object is used to model a value list for properties with multiple values (UpperBound > 1). The list is the ordered set of objects, which can be XDTO values or XDTO objects. Among them, there can be undefined values, if the Nillable property is True. The concept of "setting" is not defined for the list item.

The XDTOList object contains the following methods:

Count(). Returns a list size.
Get(<Index>). Gets a value located by the Index index. Index must be within the allowed values. Otherwise, an exception is thrown.
Set(<Index>, <Item>). Sets the Item value to the Index position. The set value replaces the previous value. Index must be within the allowed values and Item must be allowed for the property. Otherwise, an exception is thrown.
Add(<Item>). Adds a value to the end of the list. Item must be acceptable for the property. Otherwise, an exception is thrown.
Insert(<Index>, <Item>). Inserts the Item value into the Index position. Index must be within the allowed values and Item must be allowed for the property. Otherwise, an exception is thrown. Value in Index position and values with the larger positions are shifted one position to the right.
Delete(<Index>). Deletes values in the Index position. Index must be within the allowed values. Values with larger positions are shifted to the free space.

16.1.4.5. XРath

To navigate the object tree, expressions on the XPath can be used. Strictly speaking, this is not exactly the XPath, but rather modified XPath subset.

The main construction of this language is the path to the value that consists of the separate steps. The steps in the path are divided with slashes (/ character). The path step is the property name or predefined constructions: . (dot) and .. (two dots).

The expression below denotes the PropertyName property of the current object, particularly an object with Get() or Set() method called.

PropertyName

The expression below means that for the current object the PropertyName1 property value is received, and for the object with the link that is the value of PropertyName1 property the PropertyName2 property is received.

PropertyName1/PropertyName2

The step denoted as a dot means the current object, and two dots mean an object that owns the current object.

If the search path starts with slash, it means searching from the object tree root. If some property on the path is not found, this calls an exception. If there is a property with multiple values on the path, the result is the whole list of values of this property.

For example, if the List property in the path below has multiple values, the result of this expression is a list (XDTOList) of property values.

Property/List

To get one value from this list, specify the 0-based index of the value in the list in the property name and separate it with the dot, as shown below.

Property/List.0

The index must be set as an integer within the range of acceptable indexes. Otherwise, an exception is thrown.

You can get one value form the list using the 1-based index. To do this, the following construction is used:

Property/List[1]

Index can have the value from 1 to the number of list items.

You can also search in the list (only for objects). The expression for searching looks as follows:

Property/List[PropertyName='SearchString']

Here, List is a property with multiple values. The value of the list are the objects with PropertyName property. The result is the first object in the list with the Property property set to 'SearchString' string value. If no objects are found, the result is undefined value. Some objects in the list might not have the PropertyName property. Also, none of the objects may have it. The value, compared to the property value, can be set as a number, logical value (True or False) or string literal.

Property/List[PropertyName!='SearchString']

The expression above is similar to the previous one. However, in this case, the result is the first object in the list whose PropertyName property value is not equal to the 'SearchString' string value.

Below is the definition of the XPath set described.

<Path>

[/] <List of steps>

<Step> [/<List of steps>] |

<Step>

<Property name> [<Clarification>] | .. | . |

[<Letter> | _]<Rest of the name>

{<Letter> | <Digit> | _} <Rest of the name> |

.<0 based index> |
[<Property name>=<Value>] |
[<Property name>!=<Value>] |
[<1 based index>]

<0-based index>

<Unsigned integer>

<1-based index>

<Unsigned integer>

<Digit> <Digits>

<Digit>

0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9

<Digit> <Digits> |

<Value>

<Number> | <String> | <Boolean>

[+| ]<Unsigned integer>[.<Unsigned integer>]

"<Characters>" | '<Characters>'

true | false

NOTE. The string with " delimiters cannot include " characters. Similarly, the string with ’ delimiters cannot include’ characters.

When comparing the property value with the value set as a literal, the value set as a literal is converted by the behavior rules, and then the comparison is performed.

<< Prev Next >>