Smack/DEVELOPING.md

Building Smack

Linux

Building Smack is as simple as

git clone git@github.com:igniterealtime/Smack.git
cd Smack
gradle assemble

Mac

Smack requires a case-sensitive file system in order to build. Unfortunately, the macOS operating system is case-insensitive by default. To get around this, you can create a case-sensitive disk image to work from.

1. Launch Disk Utility (Applications > Utilities)
2. Click the +, or go to Edit > Add APFS Volume
3. Give it a name, e.g. "Smack"
4. Change the format to "APFS (Case-sensitive)"
5. Click Add

It'll auto-mount into /Volumes, e.g. /Volumes/Smack

cd /Volumes/Smack
git clone git@github.com:igniterealtime/Smack.git
cd Smack
gradle assemble

Windows

Smack requires a case-sensitive file system in order to build. Unfortunately, Windows NTFS is case-insensitive by default. To get around this, you can set specific folders as case-sensitive (requires Windows 10 v1803 or higher).

In an Administrator console:

fsutil.exe file SetCaseSensitiveInfo C:\git\Smack enable
cd \git\Smack
git clone git@github.com:igniterealtime/Smack.git
cd Smack
gradle assemble

IDE Config

Eclipse

Import IDE settings from ./resources/eclipse/ to configure proper ordering of imports and correct formatting that should pass the CheckStyle rules.

IntelliJ IDEA

Import Java Code Style settings from ./resources/intellij/smack_formatter.xml to configure import optimisation and code formatting to pass the CheckStyle rules when building or submitting PRs.

We've noticed, at time of writing, that IntelliJ often requires a restart when applying new rules - no amount of OK/Apply will do the trick.

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.

Stanzas

General Rules

All classes which subclass TopLevelStreamElement and ExtensionElement must either

1. be immutable (and ideally provide a Builder)
2. implement TypedCloneable

and must be Serializable. The reason that it must be either 1. or 2. is that it makes no sense to clone an inmutable instance. The preferred option is 1.

Note that there is legacy code in Smack which does not follow these rules. Patches are welcome.

ExtensionElement

Extension elements are XML elements that are used in various parts and levels of stanzas.

The static from(Stanza) Method

Every ExtensionElement class must have a static from() method that retrieves that extension for a given Stanza (if any).

Sample Code

public static RSMSet from(Stanza) {
  return packet.getExtension(ELEMENT, NAMESPACE);
}

Sometimes certain ExtensionElement's are only found in one stanza type, in that case, specify the parameter type. For example public static CarbonExtension getFrom(Message).