MXi

MXi is the abbreviation for Mobilis XMPP on iOS. Although it was intended to provide an abstract interface for the communication with Mobilis Runtimes for iOS applications, it quickly became a much more advanced library that also serves as the basis for the OS X Runtime and OS X Runtime services.

A first step in every MXi application is the setup of a network connection to an XMPP server and a Mobilis Runtime (via the XMPP server). This section will briefly explain the steps to setup a connection successfully.

The MXiAbstractConnectionHandler class provides the interface to successfully setup connections and the method is called:

-launchConnectionWithJID:password:hostName:runtimeName:serviceType:port:

A detailed explanation of this method can be found in the source code header documentation of the MXiAbstractConnectionHandler class. Nonetheless the parameters will be explained to support the understanding of XMPP, MXi and Mobilis.

• The JID is used to connect to the XMPP server. At least a bare JID has to be provided here, i.e. martin@mobilis.inf.tu-dresden.de.
• The Password is the password the user with the given JID needs to authenticate against the XMPP server.
• The address of the XMPP server is specified by the hostName parameter. Do not provide protocol information here like http or https. The domain name of the XMPP server is sufficient.
• The runtimeName parameter addresses the Mobilis Runtime accessible via the specified host, i.e. runtime1 or mobilis.
• The service type is an internal parameter MXi uses to determine it's own role in the Mobilis environment.
  • Client applications use either SINGLE or MULTI depending on the service type the application communicates with.
  • Mobilis Objective-C services specify the SERVICE type here.
  • Mobilis Objective-C runtimes specify the RUNTIME type here.
• The ingress port of the XMPP server. Mostly 5222.

The Default Settings are used to provide information to the application that users either cannot know or do not want to enter when using the application. The file to the default Settings in MUST be names Settings.plist and must be included in the application bundle – which it will be by default.

An example file providing the settings file's structure can be found in the 9Cards project and is named Settings.plist.example for instance.

At the moment one field of the service dictionary within the settings file is important:

• The namespace provides the projects namespace that is specified in the respective XPD file. Make sure that the namespace in the XPD and the one in the settings file match case sensitively.

The MXi framework offers the functionality to securely store account information of users on iOS devices using the built-in Keychain functionality. The connection setup will not use at any point in time those stored credentials automatically so that the account information always have to be specified on the connection setup using the method explained at the beginning of this section.

However, it is highly recommended to use the API MXi provides. Check out the Account and AccountManager class header documentation.

This section applies for all use-cases of the MXi framework and covers the basic communication principle of Mobilis: The exchange of beans as a mean of remote communication of client and service application.

It is the application's responsibility to set all required data of the bean using the provided bean properties. The delivery of the bean will then be handled by the MXi framework.

The transmission of beans is handled by the MXiAbstractConnectionHandler and all its subclasses which inherit the functionality. Two methods are offered by the MXiAbstractConnectionHandler to transmit beans.

(1) MXiAbstractConnectionHandler: -sendBean:toService:
(2) MXiAbstractConnectionHandler: -sendBean:toJID:

Both Methods offer the same functionality with a difference in the determination of the recipient of the bean. Method (2) can be used for arbitrary recipient that cannot be known in advance by the MXi framework such as beans addressed to participants in multi-user chat rooms. In contrast to (2) method (1) is used when beans are sent to a Mobilis service. A detailed description for both methods can be found in the source code documentation in the MXiAbstractConnectionHandler header file. If the client communicates with a Single Instance Service it is not necessary to explicitly set the service as a parameter in (1). This parameter can be nil for single instance services and MUST NOT be nil for Multi Instance Services.

In the MXi framework no central point is defined where beans are processed. The MXiConnectionHandler class rather provides an interface for various runtime objects to register for notification on incoming beans.

MXiConnection: -addBeanDelegate:withSelector:forBeanClass:
MXiConnection: -removeBeanDelegate:forBeanClass:

A precise description of the methods and their parameters can be found in the class' header file. In a nutshell, every object can add itself as a delegate for incoming beans to the MXiConnection class. Moreover it is possible for every object so specify a message that will be sent by MXiConnection every time a bean of the intended type arrives. Multiple objects can register for the same bean class. This approach provides maximum freedom to the application developer and omits the necessity to implement callback methods although they might not be required. It is the registering objects responsibility to revoke the interest in a given bean itself.

The most common usage of MXi is as foundation of Mobilis Client applications on iOS. This section will explain the most crucial concepts of client app development with MXi for the iOS platform.

The connection establishment for client applications based on the MXi framework is straight forward. Refer to the Connection Setup section for detailed information and make sure to use the MXiConnectionHandler subclass of MXiAbstractConnectionHandler. The MXiConnectionHandler subclass is implemented as a singleton object perfectly suitable for client applications. All other functionality provided by MXi can be accessed using this singletion object. Moreover application developers do not need to take care where to keep a strong reference to the underlying XMPP connection.

The service discovery is executed automatically when the connection establishment process has finished successfully. As a consequence Single Instance Services do not need to run a service discovery during their life cycle.

Note: The service discovery discussed in this section is different from the XMPP service discovery specified in XEP-30. Throughout this document the term Service Discovery always means the Mobilis service discovery to detect Mobilis services and their respective service instances.

The class performing and controlling service discoveries is the MXiServiceManager class. An instance of this manager can be created using the +serviceManagerWithConnection:serviceType:namespace:delegate: class method. A detailed set of information on the parameters of this method can be found in the class' header file. A more convenient way to utilize the functionality of the MXiServiceManager is to use the instance referenced by the MXiAbstractConnectionHandler and its subclasses. The sole task left to do is adding the caller as a delegate of the service manager.

Finally, a service discovery is triggered by sending the -rediscoverServices message to the service manager. If the service manager was created using the class instantiation method, this message does not need to be sent to the manager; a service discovery will be commenced automatically.

The registered delegates of the class will be notified as soon as the service discovery completed.

Another task of the MXiServiceManager is to mediate the creation of a new service instance of a multi instance service. It is highly recommended to use the service manager instance held by the connection handler instead of creating a new service manager.

To launch the creation of a new service instance send the -createServiceWithName:andPassword: message to the MXiServiceManager. At the moment, only the service name is crucial. The password might be omitted or an empty string. If the creation of a new service instance finished successfully or failed, the service manager would notify all its delegates on the result. When the object sending the -createServiceWithName:andPassword message to the MXiServiceManager is interested in the result of the process it is mandatory for the object to add itself as a service manager delegate first.

With the development of the OS X Runtime application it became possible to develop Mobilis Services natively on OS X. If you plan to develop a new Objective-C service or intent to continue development of an already existing service, follow this section.

OS X Mobilis Services are still experimental. This section will be described in a more detailed fashion later.

As it was previously mentioned, the MXi framework serves as the foundation of the Mobilis4Mac Runtime application. If it is your intention to continue development of the OS X runtime, continue reading this section.

The OS X Mobilis runtime application is still experimental. This section will be described in a more detailed fashion later.

MXi is backed by an still incomplete but up-to-date and rather extensive Header file Source Code documentation. The respective header file documentation is also available as docset that can be installed to Xcode in order to better support MXi based application development.

Note: The following steps only work using Mac OS X!

1. If not already done, clone the Mobilis repo that contains the MXi project.
2. If not already installed, install Cocoapods by running gem install cocoapods
   • Run pod install in the MXi root directory (the directory containing the MXi Xcode project file)
   • For detailed Information check the Getting Started section for iOS and OS X projects.
3. Open the MXi project using the workspace file (MXi.xcworkspace)
4. In the upper left corner of the Xcode Window you can find the targets. Right next to the Run and Stop Buttons.
5. The default target should read 'MXi.framework'. Click it and change the selection to 'Documentation'
6. Click the 'Run' button in the upper left corner of the Xcode project. (looks like a play button)
7. The documentation is now build and installed to Xcode.
8. If everything works fine Xcode Displays a Build Succeeded message.
9. You can now access the MXi documentation from every project opened in Xcode.
10. You can display all installed docsets including MXi by hitting cmd+0 shortcut.