1
0
Fork 0
mirror of https://github.com/vanitasvitae/Smack.git synced 2024-12-25 03:57:58 +01:00
Smack/documentation/developer/provider.md
Florian Schmaus 4133eb175c Replace XPP3 by XmlPullParser interface wrapping StAX and XPP3
Introducing Smack's own XmlPullParser interface which tries to stay as
compatible as possible to XPP3. The interface is used to either wrap
StAX's XMLStreamReader if Smack is used on Java SE, and XPP3's
XmlPullParser if Smack is used on on Android.

Fixes SMACK-591.

Also introduce JUnit 5 and non-strict javadoc projects.
2019-05-06 22:10:50 +02:00

2.5 KiB

Smack Providers

Providers are responsible for parsing the XMPP XML stream into new Java objects.

Provider Design

Assume you want to parse the following stanza extension element

<myExtension attrFoo='fourthyTwo'>
  <myElement>Foo is greater then Bar</myElement>
  <myInfo alpha='true' delta='-1337'/>
</myExtension>

then the related provider would look like this

public MyExtension parse(XmlPullParser parser, int initialDepth) {
  MyElement myElement = null;
  MyInfo myInfo = null;
  String attrFoo = parser.getAttributeValue("", "attrFoo");

  // Main parsing loop, use a loop label instead of "boolean done"
  outerloop: while(true) {
    // Make sure to have already parse all attributes of the outermost element,
    // i.e. 'attrFoo' of 'myExtension' in this example. Then advance the parser
    XmlPullParser.Event event = parser.next();

    // Use switch/case of int instead of a if/else-if cascade
    switch (event) {
    case START_ELEMENT:
      // Determine the name of the element which start tag we are seeing
      String name = parser.getName();
      // We can use switch/case of Strings since Java7, make use of its advantages
      // and collect the values of the sub elements. If the sub elements are more
      // complex then those of this example, consider creating extra *private static*
      // parsing methods for them.
      switch(name) {
      case "myElement":
        // You should only use XmlPullParser.nextText() when the element is
        // required to have a text.
        myElement = new MyElement(parser.nextText());
        break;
      case "myInfo";
        // Use ParserUtils to parse Java primitives
        boolenan alpha = ParserUtils.getBooleanAttribute(parser, "alpha");
        int delta = ParserUtils.getIntegerAttribute(parser, "delta");
        myInfo = new MyInfo(alpha, delta);
        break;
      }
      break;
    case END_ELEMENT:
      // The abort condition with the break labeled loop statement
      if (parser.getDepth() == initialDepth) {
        break outerloop;
      }
      break;
    default:
      // Catch all for incomplete switch (MissingCasesInEnumSwitch) statement.
      break;
    }
  }

  // Create the actual class at the very end, design the classes as immutable as possible
  return new MyExtension(attrFoo, myElement, myInfo);
}

Common Pitfalls

Use a long instead of int when the XML schema says xs:unsignedInt, because Java's int range is to small for this XML numeric data type.