xml_objects.rst

Xml Objects

Jaxl library works with custom XML implementation which is similar to inbuild PHP XML functions but is lightweight and easy to work with.

JAXLXml

JAXLXml is the base XML object. Open up :ref:`Jaxl interactive shell <jaxl-instance>` and try some xml object creation/manipulation:

>>> ./jaxlctl shell
jaxl 1>
jaxl 1> $xml = new JAXLXml(
.......     'dummy',
.......     'dummy:packet',
.......     array('attr1' => 'friend@gmail.com', 'attr2' => ''),
.......     'Hello World!'
....... );
jaxl 2> echo $xml->to_string();
<dummy xmlns="dummy:packet" attr1="friend@gmail.com" attr2="">Hello World!</dummy>
jaxl 3>

JAXLXml constructor instance accepts following parameters:

• JAXLXml($name, $ns, $attrs, $text)
• JAXLXml($name, $ns, $attrs)
• JAXLXml($name, $ns, $text)
• JAXLXml($name, $attrs, $text)
• JAXLXml($name, $attrs)
• JAXLXml($name, $ns)
• JAXLXml($name)

JAXLXml draws inspiration from StropheJS XML Builder class. Below are available methods for modifying and manipulating an JAXLXml object:

• t($text, $append = false)

  update text of current rover

• c($name, $ns = null, $attrs = array(), $text = null)

  append a child node at current rover

• cnode($node)

  append a JAXLXml child node at current rover

• up()

  move rover to one step up the xml tree

• top()

  move rover back to top element in the xml tree

• exists($name, $ns = null, $attrs = array())

  checks if a child with $name exists, return child JAXLXml if found otherwise false. This function returns at first matching child.

• update($name, $ns = null, $attrs = array(), $text = null)

  update specified child element

• attrs($attrs)

  merge new attrs with attributes of current rover

• match_attrs($attrs)

  pass a kv pair of $attrs, return bool if all passed keys matches their respective values in the xml packet

• to_string()

  get string representation of the object

JAXLXml maintains a rover which points to the current level down the XML tree where manipulation is performed.

XMPPStanza

In the world of XMPP where everything incoming and outgoing payload is an JAXLXml instance code can become nasty, developers can get lost in dirty XML manipulations spreaded all over the application code base and what not. XML structures are not only unreadable for humans but even for machine.

While an instance of JAXLXml provide direct access to XML name, ns and text, it can become painful and time consuming when trying to retrieve or modify a particular attrs or children. I was fed up of doing getAttributeByName, setAttributeByName, getChild etc everytime i had to access common XMPP Stanza attributes.

XMPPStanza is a wrapper on top of JAXLXml objects. Preserving all the functionalities of base JAXLXml instance it also provide direct access to most common XMPP Stanza attributes like to, from, id, type etc. It also provides a framework for adding custom access patterns.

XMPPMsg, XMPPPres and XMPPIq extends XMPPStanza and also add a few custom access patterns like body, thread, subject, status, show etc.

Here is a list of default access patterns:

1. name
2. ns
3. text
4. attrs
5. children
6. to
7. from
8. id
9. type
10. to_node
11. to_domain
12. to_resource
13. from_node
14. from_domain
15. from_resource
16. status
17. show
18. priority
19. body
20. thread
21. subject