E171 Native XML Services in PowerBuilder 9.0

1. E171 Native XML Services in PowerBuilder 9.0 • Bio Liong Lim • Staff Software Engineer • Sybase Asia Development Centre • bio-liong.lim@sybase.com

2. Session Outline The areas we will be covering. • What is DOM ? • What is PBDOM ? • PBDOM Design Goals. • PBDOM Concepts. • PBDOM Classes. • The Future of PBDOM.

3. What is DOM ? What is DOM ?

4. What is DOM ? DOM. • DOM stands for Document Object Model. • DOM is a W3C standard. • A standard way of representing the contents of an XML document as a tree of interconnected objects. • The next slide demonstrates this.

5. What is DOM ? Document root child_1 child_2 child_3 Text_1 Text_2 Text_3

6. What is DOM ? DOM. • In the preceding slide, the elements “root”, “child_1”, etc and the text node “Text_1”, etc are all DOM Nodes. • DOM defines a hierarchy of DOM Object Types starting with the DOM Node.

7. What is DOM ? The W3C DOM Hierarchy DOCUMENT DOCTYPE NODE ELEMENT ATTRIBUTE PROCESSINGINSTRUCTION ENTITY_REFERENCE NOTATION COMMENT CHARACTERDATA TEXT CDATA

8. What is DOM ? DOM. • DOM is also a set of APIs for app developers.

9. What is DOM ? User’s Understanding Of XML and DOM To effectively use PBDOM : • Some knowledge of XML (as defined in the W3C specs). • Basic understanding of the W3C DOM Tree.

10. Usage Usage [conclude]

11. Usage User’s Understanding Of XML and DOM • PBDOM uses some fundamental DOM concepts • the DOM node as a base object, • node parentage, node removal, node appending, etc. [conclude]

12. What is PBDOM ? What is PBDOM ?

13. What is PBDOM ? High-level DOM Management API. A complete API set to create, read, write and manipulate XML documents. • A large collection of non-visual classes. • Classes are hierarchical in nature and allow for polymorphic usage.

14. What is PBDOM ? High-level DOM Management API. • PBDOM is a PowerScript language extension and is built on PBNI technology. • It embraces native PowerBuilder datatypes like the boolean, date, datetime, long, etc. • It also uses standard PB facilities like PB arrays. • PS Developers will find the PBDOM classes and their methods natural and easy to use.

15. What is PBDOM ? High-level DOM Management API. • Efforts were taken to ensure that the PBDOM APIs provide users with great amount of leverage and productivity. • Incurs short learning curve. • Provides indisputable edge over other XML service providers. [conclude]

16. Design Goals Design Goals

17. Design Goals What PBDOM aims to achieve : • Instinctive user view of a DOM document... • Flexibility... • Incorporation of PowerScript Facilities... • “Live” Effects... • Building a PBDOM Tree from various input sources.

18. Design Goals Instinctive user view of a DOM document. • PBDOM portrays an XML document as a collection of interconnected objects (PBDOM_OBJECTs). • The PBDOM APIs indicate what these objects can do as well as what can be done with them.

19. Design Goals Instinctive user view of a DOM document. • PBDOM classifies different types of XML Nodes into different classes (albeit all deriving from the same base PBDOM_OBJECT class). • Each inherited object has its own specialised methods. • These classes will be covered later in the section on PBDOM classes.

20. Design Goals Flexibility • The W3C DOM APIs are low-level and are primarily intended for 3-GL developers who are likely to use C++ as their main development tool. • PBDOM aims to present a much higher-level API set.

21. Design Goals Flexibility • PBDOM allows DOM nodes to be moved around across nodes and across documents easily. Document 1 Document 2 <Parent_Element> <An_Element/> <Child_Element/> </Parent_Element>

22. Design Goals Flexibility • PBDOM allows DOM nodes to be moved around across nodes and across documents easily. Document 1 Document 2 <Parent_Element> <An_Element/> <Child_Element/> </Parent_Element> element.Detach() <Child_Element/> is now “stand-alone”

23. Design Goals Flexibility • PBDOM allows DOM nodes to be moved around across nodes and across documents easily. Document 1 Document 2 <Parent_Element/> <An_Element> <Child_Element/> </An_Element> element.SetParentObject() <Child_Element> is now “parent-owned” and “document-owned”

24. Design Goals Flexibility • PBDOM’s allows convenient re-naming of nodes. <Parent_Element> <Child_Element/> </Parent_Element>

25. Design Goals Flexibility • PBDOM’s allows convenient re-naming of nodes. <Parent_Element> <Child_Element/> element.SetName(“My_Child_Element”) </Parent_Element>

26. Design Goals Flexibility • PBDOM’s allows convenient re-naming of nodes. <Parent_Element> <My_Child_Element/> </Parent_Element> <Child_Element> has now been re-named to <My_Child_Element/>

27. Design Goals Flexibility • PBDOM allows setting and re-setting of the root element of a document. Document 1 <Parent_Element> <My_Element/> <Child_Element/> </Parent_Element> <My_Element> is a “Stand-Alone” PBDOM_ELEMENT.

28. Design Goals Flexibility • PBDOM allows setting and re-setting of the root element of a document. Document 1 <Parent_Element> <My_Element/> <Child_Element/> </Parent_Element> reference document.SetRootElement(element) We call SetRootElement() on the “Document 1” PBDOM_DOCUMENT.

29. Design Goals Flexibility • PBDOM allows setting and re-setting of the root element of a document. Document 1 <My_Element/> <My_Element> is now the Root Element of “Document 1”.

30. Design Goals PowerScript Facilities • PBDOM allows PB developers to use regular PowerScript constructs like arrays to obtain lists of DOM Objects. • The W3C DOM API defines the NodeList and the NamedNodeMap.

31. Design Goals PowerScript Facilities • Example 1. Let’s say we have a document as shown below and we wish to get all the child elements of <Parent_Element>. Document 1 <Parent_Element> <Child_Element_1/> <Child_Element_2/> <Child_Element_3/> </Parent_Element>

32. Design Goals PowerScript Facilities • Use PBDOM_ELEMENT class’s GetContent() with an unbounded PBDOM_OBJECT array. Document 1 Unbounded PBDOM_OBJECT array <Parent_Element> <Child_Element_1/> <Child_Element_2/> <Child_Element_3/> </Parent_Element> element::GetContent(ref pbdom_object_array)

33. Design Goals PowerScript Facilities • The PBDOM_OBJECT array will be filled with references to actual PBDOM_OBJECTs. Document 1 Unbounded PBDOM_OBJECT array <Parent_Element> <Child_Element_1/> PBDOM_OBJECT[1] <Child_Element_2/> PBDOM_OBJECT[2] <Child_Element_3/> PBDOM_OBJECT[3] </Parent_Element> element::GetContent(ref pbdom_object_array)

34. Design Goals PowerScript Facilities • Example 2. Let’s say we have the following single-element document : Document 1 <Parent_Element/>

35. Design Goals PowerScript Facilities • We wish to add 3 child elements to <Parent_Element>. We first create an array of 3 child elements : Document 1 Unbounded PBDOM_OBJECT array <Parent_Element/> PBDOM_ELEMENT[1] PBDOM_ELEMENT[2] PBDOM_ELEMENT[3]

36. Design Goals PowerScript Facilities • We then call on the SetContent() function on <Parent_Element> with reference to the array : Document 1 Unbounded PBDOM_OBJECT array <Parent_Element/> PBDOM_ELEMENT[1] PBDOM_ELEMENT[2] PBDOM_ELEMENT[3] element.SetContent(ref pbdom_object_array)

37. Design Goals PowerScript Facilities • The 3 child elements are now children of <Parent_Element> : Document 1 Unbounded PBDOM_OBJECT array <Parent_Element> <Child_Element_1/> PBDOM_ELEMENT[1] <Child_Element_2/> PBDOM_ELEMENT[2] <Child_Element_3/> PBDOM_ELEMENT[3] </Parent_Element> element.SetContent(ref pbdom_object_array)

38. Design Goals “Live” Effects • PBDOM provides a “live” object model where PBDOM_OBJECTs that are returned in an array refer to actual PBDOM_OBJECTs and modifications made on these array items will permanently affect the referenced PBDOM_OBJECTs.

39. Design Goals “Live” Effects • Let’s use a previous example where we obtained an array of child elements of a parent element : Document 1 Unbounded PBDOM_OBJECT array <Parent_Element> <Child_Element_1/> PBDOM_OBJECT[1] <Child_Element_2/> PBDOM_OBJECT[2] <Child_Element_3/> PBDOM_OBJECT[3] </Parent_Element> element.GetContent(ref pbdom_object_array)

40. Design Goals “Live” Effects • Now, each item of the array is a reference to an actual PBDOM_OBJECT. Thus, we can call its methods to permanently modify it : Document 1 Unbounded PBDOM_OBJECT array <Parent_Element> <Child_Element_1/> PBDOM_OBJECT[1] <Child_Element_2/> PBDOM_OBJECT[2] <Child_Element_3/> PBDOM_OBJECT[3] </Parent_Element> pbdom_object_array[2].SetName(“My_Child_Element”)

41. Design Goals “Live” Effects • PBDOM_OBJECT[2] now has its name changed to “My_Child_Element” : Document 1 Unbounded PBDOM_OBJECT array <Parent_Element> <Child_Element_1/> PBDOM_OBJECT[1] <My_Child_Element/> PBDOM_OBJECT[2] <Child_Element_3/> PBDOM_OBJECT[3] </Parent_Element> pbdom_object_array[2].SetName(“My_Child_Element”)

42. Design Goals Building a PBDOM Tree From Various Input Sources. • Source from which a DOM Tree can be constructed is not limited to a file. • Other input sources should also be available e.g. : • From a string. • From an SQL Query Result Set. • From an existing DOM sub tree. [conclude]

43. PBDOM Concepts PBDOM Concepts

44. PBDOM Concepts Base PBDOM_OBJECT class • PBDOM introduces the concept of a base PBDOM_OBJECT. It is a PowerScript class that represents an XML DOM node.

45. PBDOM Concepts Base PBDOM_OBJECT class • Abstract nature of a PBDOM_OBJECT • The PBDOM_OBJECT class is an “abstract” class. • It is not expected to be directly instantiated and used. • An example is shown next.

46. PBDOM Concepts Base PBDOM_OBJECT class • Abstract nature of a PBDOM_OBJECT

47. PBDOM Concepts Base PBDOM_OBJECT class • Abstract nature of a PBDOM_OBJECT • In the preceding example, an exception will be thrown and the exception text will be displayed in a message box :

48. PBDOM Concepts Stand-Alone, Document-Owned And Parent-Owned PBDOM_OBJECTs • PBDOM presents the concepts of “stand-alone”, “document-owned” and “parent-owned” PBDOM_OBJECTs. • These are states. • Nothing revolutionary but it promotes an Object-Oriented mindset. • It is a by-product of our view of DOM Nodes as objects that can be moved around from node to node and from document to document.

49. PBDOM Concepts Stand-Alone PBDOM_OBJECTs • Globally and locally created PBDOM_OBJECTs. • Not owned by any document or any parent. • Being stand-alone is just a state. • Whenever any PBDOM_OBJECT is created, it is created as a Stand-Alone Object. • Being stand-alone bears no special intrinsic privileges except that being tied to a parent or a document can prevent a PBDOM_OBJECT from being moved around.

50. PBDOM Concepts Document-owned PBDOM_OBJECTs • PBDOM_OBJECTs which have been added to a document either directly or indirectly. • A document-owned PBDOM_OBJECT may or may not have any parent.