1C:Enterprise 8.3. Developer Guide. Contents
XDTO MECHANISM
The XDTO mechanism is a universal data presentation method that interacts with various external data sources and software systems.
XDTO stands for XML Data Transfer Objects.
Use the XDTO mechanism to create a data representation model (model of types and values) that, on the one hand, provides easy and natural data manipulation in the 1C:Enterprise environment and, on the other hand, can be adapted for transparent data conversion to other formats, mostly XML.
Fig. 307. General XDTO Schema
There are several tasks for which the XDTO mechanism is used:
Data exchange between the 1C:Enterprise configurations and other considerably different data schemas;
Data exchange based on XML schemas that are not linked to any configuration (e.g., data exchange with information systems that aren’t built on the basis of 1C:Enterprise);
Organization of work with Web services. Use the XDTO mechanism to describe the types of parameters and return values of Web services and to manipulate transferred and returned data.
The XDTO mechanism has the following key properties:
Supports work with XML;
Provides a typical model of working with data.
At present, data exchange with various software platforms and systems is implemented using XML: XML documents are used to represent data, whilst an XML schema is used to describe formats and data structure. Use the XDTO mechanism to create XML schemas that are required for data exchange and generate XML documents for these schemas.
At the same time, you can use the XDTO mechanism to execute these actions in the manner which is usual for most 1C:Enterprise developers.
Developers deal with data objects and types; data objects contain properties for which values are set, etc. When manipulating data using XDTO, the developer is to a greater extent isolated from the details connected with how these data are presented in XML. Of course, it is impossible to eliminate these details completely, but an important point is that they manifest only where it is really necessary.
16.1. XDTO FACTORY
The key notion of the XDTO mechanism is XDTO factory. The XDTO factory contains a description of all the types that a certain system operates. In particular, for any 1C:Enterprise configuration, a global XDTO factory exists which describes all the types used in the configuration in XDTO terms (this XDTO factory is available through the global context XDTOFactory property).
All descriptions of the types that XDTO factory contains are grouped in one or several XDTO packages. To draw an analogy between XDTO and XML, one can say that the XDTO package corresponds to an XML schema. Therefore, the XDTO factory can correspond to several XML schemas.
The XDTO factory is completely self-contained. In other words, any of the types registered in the XDTO factory can only reference the types from the same XDTO factory.
Generally, the XDTO factory is created once, on the basis of the descriptions of all the types that must be registered in the factory. To create an XDTO factory with the help of 1C:Enterprise script tools, use the XDTOFactory object wizard which receives a set of XML schemas contained in the XMLSchemaSet object.
The scenario of adding XDTO types to the factory one by one or in groups is not supported.
Below is an example of creating the XDTO factory based on the XML schema contained in the XML file. Since the XDTO mechanism is an abstraction built "above" XML, it is necessary to "go through" several levels of work with the XML data in sequence to obtain an XML schema from an XML file:
First, low-level reading/writing of XML files;
Then, the XML object model from which you can obtain the 1C:Enterprise script XMLSchema object that contains the XML schema data.
Fig. 308. Creation of XDTO Factory Example:
// Create the XDTO factory based on the XML schema
// contained in the XML file
// Create a default XML reader object
NewXMLReader = New XMLReader;
// Open the XML file
NewXMLReader.OpenFile("D:/MySchema.xsd");
// Create the default DOM document builder
NewDOMBuilder = New DOMBuilder;
// Read the XML file to the DOM document
NewDOMDocument = NewDOMBuilder.Read(NewXMLReader);
// Create a default XML schema builder
NewXMLSchemaBuilder = New XMLSchemaBuilder;
// Get the XML schema from the DOM document
NewXMLSchema = NewXMLSchemaBuilder.CreateXMLSchema(NewDOMDocument);
// Create a default set of XML schemas
NewXMLSchemaSet = New XMLSchemaSet;
// Add an XML schema to the XML schema set
NewXMLSchemaSet.Add(NewXMLSchema);
// Create the XDTO factory based on the XML schema set
NewXDTOFactory = New XDTOFactory(NewXMLSchemaSet);In the above example, the XMLReader object is created first and the XML file located in the disk is opened. After that, use the DOM document builder to create a DOMDocument object containing the XML file data. Then use the XML schema builder to create a new XMLSchema object containing XML schema data on the basis of the DOM document. Finally, create an empty set of XML schemas, add the existing XML schema to it and use the set to create the XDTO factory.
16.1.1. XDTO Factory Retrieval from XSD Schema File
Schemas = New Array;
Schemas.Add("path1");
Schemas.Add("path2");
Packages = New Array;
Packages.Add(XDTOFactory.Packages.Get("Namespace URI for the package from configuration 1"));
Packages.Add(XDTOFactory.Packages.Get("Namespace URI for the package from configuration 2"));
MyFactory = CreateXDTOFactory(Schemas, Packages);Unlike an arbitrary XDTO factory that a developer can create, the global XDTO factory is created automatically by the system when a new infobase is created; you can add one or several XDTO types to such a factory. Use the visual construction tools to add XDTO packages to the Common – XDTO packages metadata tree branch. All packages in the global XDTO factory can be divided into three types:
An XDTO package containing the description of the platform types. It is identical for all the configuration in the 1C:Enterprise system;
An XDTO package containing a description of the configuration types created as a result of metadata editing (creation and modification of properties of catalogs, documents, etc.);
A single or multiple XDTO packages described directly in the configuration tree, in the Common – XDTO packages branch.
An XDTO package contains a description of a set of types belonging to a single namespace, i.e., a package namespace. In addition to the type descriptions, the XDTO package can contain references to the packages used by this package and a list of global package property definitions.
References to other packages are contained in the Dependencies property of the XDTO package and represent the XDTOPackageCollection object. Packages from this collection include types from the namespace referenced in this package.
A package can contain references to global properties from other packages.
16.2. XDTO DATA TYPES
Each of the XDTO data types is either an XDTO value type or an XDTO object type. Therefore, the XDTOValueType object is used to describe the value type and the XDTOObjectType object is used to describe the object type.
The XDTOValueType object is used to describe the types of simple indivisible values in which no separate constituents can be singled out. Examples of simple values can be various strings, numbers, dates, etc.
The XDTOObjectType object is used to describe the types of data instances that have a certain state presented as a set of property values of this data instance. Property types of this data instance can be either XDTO value types or XDTO object types.
Both XDTOValueType and XDTOObjectType have two properties:
Name – the type name;
NamespaceURI – URI of the namespace in which this type is defined.
Values of these properties match similar parameters that define this type in the XML schema. The type name and namespace URI form a unique type identifier. The type name must be defined. The NamespaceURI property can contain an empty string, though it is not recommended.
16.2.1. XDTO Value Type
You can use three methods to define the XDTO value type in accordance with the rules for the simple type from the XML schema:
restriction, when a base type (the BaseType property) and a set of restrictions for multiple possible values (the Facets property) is specified;
merging, when the type is obtained as a result of merging several value types (merged types are enumerated in the MemberTypes property);
list, when the value is a list of values (the type of item values making up a list of values is specified in the ListItemType property).
In addition to the Name and NamespaceURI properties, the XDTO value type contains the following properties:
BaseType – a base type for this type of XDTO value. The base types can be inherited from other types of XDTO values. A valid set of inherited type values is a subset of possible values of the base type. The upper level in the simple type hierarchy is the predefined anySimpleType type from the http://www.w3.org/2001/XMLSchema namespace. All the value types are directly or indirectly inherited from this type. The types generated by mergers or lists are always directly inherited from anySimpleType;
Facets – is a list of facets restricting a set of valid values towards the base type. A list of facets is specified only for the XDTO value types defined by the restriction of the base type. Every facet is a pair, a facet name and a value. A list of names for valid facets is defined. There are certain limits as to how valid facets can be applied to any type. The list of facets and their applicability to a certain type comply with the rules of the XML Schema (http://www.w3.org/ TR/xmlschema-2/);
MemberTypes is a list of types that form a merger. Only XDTO value types can become unions. If a type is formed by a merger, the MemberTypes list contains at least one type. The Facets list must be empty and the ListItemType property must return an undefined value;
ListItemType – if the XDTO value type is defined by the list, then this property shows the list item type. Facets and the MemberTypes lists must be empty.
A list of valid facets (that is defined by the XDTOFacetType system enumeration):
○ Length – the length facet. It contains a number of units of length, with a unit of length having a different meaning for different types. For string and anyURI types, the length contains a number of characters. For hexBinary and base64Binary types, the length contains a number of binary data bytes. For types defined by the list, the length contains a number of list items;
○ MaxInclusive – a facet of the maximum including the boundary.
It restricts the space of the values of this type with the maximum value. Any value of this type is either less or equal to the specified value;
○ MaxLength – maximum length facet. It contains a maximum number of units of length, with a unit of length having a different meaning for different types. For the string type, the maximum length contains the maximum number of characters. For hexBinary and base64Binary types, the maximum length contains the maximum number of binary data bytes. For types defined by the list, the maximum length contains the maximum number of list items;
○ MaxExclusive – a facet of maximum, not including the boundary.
It restricts the space of the values of this type with the maximum value. Any value of this type is less than the specified value;
○ MinInclusive – facet of the minimum including the boundary. It restricts the space of the values of this type with the minimum value. Any value of this type is either more or equal to the specified value;
○ MinLength – minimum length facet. It contains the minimum number of units of length, with a unit of length having a different meaning for different types. For the string type, the minimum length contains the minimum number of characters. For hexBinary and base64Binary types, the minimum length contains the minimum number of binary data bytes. For the types defined by the list, the minimum length contains the minimum count of list items;
○ MinExclusive – facet of the minimum, not including the boundary. It restricts the space of the values of this type with the minimum value. Any value of this type is more than the specified value;
○ Pattern – the pattern facet. It contains a regular expression defining the space of the values of this type;
○ Enum – the enumeration facet. It defines a set of valid values of this type; ○ White space – the white space facet. It can have one of three values:
□ Preserve – the string can contain any white spaces;
□ Replace – the string should not contain #x9 (tab), #xA (line feed) and #xD (carriage return). If they exist, they must be replaced by #x20 (space) character;
□ Collapse – in addition to the requirements specified for the replace value, the string should not contain paired #x20 characters (space) or opening and closing #x20 characters (space);
○ DigitsTotal – the facet for the total number of digits. It contains the total number of digits (integers plus the fractional parts);
○ FractionPartDigits – the facet for the number of fractional digits. It contains the number of digit positions of the fractional amount.
The XDTO infrastructure defines a set of predefined types for the XDTO values. This set matches the set of primitive types as defined in "XML Schema Part 2: Datatypes". The predefined types form a hierarchy in accordance with "XML Schema Part 2: Datatypes". The type names match the type names of the XML Schema and belong to the URI of the http://www.w3.org/2001/XMLSchema namespace. The predefined types are automatically registered in any XDTO factory.
16.2.2. XDTO Object Type
In addition to the Name and NamespaceURI properties, the XDTO object type contains the following properties:
BaseType – a base type for this type. It can only be an XDTO object type. The base type of the XDTO object type hierarchy is the predefined anyType type from the http://www.w3.org/2001/XMLSchema namespace. All the XDTO object types are directly or indirectly inherited from this type;
Open – this flag specifies if the XDTO object type is open. This property shows if the XDTO object instance can contain additional properties that are not defined in its type, i.e. it implements the open content model. It corresponds to the use of the following descriptions for this type in the XML schema:
<anyAttribute>, <any>;
Abstract – this flag specifies if the XDTO object type is abstract. It corresponds to the use of abstract="true" attribute for this item in the schema;
Ordered – this flag specifies if the order of items that represent property values strictly corresponds to the order of properties in the XDTO object type. If the xsd:all content model is set, the order of XML items can be arbitrary. The order corresponding to the order of properties in the type is also valid, i.e. if the Ordered property is False, on input the order of the XML items is not controlled, whilst on output it is defined by the order of the properties, unless the Sequenced flag is True;
Sequenced – this property shows if an instance of the relevant XDTO object contains an XDTO sequence. This flag is True when the order of nested XML items cannot be uniquely defined by the order of the properties in the type (e.g., the content is set as <sequence … maxOccurs=10 … > in the XML schema) or the mixed="true" attribute is defined for the corresponding XML type in the schema. Use the XDTO sequence to expressly set the order of items in the XML document. The order of the nested items corresponds to the order of properties for objects of the types for which the Sequenced property has the False value;
Mixed – this property shows if mixed content is defined for this type in the XML schema. If the Mixed property setting is True, then the Sequenced value is always True, because mixed content cannot be modeled without using an XDTO sequence;
Properties is a list of properties defined for this XDTO object type. Each of the properties is presented as the XDTOProperty object instance. The list contains a full list of properties including those defined in the base type. There is a predefined XDTO object type with the anyType name and URI of the http://www.w3.org/2001/XMLSchema namespace. This type is the base type for any XDTO object type, but it has no base type of its own. It is open, not abstract, implies a sequence and has an empty list of properties.
This XDTO object type corresponds to anyType defined in "XML Schema Part 2: Datatypes".
16.2.3. XDTO Property
An individual property of an individual XDTO object type is described using the XDTOProperty object instance. It means that one and the same XDTOProperty object instance cannot be used to describe the properties in various XDTO object types and two different properties of one XDTO object type. The XDTOProperty object contains the following properties:
Name – a property name. The property names should be unique within one XDTO object type.
When an XDTO data model is created on the basis of the XSD schema, XDTO property names are formed on the basis of the names of attributes and elements described in that schema. A model type is built sequentially: an attribute based list of properties is created first, then an item based list of properties, in the order of the schema declaration. The name complies with the naming conventions of the script. Characters that are accepted in an XML-name (".", "-", for instance) but that are not accepted from the point of view of script names are replaced with "_". If attribute and item names are copied, a copy is assigned a name extended with a numerical suffix (starting from 1).
Type – a property type. It can be either XDTOValueType object instance or XDTOObjectType object instance;
UpperBound – this property of an XDTO object type can be defined as containing one or multiple values. The property is considered to contain one value if set to 1. If the UpperBound property is greater than 1, it is considered to be able to contain multiple values. This property is modeled as a list in the object structure (be sure not to confused it with the list in the description of the XDTO value type). The UpperBound property shows the maximum number of property values. Its value can be greater than 1 only if the property is represented as an XML item. The UpperBound property corresponds to the xsd:maxOccurs attribute in the XML Schema. A value of -1 corresponds to unbounded;
LowerBound – the minimum number of property values. The minimum number of property values can take values of >= 0. Of course, the LowerBound value must be less than or equal to the UpperBound value (unless the UpperBound value is -1);
Nillable – shows if the property can take an undefined value. An undefined property value is represented in XML as the following item: <elem xsi:nil="true" />. Therefore, the Nillable property set to True can only be defined for properties with the Item presentation form. The Nillable property corresponds to the xsd:nillable attribute in the XML Schema. If UpperBound is greater than 1, property value list items can have an undefined value;
DefaultValue – default property value. The default property value can only be XDTODataValue. This value must be of the same type as the property type or of the inherited type. When the XDTO object is created, the property allowing the only value takes the default value (the IsSet() method of the XDTO object returns False for this property). For properties with multiple values, a list of values is initially empty, irrespective of whether the default value is defined;
Fixed – specifies if the property value is fixed. If it is set to True, the fixed value can be obtained through the DefaultValue property;
Form is the form of property presentation in XML. It can be Text, Item or Attribute. If the presentation form is Attribute or Text, the value of the UpperBound property cannot exceed 1. If the property has the Text value, then the value of the LowerBound property is also equal to 1. Only one property of an individual type can have its presentation form set to Text, while all the other properties must have their presentation form set to Attribute;
LocalName is the local name of an attribute or item used for property presentation. For properties with the Text presentation form, it is an empty string;
NamespaceURI – the URI of the namespace for an attribute or item used for property presentation. It is an empty string if there is no namespace.
16.3. XDTO DATA INSTANCES
The XDTO data instances can be the XDTO values (XDTOValue) or XDTO objects (XDTODataObject).
16.3.1. XDTO Value
The XDTO value is a simple indivisible value in which no separate constituents can be singled out. Examples of such simple values can be various strings, numbers, dates, etc. Instances of simple values are non-mutable.
Use the Create() method of the XDTO factory to create a new XDTO value:
on the basis of the XDTO value type and value;
on the basis of the XDTO value type and lexical value presentation. Below are examples of creating an XDTO value.
Example:
GlobalXDTOFactory = XDTOFactory;
// Create an XDTO value from a reference
CatalogItemRef = Catalogs.Nomenclature.FindByCode("0000001");CreatedValueXDTOValueType = GlobalXDTOFactory.Type("urn:schemas-v8-1c-ru:config-data", "CatalogRef.Nomenclature");
NewXDTOValue = GlobalXDTOFactory.Create(CreatedValueXDTOValueType,CatalogItemRef);
// Create an XDTO value from a lexical value presentation
CreatedValueXDTOValueType = GlobalXDTOFactory.Type("http://www.w3.org/2001/XMLSchema","dateTime");
NewXDTOValue = GlobalXDTOFactory.Create(CreatedValueXDTOValueType, "2006-04-20T12:00:30");You can also obtain a new XDTO value by reading the XML file.
Example:
GlobalXDTOFactory = XDTOFactory;,
// Read XDTO value data from XML file
NewXMLReader = New XMLReader;
NewXMLReader.OpenFile("D:/Exchange.xml");
…
NewXDTOValue = GlobalXDTOFactory.ReadXML(NewXMLReader);
You can write an XDTO value 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.3.2. XDTO Object
Unlike a simple value, an XDTO object state is presented as a set of values of its properties. XDTO object instances are mutable, i.e. the state of an XDTO object can be modified by changing its property values during its lifetime. Any XDTO data instances (both an XDTO value and an XDTO object) can be used as property values. When an XDTO object is a property value, reference to the object is said to be a property value.
Use the Create() method of the XDTO factory to create a new XDTO object on the basis of an XDTO object type. After that, assign corresponding values to the XDTO object properties. Below is an example of creating an XDTO object and filling in its properties.
Example:
GlobalXDTOFactory = XDTOFactory;
// Create an empty XDTO object
CreatedObjectXDTOObjectType =
GlobalXDTOFactory.Type("http://www.1c.ru/demos/goods", "Nomenclature");
NewÕDTOObject = GlobalXDTOFactory.Create(CreatedObjectXDTOObjectType);
// Fill in the XDTO object's property values
CatalogObject = CatalogItemRef.GetObject();
NewÕDTOObject.Description = CatalogObject.Description;
NewÕDTOObject.FullDescr = CatalogObject.FullDescr;
NewÕDTOObject.PurchasePrice = CatalogObject.PurchasePrice;
NewÕDTOObject.Barcode = CatalogObject.Barcode;You can also read the XDTO object data from the XML file or write in the XML file, the way it is done with the XDTO value.
Example:
GlobalXDTOFactory = XDTOFactory;
// Read XDTO object data from XML file
NewXMLReader = New XMLReader;
NewXMLReader.OpenFile("D:/Exchange.xml");
…
NewÕDTOObject = GlobalXDTOFactory.ReadXML(NewXMLReader);
…
// Write XDTO object data to the XML file
NewXMLWriter = New XMLWriter;
NewXMLWriter.OpenFile("D:/Exchange.xml");
…
GlobalXDTOFactory.WriteXML(NewXMLWriter, NewÕDTOObject);When non type-safe data is read, the element is read into XDTOObject of the xsd:anyType type if there are attributes or child elements. This is an open type with mixed content, so the text in the element is interpreted as text and inserted into the object’s sequence, not as a value of property __content.
For instance, if an element of type <element attr="attr_value">element value</ element> is read, text element value can be obtained the following way: XDTOObject.Sequence().GetText(0).
XDTODataObject contains the following methods:
Type() – returns the type of this XDTO object (XDTOObjectType);
Set(<Expression>), Set(<Property>, <Value>) – use these methods to specify the property value:
○ Expression – the Xpath expression specifying the property; ○ Property – the property name; ○ Value – the specified property value.
If Expression is set incorrectly or Value cannot be assigned to the property (e.g., the type is incompatible with the property type), an exception is raised. If an undefined value is assigned to the property, whilst the Nillable property is False, an exception is raised. If a reference to an XDTO object is assigned to the property and the reference to this XDTO object is already a value of any other property, this reference stops being the value of the other property. Chains of references to XDTO objects contained in the object properties cannot form cycles. Therefore, when a reference to an XDTO object is assigned and a cycle is formed, an exception is raised. If the property can have multiple values, you cannot use the Set() method for it as it raises an exception. When a value is assigned to the property, it is checked to see if this value type is allowed for the property. The value can be assigned if its type matches the property type, is inherited from the property type or is one of the types included in a merger. When assigning, if the property presentation form in XML is Text or Attribute, the value is converted to the property type. If the presentation form is Item, the value is assigned as is.
Get(<Property>), Get(<Expression>) – obtains the property value:
○ Property – the property name;
○ Expression – the Xpath expression specifying the property. For properties with multiple values, this method returns a list of property values: XDTOList. All operations of property value modification must be executed through this list.
Reset(<Property>), Reset(<Expression>) – resets the property value:
○ Property – the property name;
○ Expression – the Xpath expression specifying the property.
The Reset() method works differently for various properties. For properties with multiple values (UpperBound > 1), the Reset() method clears up the list of values.
Set() – checks if the property is set. Immediately after the object has been created, all properties have a False value as a result of the Set() method execution.
Sequence() – returns a sequence object (XDTOSequence) belonging to this XDTO object. You can also use the XDTO sequence to modify the object state. This method returns the XDTO sequence only if the Sequenced property is set for the object type.
Validate() – use this method to check if the XDTO object property values are filled in correctly. It also validates the objects referenced in the property values. The following issues are checked: whether the number of property values corresponds to the LowerBound and UpperBound properties; if the order of the property values in the XDTO sequence is correct; and if the Ordered property has the True value. The check stops when the first error is found.
In this case an exception is raised.
16.3.3. XDTO Sequence
Use the XDTOSequence object to model the order of items and text fragments the way they look in the XML object presentation. The sequence consists of property-value pairs. Only properties with the Item presentation form can be used as properties as the order of the attributes is not important. The property in a property-value pair can also have an undefined value. In this case this sequence item is considered a text fragment. Sequence items representing text fragments are only allowed for object types that have a True value of the Mixed property.
When content of an XDTO object is formed by means of assigning values to the properties, the order of assignment is shown in the XDTO sequence.
The XDTO sequence contains he following methods:
Count() – returns the number of sequence items;
GetProperty(<IndexOf>) – returns the property that matches the value located at the IndexOf index. If IndexOf is beyond the allowed values, an exception is raised. The method can return an undefined value if a text fragment from the mixed content (text and items) corresponds to the sequence item;
GetValue(<IndexOf>) – returns the value located at the IndexOf index. If IndexOf is beyond the allowed values, an exception is raised;
SetValue(<IndexOf>, <Item>) – sets the Item value at the IndexOf index. The IndexOf value must be in the range of allowed indices. The item must have a valid value for the property it is set for or for the text;
Add(<Property>, <Item>) – adds a property-value pair to the sequence. The value must be valid for the property;
Add(<Text>) – adds a text fragment to the sequence. If the Mixed property of the object type has a False value, an exception is raised;
Insert(<IndexOf>, <Property>, <Item>) – inserts a property-value pair in the IndexOf position of the sequence. The IndexOf value must be within the range of indices. An item in the IndexOf position and all items with large index values are shifted one position to the right;
Insert(<IndexOf>, <Text>) – inserts Text in the IndexOf position of the sequence. The IndexOf value must be within the range of indices. An item in the IndexOf position and all items with large index values are shifted one position to the right;
Delete(<IndexOf>) – deletes the sequence item in the IndexOf position. The IndexOf value must be within the allowed range.
16.3.4. XDTO List
Use the XDTOList object to model a list of values for properties with multiple values (UpperBound > 1). The list is an ordered set of objects that can be both XDTO values and XDTO objects. If the Nillable property is True, they can also include undefined values. However, the IsSet notion is not defined for list items.
The XDTOList object contains the following methods:
Count() – returns the list size;
Get(<IndexOf>) – obtains the value located at the IndexOf index. IndexOf must be within the allowed range. Otherwise an exception is raised;
Set(<IndexOf>, <Item>) – specifies the Item value in the IndexOf position. The specified value replaces the previous one. IndexOf must be within the allowed range, whilst Item must be valid for the property. Otherwise an exception is raised;
Add(<Item>) – adds the value to the end of the list. Item must be valid for the property. Otherwise an exception is raised;
Insert(<IndexOf>, <Item>) – includes the Item value in the IndexOf position. IndexOf must be within the allowed range, whilst Item must be valid for the property. Otherwise an exception is raised. The value in the IndexOf position and all values with large indices are shifted one position to the right;
Delete(<IndexOf>) – deletes the value in the IndexOf position. IndexOf must be within the allowed range. Any values with large positions are shifted to the free position.
16.3.5. XÐath
Use XPath expressions to navigate the object tree. It is not exactly XPath, but a slightly modified XPath subset.
The main construct of this language is a value path which consists of certain steps. The path steps are separated by the / (slash) character. The property name or predefined period (.) and two-period (..) constructs are used as path steps.
An expression shown below means a PropertyName property of the current object, i.e. the object for which Get() or Set() method has been called.
PropertyName
An expression shown below means that the PropertyName1 property value has been obtained for the current object and the PropertyName2 property value has been obtained for the object referenced by the PropertyName1 property value.
PropertyName1/PropertyName2
Therefore, the step marked by a period represents the current object, while two periods stand for its owner object.
If a search path starts with the slash character, it means that the search begins at the object tree root. If any property is not found in the path, an exception is raised. If the path includes a property with multiple values, the result is the entire list of values for this property.
For example, if the path below contains the List property with multiple values, the result of this expression is the list of values (XDTOList) for this property.
Property/List
To obtain a certain value from this list, specify a 0-based value index over the period from the property name in the list as shown below.
Property/List.0
The index must be specified as an integer falling in the range of allowed indices. Otherwise an exception is raised.
A certain list value can be obtained using a 1-based index. The following construct can be used:
Property/List[1]
Index values can range from 1 up to the number of list items.
The search functionality is also available for lists (only for objects). The search expression looks like the following:
Property/List[PropertyName='SearchString']
Here List is the property with multiple values. List values are objects having a PropertyName property. The result is the first object in the list with the Property property value equal to 'SearchString'. If no object is found, the result is an undefined value. Not all list objects can have the PropertyName property. Sometimes there are no objects with such a property. The value with which the property value is compared can be specified as a number, a logical value (True or False) or a string literal.
Property/List[PropertyName!='SearchString']
The above expression is similar to the previous example, with the exception that the result is the first object in the list with its PropertyName property value different from 'SearchString'.
Below is the definition of the described XPath subset.
<Path>
[/] <Step List>
< Step List >
<Step> [/<Step List>] |
<Step>
<Property Name> [<Qualifier>] | .. | . |
<Property Name>
[<Letter> | _]<Name balance>
<Name Remain>
{<Letter> | <Digit> | _} <Name remain > |
<Qualifier>
.<0-based index> | [<Property Name>=<Value>] | [<Property Name>!=<Value>] | [<1-based index>]
<0-based index>
<Integer without sign>
<1-based index>
<Integer without sign>
<Integer without sign>
<Digit> <Digits>
<Digit>
0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
<Digits>
<Digit> <Digits> |
<Value>
<Number> | <String> | <Boolean>
<Number>
[+|-]<Integer without sign>[.<Integer without sign>]
<String>
"<Characters>" | '<Characters>'
<Boolean>
true | false
NOTE
In a string with double quotation marks (") used as delimiters, double quotation marks cannot be used among other characters. Similarly, in a string with single quotation marks (') as delimiters, single quotation marks cannot be used among other characters.
When the property value is compared with the value specified as a literal, the latter is converted into the property type according to the conversion rules and then comparison is performed.
16.4. XDTO-BASED XML SERIALIZATION
Type values of 1C:Enterprise configurations can be serialized directly in/from an XML file on the basis of XDTO.
Use the XDTOSerializer object that can be obtained using the wizard on the basis of the existing XDTO factory. Working with XDTOSerializer is similar to working with global procedures and functions within XML.
For example, a reference to the Nomenclature catalog can be serialized into XML file using software code.
Example:
// Get a reference to Nomenclature catalog item
CatalogItemRef = Catalogs.Nomenclature.FindByCode("0000001");
// Create XDTO serializer for global XDTO factory
NewXDTOSerializer = New XDTOSerializer(XDTOFactory);
// Create XML writer and open the file
NewXMLWriter = New XMLWriter;
NewXMLWriter.OpenFile("D:/Exchange.xml"); // ...
// Serialize the reference into XML
NewXDTOSerializer.WriteXML(NewXMLWriter, CatalogItemRef, XMLTypeAssignment.Explicit);Below is an example of how a Nomenclature catalog reference can be serialized from XML file.
Example:
// Create XDTO serializer for global XDTO factory
NewXDTOSerializer = New XDTOSerializer(XDTOFactory);
// Read XDTO object data from XML file
NewXMLReader = New XMLReader;
NewXMLReader.OpenFile("D:/Exchange.xml"); … // Serialize reference from XML
NewCatalogReg = NewXDTOSerializer.ReadXML(NewXMLReader);16.5. XML SCHEMA LAYOUT RECOMMENDATIONS
XMLSchemaSet → XDTOFactory → XMLSchemaSet conversion does not generally result in a set of XML schemas which is equivalent to the source set. Follow a set of recommendations on the XML schema layout to obtain the resulting set of schemas which is equivalent to the source set:
Maintain the equivalence between the resulting and the source set of schemas for XMLSchemaSet → XDTOFactory → XMLSchemaSet conversion.
Use the Validate() method to check if XDTODataObject properties have been filled in correctly and ensure that the object representation in XML corresponds to the XML schema.
Use polymorphism for maximum flexibility and prevention of distortions.
XML schema obtained on the basis of the XDTO factory whose types have unchanged default values for the parameters responsible for XML data presentation complies with the above recommendations.
The following list of recommendations is a set of best practices; follow them to obtain the best results from different points of view.
XML schema must not contain anonymous types
The following constructs are invalid:
<element name="Person"> <complexType> <sequence> <element name="FirstName" type="string" /> <element name="FamilyName" type="string" /> </sequence> </complexType> </element>
This fragment should be arranged in the following way:
<element name="Person" type="tns:PersonType"> <complexType name="PersonType"> <sequence> <element name="FirstName" type="string" /> <element name="FamilyName" type="string" /> </sequence> </complexType>
Only sequence model must be used for complex type content
To model the complexType content, use the only sequence block without redefining the default values for minOccurs and maxOccurs attributes.
<complexType name="PersonType"> <sequence> <element name="FirstName" type="string" /> <element name="FamilyName" type="string" /> </sequence> </complexType>
The all model does not violate the identity of the source and resulting schemas during XMLSchemaSet → XDTOFactory → XMLSchemaSet conversion. However, it has some limitations. Specifically, the maxOccurs attribute in the all model cannot be greater than 1.
The selection model violates the identity of the source and resulting schemas and does not make it possible to check whether the object data meets the XML schema requirements using the Validate() method.
For the same reasons it is not recommended to use multiple content models within a single complex type or define non-default minOccurs and maxOccurs attribute values for sequence.
We recommend you present object properties as XML elements
Representation of properties as XML attributes has no influence on the identity of the source and resulting schemas. However, there are some limitations:
an attribute cannot contain object type values, it can only contain value types;
an attribute cannot contain properties with multiple values;
value type can get distorted if the property represented as an XML attribute has polymorph types, i.e. when a value is assigned to the property, the value type is cast to the property type as the XML item permits specifying the xsi:type attribute (that specifies the exact property value type) only for property values.
Therefore, it is not necessary to use simpleContent for complexType, as this model implies use of XML item attributes and text to store values.
We recommend that you do not use similar names to declare an attribute and an element. For XDTO property naming rules, please see page 2-796.
Mixed content model should be avoided
Using the following construct in a XML schema means that XML item corresponding to the described type can contain text mixed with XML items.
<complexType name="FormLetter" mixed="true"> </complexType>
Information content of this type for the relevant XDTOObjectType is supported by setting Sequenced and Mixed properties to True and obtaining XDTO sequence (XDTOSequence object) for each instance of the corresponding XDTODataObject object. It is much harder to manage the information content of such objects than that of the objects with the state represented by a property value set.
Fortunately, in most cases it is not necessary to use mixed content.
The ElementFormDefault property for XML schema must be set to Qualified.
This recommendation is an element of good style and XDTO follows this style.
16.6. XDTO FACTORY CHECK RULES
A general schema of coding identifiers for XDTO factory check error messages looks like the following:
xdto-<area>-<section>[-<rule>]: <error description>
<area> is the check area (XDTO factory, XDTO package, XDTO value type, XDTO facet or XDTO object type);
<section> is the number of the section which resulted in failure after the check;
<rule> is a section rule;
<error description> is an error description.
16.6.1. Check Rules for XDTO Factory Proper
When XDTO factory is checked, error codes are prefixed with model. A general prefix looks like the following:
xdto-model-<section>[-<rule>]: <error description>
Packages within the model should have unique namespace URIs – duplicate packages are not allowed in the model.
Import directives should determine non-empty namespace URIs of imported packages.
Package import directives should define the existing type packages.
Type packages defined in the model should meet the package check rules.
16.6.2. XDTO Package Check Rules
When XDTO packages are checked for correctness, error codes are prefixed with package. A general prefix looks like the following:
xdto-package-<section>[-<rule>]: <error description>
XDTO package should have the NamespaceURI property set.
Types defined in the XDTO package can have references only to the types specified in the list of imported types (Dependencies property).
Import directives should meet the following criteria:
Import directives should determine XDTO packages which cannot contain any import directives pointing to this XDTO package – loops are not allowed for imported directives.
Import directives should determine the non-empty NamespaceURI property of the imported XDTO package.
Import directives should define the existing XDTO packages.
Package properties should meet the following criteria:
names of package properties should be set and non-empty;
names of package properties should be unique within the XDTO package;
package property type should be set and defined;
package property types should be defined in the package or its dependencies;
setting a name and an anonymous definition for the global property type is not allowed;
package property cannot reference definition of another package property;
package property cannot define limits for the number of property values; package property can have only Attribute or Item presentation form.
16.6.3. XDTO Value Type Check Rules
When XDTO value types are checked for correctness, error codes are prefixed with valueType. A general prefix looks like the following:
xdto-valueType-<section>[-<rule>]: <error description>
General rules for checking the XDTO value type:
If the type is defined within a type package, the following requirements should be met:
○ XDTO value type should have the set Name property containing a nonempty name.
○ XDTO value type name should be unique within the XDTO package (among all the XDTO package types).
If the type is defined within another value type definition or within object type property definition, the following requirements should be met:
○ Name property of type definition should not be set.
○ XDTO value type cannot contain self-references in the base type, list item type or any of the union types in the entire hierarchy.
Rules for checking the base type – BaseType property:
If the BaseType property is not set:
○ If the Variant property is not set and the MemberTypes property is not set or the Variant property is set to Atomic:
□ If the TypeDefinition property contains a single value, this type definition is used for the atomic base type.
□ Otherwise anySimpleType of the XML schema namespace
(http://www.w3.org/2001/XMLSchema) is considered the base type.
If the BaseType property is set, the following requirements should be met:
○ Base type should comply with the second rule of XDTO package check.
○ Base type should be the XDTO value type.
Base type cannot be this XDTO value type.
Rules for checking the list item type – the ListItemType property:
If the ListItemType property is set in the type definition, the following requirements should be met:
○ List item type should comply with the second rule of XDTO package check.
○ List item type should be the XDTO value type.
○ List item type cannot be this XDTO value type.
○ XDTO value type that represents an item list should be either atomic or XDTO value type union consisting only of atomic XDTO value types.
If the Variant property is not set and the BaseType property is set or the Variant property is set to List:
○ If the TypeDefinition property contains a single value, this type definition is used for the anonymous list item type.
○ Otherwise the ListItemType property value is determined based on the corresponding property of the base XDTO value type. Rules for checking the union type – MemberTypes property:
If the MemberTypes property is set in the XDTO type definition, the following requirements should be met:
○ Union type should comply with the second rule of XDTO package check.
○ Union type should be the XDTO value type.
○ Union type should not be this XDTO value type.
○ XDTO value union type should be either an atomic type or a list.
If the Variant property is not set and the BaseType property is set or the Variant property is set to Union:
○ The TypeDefinition property contains values that are anonymous definitions of union types.
○ Otherwise the MemberTypes property value is determined on the basis of the MemberTypes property value of the base XDTO value type.
Inheritance of XDTO value types is considered correct if the following requirements are met:
The following conditions should be met for atomic types of XDTO values (ListItemType and MemberTypes properties are not set after execution of the rules for checking the list item type and the union type):
○ Base XDTO value type should be atomic, i.e. its ListItemType and MemberTypes properties should not be set.
○ Ancestor of the XDTO value type should be one of primitive types of the XML schema namespace (http://www.w3.org/2001/XMLSchema).
○ Content of the facets specified in the XDTO value type description should match the list of valid facets for the primitive type which is the ancestor of this XDTO type.
○ Value of each facet specified in the XDTO value type should comply with the limitation rules for effective values of similar facets of the XDTO base types.
For the list item types (the ListItemType property is set after execution of the rules for checking the list item type and the union type):
□ Base XDTO type cannot be a union type, i.e. its MemberTypes property should not be set.
□ If the ListItemType property of the XDTO base type is set, its value should determine the base type for the list item type defined in the ListItemType property of this XDTO value type.
□ If anySimpleType is the base type of the XML schema namespace (http://www.w3.org/2001/XMLSchema), it is allowed to use only the Whitespace facet out of the facet list.
□ Otherwise only the following facets can be defined: Pattern, Enum, Length, MinLength, MaxLength and Whitespace.
□ Value of each facet in the type should comply with the limitation rules for the effective value of similar base-type facets.
○ For union types (the MemberTypes property is set after execution of rules for checking the list item type and the union type):
□ anySimpleType of the XML schema namespace (http://www.w3.org/2001/ XMLSchema) or a union type can be the base type, i.e. the base type should have the MemberTypes property set.
□ If the base type is a union type, the following requirements should be met:
§ The number of union types for the base type should not be greater than the number of union types for this type.
§ Union types should be descendants of their corresponding base type union types, in accordance with the union type list order.
§ If anySimpleType of the XML schema namespace (http://www.w3.org/2001/XMLSchema) is the base type, facet definition is not allowed.
□ Otherwise it is possible to define only Pattern and Enum facets.
Value of each facet in the type should comply with the limitation rules for the effective value of similar base-type facets.
If the Variant property (contents model) for the type definition is set, it must not conflict with the type definition:
○ If the property is set to Atomic, the type has an atomic contents model and should comply with xdto-valueType-5.1 rules.
○ If the property is set to List, the type has a List contents model and should comply with xdto-valueType-5.2 rules.
○ If the property is set to Union, the type has a Union contents model and should comply with xdto-valueType-5.3 rules.
16.6.4. XDTO Object Type Check Rules
When XDTO object types are checked for correctness, error codes are prefixed with objectType. A general prefix looks like the following:
xdto-objectType-<section>[-<rule>]: <error description>
General rules for checking the XDTO object type:
If the type is defined within a type package, the following requirements should be met:
○ XDTO object type should have the set Name property containing a nonempty name.
○ The name of the XDTO object type should be unique within the package (among all the package types).
If the type is defined within an object-type property, the following requirements should be met:
○ Name property of type definition should not be set.
Rules for checking the base type – BaseType property:
If the BaseType property is not set, anyType of the XML schema namespace (http://www.w3.org/2001/XMLSchema) is considered the base type.
If the BaseType property of the XDTO object type is set, it should meet the following conditions:
○ Base type should comply with the second rule of XDTO package check.
○ Base type should be the XDTO object type.
○ Base type cannot be this XDTO object type.
Each property of the XDTO object type should meet the following conditions:
Property name should be defined.
Property name cannot be empty.
Property name should be unique for the XDTO object type.
If the Type property is set, it should meet the following conditions:
○ Type name should define the existing XDTO object type or XDTO value type.
○ Property type should comply with the second rule of XDTO package check.
Property cannot contain an anonymous type definition.
If the Type property is not set, it should meet the following conditions:
○ If the property has an anonymous type definition, the property type is the type corresponding to this definition.
○ Otherwise anyType of the XML schema namespace (http://www. w3.org/2001/XMLSchema) is considered the property type.
If a default value is specified for the property, the following requirements should be met:
○ DefaultValue property type should be the XDTO property type.
○ Lexical representation of the default value should match the space of values for the XDTO property type.
The following requirements should be met:
○ If the LocalName property of the XDTO property is not set, the Name property of the XDTO property is used as the local name of the XML representation for the XDTO property.
○ If the NamespaceURI property of the XDTO property is not set, URI of the XML namespace for XDTO property representation is determined as follows:
□ If the XML representation form of XDTO property (Form property) is Item, it uses URI of the namespace for the type containing this property.
□ Otherwise URI of namespace for the XDTO property XML representation is considered non-existent.
○ XDTO property should be unique for the XML representation within the XDTO object type.
○ If the XDTO property has the Text XML representation form, the following conditions should be met:
□ Name and URI of the namespace should be undefined or empty.
□ XDTO object type properties can include XDTO properties with the Attribute XML representation form.
□ If XDTO property has the Item XML representation form, it is not allowed to use XDTO properties with the Text XML representation form for this XDTO object type.
○ Value of the lower boundary for the number of LowerBound property values can be a non-negative integer. LowerBound value should be less than or equal to the value of the upper boundary for the number of UpperBound property values if it does not equal -1.
○ UpperBound value can be a non-negative integer or -1. If it is -1, it means the number of property values is unlimited.
○ If the Fixed property value is set, DefaultValue must be set by default and correspond to the XDTO property type value space.
○ If a reference to the global property definition is set, the following requirements should be met:
□ The property definition cannot override values of the global definition properties.
□ The global property referenced by the property definition should be defined within the current package or its dependency packages.
If XDTO object type properties include an XDTO property with the same name or XML representation as the base type property, the inheritance type is determined as limitation inheritance. The following conditions should be met for this inheritance type:
○ The following conditions should be met for each XDTO property:
□ Base type should define the XDTO property with the same name – the overridden property.
□ If the base type determines the order of properties (Ordered property), position of the overridden property should be identical to the position of the property in the inheriting type.
□ XML representation form of the overridden property and property of this type should be the same.
□ XML representation local name of the overridden property and property of this type should be the same.
□ XML representation namespace URI of the overridden property and property of this type should be the same.
○ If the overridden property determines a fixed value:
□ The fixed value cannot be removed from the inheriting type.
□ The fixed value in the base type and the inheriting type should be the same.
□ The lower limit for the number of property values should be less than or equal to the lower limit for the number of overridden property values.
□ The upper limit for the number of property values should be greater than or equal to the upper limit for the number of overridden property values.
□ The property type should be a descendant of the overridden property type.
□ If the base type does not have mixed content (Mixed property), it is not possible to set the mixed model for the inheriting type.
□ If the base type has a fixed order of properties (Ordered property), it is not possible to change the order in the inheriting type.
□ If the base type does not specify a sequence (Sequenced property), it is not possible to specify it in the inheriting type.
□ If the base type does not have an open content model (Open property), it is not possible to set the open content model for the inheriting type.
Otherwise (see rule 4) the inheriting type is determined as enhancement inheritance. The following conditions should be met for this inheritance type:
If the base type content model is mixed (Mixed property), it is not possible to change the mixed model in the inheriting type.
If the base type property order is not fixed (Ordered property), it is not possible to change the order in the inheriting type.
If the base type specifies a sequence (Sequenced property), it is not possible to disable the sequence in the inheriting type.
If the base type has an open content model (Open property), it is not possible to change the content model for the inheriting type.
The following conditions should be met for any inheritance type:
If the content model is mixed (Mixed property), it is not possible to disable sequences (Sequenced property).
If the content model is open (Open property), it is not possible to disable sequences (Sequenced property).
16.6.5. Facet Limitation Rules
When XDTO facets are checked for correctness, error codes are prefixed with facet. A general prefix looks like the following:
xdto-facet-<section>[-<rule>]: <error description>
Rules for the Length facet:
Facet value should be the same as the efficient value of the base type facet.
If the MinLength facet value is set, it should meet the following conditions:
○ MinLength facet value should be less than or equal to the Length facet value.
○ In the base type, Length facet values should not be set or the MinLength facet value should be the same as the effective value of the base type MinLength facet.
If the MaxLength facet value is set, it should meet the following conditions:
○ MaxLength facet value should be less than or equal to the Length facet value.
○ In the base type, Length facet values should not be set or the MaxLength facet value should be the same as the effective value of the base type MaxLength facet.
Rules for the MinLength facet:
Facet value should be greater than or equal to the effective facet value in the base class.
Facet value should be less than or equal to the MaxLength facet effective value.
Rules for the MaxLength facet:
Facet value should be less than or equal to the effective facet value in the base class.
Facet value should be greater than or equal to the MinLength facet effective value.
Rules for the Whitespace facet:
If the base type facet effective value is Collapse, the facet cannot have any other value.
If the base type facet effective value is Preserve, the facet cannot have Replace value.
Rules for the MinInclusive facet:
Facet value should be less than the MaxExclusive facet effective value of this type.
Facet value should be greater than or equal to the base-type facet effective value.
If MaxInclusive facet value is set, it should be less than or equal to the base type MaxInclusive facet effective value.
If MinInclusive facet value is set, it should be greater than the base-type MinInclusive facet effective value.
If MaxExclusive facet value is set, it should be less than the base-type MaxExclusive facet effective value.
Rules for the MinExclusive facet:
It is not permitted to set the MinExclusive and MinInclusive facet values in the type definition.
If the MaxInclusive facet value is set, the MinExclusive facet value should be less than the MaxInclusive facet value for this type.
Facet value should be greater than or equal to the base-type facet effective value.
If the MaxInclusive facet value is set, it should be less than or equal to the base-type MaxInclusive facet effective value.
If the MinInclusive facet value is set, it should be greater than or equal to the base-type MinInclusive facet effective value.
If the MaxExclusive facet value is set, it should be less than the effective MinInclusive base-type facet value.
Rules for the MaxInclusive facet:
Facet value should be greater than or equal to the MinInclusive facet value for this type.
If the MaxExclusive facet value is set, it should be less than the effective value for the base type.
If the MinInclusive facet value is set, it should be greater than or equal to the effective value for the base type.
If the MinExclusive facet value is set, it should be greater than the effective value for the base type.
Rules for the MaxExclusive facet:
It is not permitted to set the MaxExclusive and MaxInclusive facet values in the type definition.
If the MinExclusive facet value is set, the MaxExclusive facet value should be greater than the MinExclusive facet value for this type.
Facet value should be less than or equal to the effective base-type facet value.
If the MaxInclusive facet value is set, it should be less than or equal to the effective value for the base type.
If the MinExclusive facet value is set, it should be greater than the effective value for the base type.
If the MinInclusive facet value is set, it should be greater than the effective value for the base type.
Rules for the DigitsTotal facet:
Facet value should be less than or equal to the effective base-type facet value. Rules for the FractionPartDigits facet:
Facet value should be less than or equal to the effective DigitsTotal facet value.
Facet value should be less than or equal to the effective base-type facet value.