User Guide
1 - What is Muki?
2 - Requirements for using Muki
3 - How do you use Muki?
4 - Defining a service
5 - Generating code
6 - Integrating generated code in the applications
7 - Full example
Muki is a tool for rapidly generating code that automates the communication between iOS clients and a JEE server application through RESTful services. Starting from the description of the service, Muki generates additional classes in Swift and Objective-C that can be easily integrated into iOS applications and Java classes that allow to quickly implement a RESTful service following the standard JAX-RS.
The entire HTTP communication process and data serialization and conversion between the server and client applications is done automatically by the generated classes.
So with Muki, applications written for iOS can easily connect with RESTful services implemented in Java. The generated code is 100% readable and clean. Muki generated classes abstract away the communication between clients and server and hide the details of the communication carried out in HTTP (GET, POST, PUT and DELETE methods) and the serialization of objects traveling in XML and JSON. The following code snippet shows the invocations performs by an iOS application to communicate with a remote server, using the classes generated by Muki.
// Instantiate the proxy to access the service
let remoteService = StoreService(url: "http://muki/demo-server/store")
// Send an object to server
var localError: NSError?
var newCustomer = Customer()
newCustomer.name = @"Paul Smith";
newCustomer.telephone = @"678 900 000";
remoteService.addCustomer(newCustomer, error: &localError)
// Retrieve a object from the server
let anotherCustomer = remoteService.getCustomerId("12345667", error: &localError)
- Java installation (JRE 1.5+)
- muki-generator-1.4.jar (Muki distribution)
- commons-collections-3.2.1.jar, commons-lang-2.4.jar, velocity-1.6.1.jar
- Note that other versions of the libraries might also work, but those are the versions that we used in our tests.
- You need Xcode 4.5.x or superior
- A framework that implements the JAX-RS specification, like RESTEasy or other
- Optional: you can integrate the generated classes with Spring Framework or use any other framework. In our tests, we deployed the service on Google App Engine using RESTEasy v2.0.1 libraries and Spring.
Creating a service with Muki is summarized in three steps:
STEP 1: Create the service definition using an XML document. The definition declares the operations exposed by the service and the data structures representing the parameters and resources.
STEP 2: Calling the code generation process from Java.
STEP 3: Integrating generated classes in your applications.
Creating RESTful services with Muki begins with a description of the data structures and operations for serving the requests sent by clients (iOS). The description of the service must be available in an XML document.
The service description has two parts: one is the definition of the models, which are data structures that represent the input and output parameters (resources), on the other hand are the controllers for processing the HTTP requests and serve the web service resources.
The following snippet shows the structure of a Muki service definition. The complete schema of the XML document is available in muki-service-description-v01.xsd.
<ns2:project name="MukiDemo" xmlns:ns2="http://muki/service-description/">
<model-definitions ... >
<model name="CustomerData">
...
</model>
...
</model-definitions>
<controller-definitions ... >
<controller name="CustomerController" ... >
<get-operation ... />
<post-operation ... />
<put-operation ... />
<delete-operation ... />
...
</controller>
...
</controller-definitions>
</ns2:project>
In Muki, a model is an object that represents the application data and is used to send and receive information between iOS clients and the server. A model can be seen as a class representing a web resource. With the description of the models, Muki generates classes that automate the process of serializing and deserializing objects in JSON and XML. Generated Java classes include JAXB annotations that handle the serialization. For the serialization of Swift and Objective-C classes, Muki generates support classes also in Swift and Objective-C, respectively.
The following snippet shows the definition of models:
<model-definitions java-package="...">
<model name="Model1">
<simple-attr type="..." name="..." />
<simple-attr type="..." name="..." />
...
</model>
<model name="Model2">
<simple-attr type="..." name="..." />
<list-attr items-type="Model1" name="items" />
...
</model>
...
</model-definitions>
The definitions of the models must be inside an <model-definitions java-package = " ... "> element. The value of java-package attribute is the name of the Java package where Muki generates the Java classes (beans). Each model is defined with a <model name = " ... "> element. The value of the name attribute is the name used to generate the corresponding class in Java, Swift and Objective-C. Each model has one or more attributes, which can be either simple or represent list types. Simple attributes can be basic types (boolean, integer, string, etc.) or references to other models. List attributes can only have references to other models, it is not possible to have lists of basic types.
The following table shows the basic types used by Muki and their correspondence with Java, Swift and Objective-C data types when generating classes.
| Muki basic type | Java type | Swift type | Objective-C type |
|---|---|---|---|
| STRING | String | String | NSString |
| LONG | long | Int64 | long long |
| INT | int | Int | NSInteger |
| DOUBLE | double | Double | double |
| BOOLEAN | boolean | Bool | BOOL |
Take for example the following diagram with two models. There is a model called TrackData that has attributes of basic types (String, Long, Boolean, etc.) And there is a model called AlbumData having 2 attributes of type String, a reference to TrackData and an attribute that is a list of TrackData:
The following fragment corresponds to the description required by Muki to create classes in Java, Swift and Objective-C for the previous model:
<model-definitions java-package="demo.model">
<model name="TrackData">
<simple-attr type="STRING" name="title" />
<simple-attr type="INT" name="lengthInSeconds" />
<simple-attr type="LONG" name="catalogId" />
<simple-attr type="BOOLEAN" name="newRelease" />
<simple-attr type="DOUBLE" name="price" />
</model>
<model name="AlbumData">
<simple-attr type="LONG" name="catalogId" />
<simple-attr type="STRING" name="title" />
<simple-attr type="STRING" name="artist" />
<simple-attr type="TrackData" name="mainTrack" />
<list-attr items-type="TrackData" name="tracks" />
</model>
</model-definitions>
With the above definition, Muki generates the following classes in Java. The classes have JAXB annotations for XML and JSON serialization:
@XmlRootElement(name = "trackdata")
@XmlType(name = "TrackData", propOrder = {})
public class TrackData implements Serializable {
private static final long serialVersionUID = 1L;
private String title;
private int lengthInSeconds;
private long catalogId;
private boolean newRelease;
private double price;
@XmlElement(name = "title")
public String getTitle() {
return this.title;
}
public void setTitle(String newValue) {
this.title = newValue;
}
@XmlAttribute(name = "price")
public double getPrice() {
return this.price;
}
...
}
And also:
@XmlRootElement(name = "albumdata")
@XmlType(name = "AlbumData", propOrder = {})
public class AlbumData implements Serializable {
private static final long serialVersionUID = 1L;
private long catalogId;
private String title;
private String artist;
private TrackData mainTrack;
private List<TrackData> tracks = new ArrayList<TrackData>();
@XmlElement(name = "title")
public String getTitle() {
return this.title;
}
@XmlElement(name = "mainTrack")
public TrackData getMainTrack() {
return this.mainTrack;
}
public void setMainTrack(TrackData newValue) {
this.mainTrack = newValue;
}
@XmlElementWrapper(name = "tracks")
@XmlElement(name = "trackdata")
public List<TrackData> getTracks() {
return this.tracks;
}
public void addToTracks(TrackData aValue) {
this.tracks .add(aValue);
}
public void removeFromTracks(TrackData aValue) {
this.tracks .remove(aValue);
}
...
}
With the above definition, Muki generates the following classes in Swift. Note that unlike Java, Swift classes have no annotations and the whole process of XML and JSON serialization is performed by auxiliary classes.
class TrackData : NSObject {
var title = ""
var lengthInSeconds = 0
var catalogId: Int64 = 0
var newRelease = false
var price = 0.0
}
And also:
class AlbumData : NSObject {
var catalogId: Int64 = 0
var title = ""
var artist = ""
var mainTrack: TrackData?
var tracks = [TrackData]()
func addToTracks(anObject: TrackData) {
...
}
func removeFromTracks(anObject: TrackData) {
...
}
}
The controllers described the service operations that deal with incoming requests to get, add, update and delete server web resources. With the definition of the controllers, Muki generates classes that simplify the communication between iOS clients and the server. Thus, the remote communication becomes simple method invocations between objects. The generated classes are responsible for establishing the communication between iOS clients and the server following RESTful principles by using the following HTTP methods: GET, POST, PUT and DELETE.
The following snippet shows the definition of the controllers:
<controller-definitions java-package="...">
<controller http-path="..." name="Controller1" >
<get-operation http-path="..." return-type="..." name="..." serialization-type="...">
<path-param name="..." />
</get-operation>
...
<post-operation serialization-type="..." http-path="..." param-type="..." return-type="..." name="..." />
<put-operation serialization-type="..." http-path="..." param-type="..." name="..." />
<delete-operation http-path="..." name="...">
<path-param name="..." />
</delete-operation>
</controller>
<controller http-path="..." name="Controller2" >
...
</controller>
</controller-definitions>
As our goal is to create a RESTful service, the service operations are mapped directly to HTTP methods invocations. So, to send invocations from iOS, Muki uses the definition of the controllers to generate stubs that prepare and send HTTP invocations. To process the requests on the JEE server, Muki uses the definition of the controllers to create classes with annotations that follow the JAX-RS specification.
GET operations return resources. The following snippet shows all attributes and sub-elements to define a GET operation with Muki.
<get-operation http-path="/customers/{customerId}/{orderId}" return-type="OrderData" name="getOrder" serialization-type="json">
<path-param name="customerId" />
<path-param name="orderId" />
</get-operation>
The following table summarizes all the attributes to define a GET operation with Muki:
| Attributes | Comments |
|---|---|
| name | This is the name of the operation and must be unique. In Java, this value is used to name of the corresponding method in the controller. In Swift and Objective-C it is used as the first keyword of the method defined in the stub. |
| http-path | The path to invoke the operation. It can be an expression formed with parameters. For example: "/customers/{id}/{orderId}". If the path contains parameters, you must declare them with sub-elements <path-param ... /> and <query-param ... />. |
| return-type | It's the result type. The value can be STRING or the name of a model. |
| serialization-type | It takes the value "json" or "xml". It indicates the format to serialize the resource (model) returned by the operation. Required if the value of return-type is the name of a model. |
The value of http-path may include parameters {param} to make the URI used to invoke the operation more flexible. If parameters are included, you need to add sub-elements <path-param name="param1" /> and <query-param name="param2" /> so that Muki can build the methods correctly. The names of the parameters that appear in http-path must match the names declared in the sub-elements.
Take for example the following definition of an operation:
<get-operation http-path="/customers/{customerId}/{orderId}" return-type="OrderData" name="getOrder" serialization-type="json">
<path-param name="customerId" />
<path-param name="orderId" />
</get-operation>
With the above definition, Muki generates the following Java method in the controller:
@GET
@Path("/customers/{customerId}/{orderId}")
@Produces("application/json")
public OrderData getOrder(@PathParam("customerId") String customerId, @PathParam("orderId") String orderId) {
OrderData result = this.getDelegate().getOrder(customerId, orderId);
...
}
In the stub class written in Swift, Muki adds the following function:
func getOrder(customerId: String, orderId: String, error outError: NSErrorPointer) -> OrderData? {
...
}
In the stub interface in Objective-C, Muki declares the following method:
- (OrderData*)getOrderCustomerId: (NSString *)aString1 orderId: (NSString *)aString2 error: (NSError **)error;
In general, POST operations are used to add new resources and PUT operations to update the properties of existing resources on the server. The following snippet shows all attributes and sub-elements to define POST and PUT operations in Muki. Its structure is similar.
<post-operation http-path="/customers/{customerId}/{orderId}" param-type="OrderData" return-type="OrderData" name="addOrder" serialization-type="json">
<path-param name="customerId" />
<path-param name="orderId" />
</post-operation>
<put-operation http-path="/customers/{customerId}/{orderId}" param-type="OrderData" return-type="OrderData" name="updateOrder" serialization-type="json">
<path-param name="customerId" />
<path-param name="orderId" />
</put-operation>
The following table summarizes all the attributes to define POST / PUT operations with Muki:
| Attributes | Comments |
|---|---|
| name | This is the name of the operation and must be unique. In Java, this value is used to name of the corresponding method in the controller. In Swift and Objective-C it is used as the first keyword of the method defined in the stub. |
| http-path | The path to invoke the operation. It can be an expression formed with parameters. For example: "/customers/{id}/{orderId}". If the path contains parameters, you must declare them with sub-elements <path-param ... /> and <query-param ... />. |
| param-type | PUT and POST operations can send an object (model) as a parameter. The param-value type indicates the type of the parameter and can be STRING or the name of a model. If this attribute is not set, it means that the operation has no input parameter. |
| return-type | It the result type. The value can be STRING or the name of a model. |
| serialization-type | It takes the value "json" or "xml". It indicates the format to serialize the resource (model) returned by the operation. Required if the value of return-type is the name of a model. |
The value of http-path may include parameters {param} to make the URI used to invoke the operation more flexible. See the explanation in the GET operations section.
Take for example the following definition of a POST operation and another PUT:
<post-operation http-path="/customers/{customerId}/{orderId}" param-type="OrderData" return-type="OrderData" name="addOrder" serialization-type="json">
<path-param name="customerId" />
<path-param name="orderId" />
</post-operation>
<put-operation http-path="/customers/{customerId}/{orderId}" param-type="OrderData" return-type="OrderData" name="updateOrder" serialization-type="json">
<path-param name="customerId" />
<path-param name="orderId" />
</put-operation>
With the above definition, Muki generates the following Java methods in the controller:
@POST
@Path("/customers/{customerId}/{orderId}")
@Consumes("application/json")
@Produces("application/json")
public OrderData addOrder(@PathParam("customerId") String customerId, @PathParam("orderId") String orderId, OrderData param) {
return this.getDelegate().addOrder(customerId, orderId, param);
}
@PUT
@Path("/customers/{customerId}/{orderId}")
@Consumes("application/json")
@Produces("application/json")
public OrderData updateOrder(@PathParam("customerId") String customerId, @PathParam("orderId") String orderId, OrderData param) {
return this.getDelegate().updateOrder(customerId, orderId, param);
}
In the stub class written in Swift, Muki adds the following functions:
func addOrder(anObject: OrderData, customerId: String, orderId: String, error outError: NSErrorPointer) -> OrderData? {
...
}
func updateOrder(anObject: OrderData, customerId: String, orderId: String, error outError: NSErrorPointer) -> OrderData? {
...
}
In the stub interface in Objective-C, Muki declares the following methods:
- (OrderData*)addOrder: (OrderData *)anObject customerId: (NSString *)aString2 orderId: (NSString *)aString3 error: (NSError **)error;
- (OrderData*)updateOrder: (OrderData *)anObject customerId: (NSString *)aString2 orderId: (NSString *)aString3 error: (NSError **)error;
DELETE operations remove resources from the server. The following snippet shows all attributes and sub-elements to define DELETE operations with Muki:
<delete-operation http-path="/customers/{customerId}/{orderId}" name="deleteOrder">
<path-param name="customerId" />
<path-param name="orderId" />
</delete-operation>
The following table summarizes all the attributes to define a DELETE operation with Muki:
| Attributes | Comments |
|---|---|
| name | This is the name of the operation and must be unique. In Java, this value is used to name of the corresponding method in the controller. In Swift and Objective-C it is used as the first keyword of the method defined in the stub. |
| http-path | The path to invoke the operation. It can be an expression formed with parameters. For example: "/customers/{id}/{orderId}". If the path contains parameters, you must declare them with sub-elements <path-param ... /> and <query-param ... />. |
The value of http-path may include parameters {param} to make the URI used to invoke the operation more flexible. See the explanation in the GET operations section.
Take for example the following definition of a DELETE operation:
<delete-operation http-path="/customers/{customerId}/{orderId}" name="deleteOrder">
<path-param name="customerId" />
<path-param name="orderId" />
</delete-operation>
With the above definition, Muki generates the following Java method in the controller:
@DELETE
@Path("/customers/{customerId}/{orderId}")
public void deleteOrder(@PathParam("customerId") String customerId, @PathParam("orderId") String orderId) {
this.getDelegate().deleteOrder(customerId, orderId);
}
In the stub class written in Swift, Muki adds the following function:
func deleteOrder(customerId: String, orderId: String, error outError: NSErrorPointer) {
...
}
In the stub interface in Objective-C, Muki declare the following method:
- (void)deleteOrderCustomerId: (NSString *)aString1 orderId: (NSString *)aString2 error: (NSError **)error;
Once the service description is finished, you run the code generation process. This is a program written in Java that is invoked from the command-line interface or by using an Ant script. In both cases, in addition to the Muki library (muki-generator-1.4.jar), you must add the following libraries to the classpath: commons-collections-3.2.1.jar, commons-lang-2.4.jar, velocity-1.6.1.jar. Note that other versions of the libraries might also work.
Indeed, you must do two invocations of the process: one to generate Java classes, another one to generate Swift or Objective-C classes.
When you invoke the code generation process, Muki first evaluates the service definition (XML). If the definition has no errors, Muki generates the classes in the output directory. If the definition has errors, Muki lists the problems encountered. In this case, you must fix the issues and re-invoke the code generation process.
Command syntax: muki.tool.MukiGenerator <option> <path-to-definition.xml> <output-directory>
where:
- <option>: must be generate-java, generate-swift or generate-objc, to indicate whether Muki generates Java server classes or the classes for the iOS Cocoa client, respectively.
- <path-to-definition.xml>: the full path to the XML file that has the service definition
- <output-directory>: full path to the directory where Muki generates the classes. The directory must exist.
Example of an invocation to generate Java classes:
>java -classpath ./lib/muki-generator-1.4.jar:./lib/commons-collections-3.2.1.jar:./lib/commons-lang-2.4.jar:./lib/velocity-1.6.1.jar muki.tool.MukiGenerator generate-java /Users/gabriel/temp/project/code-generation/muki-definitions.xml /Users/gabriel/temp/project/generated-java
<target name="generate-java-server">
<path id="tools.classpath">
<fileset dir="${basedir}/lib">
<include name="*.jar" />
</fileset>
</path>
<taskdef name="muki-generator" classpathref="tools.classpath" classname="muki.tool.AntTask"/>
<mkdir dir="${server.generation.dir}"/>
<muki-generator
option="generate-java"
projectFile="${basedir}/muki-definitions.xml"
outputDirectory="${server.generation.dir}" />
</target>
Important notice: none of the classes generated by Muki should be modified manually. If changes are required, you must change the service definition (XML) and re-launch the code generation process.
The following diagram shows the sequence of invocations for getting server resources. The iOS application invokes a method in the stub generated by Muki (Swift/Objective-C). The stub is responsible for processing the call and sending the HTTP request (GET) to the server. The HTTP request arrives at the server, it is processed and becomes the method invocation of the controller class generated by Muki (Java). The controller in turn invokes the delegate that implements the functionality of the service. The delegate implements a Java interface also generated by Muki.
The following table summarizes the classes generated by Muki for the Java application (server), when invoking the process with the option: generate-java:
| Class / Interface | Comments |
|---|---|
| RestApplication | This is the class that manages JAX-RS integration. Returns the instance of the service that will listen for requests. This class should not be modified manually! |
| Model | For each <model ... > definition, Muki generates a class with JAXB annotations for the serialization in XML and JSON. These classes are the beans that travel between the iOS clients and the server. These classes should not be changed manually! |
| Controllers | For each <controller ... > definition, Muki generates a class with JAX-RS annotations. These controllers receive and process HTTP requests sent by clients. The controllers have methods for the operations declared in: <get-operation ... >, <post-operation ... >, <put-operation ... > and <delete-operation ... >. The controllers invoke other classes called Delegates. That's where you implement the service logic. The controllers classes must not be changed manually! |
| ControllerDelegates | These interfaces declare all the operations of the service controllers. The developer must implement these interfaces with the concrete behavior of the service and also integrate the Delegates in the controllers. When a request comes to a controller, it invokes the delegate that it is associated with. Muki generates a delegate interface for each controller. The definition of Delegates should not be changed manually! |
| MukiExceptionMapper | This is a support class that implements a mapper that handles the exceptions that are thrown when a resource is not found on the server. This class should not be changed manually! |
| MukiResourceNotFoundException | It is a support class to represent exceptions that are thrown when a resource is not found on the server. This class should not be changed manually! |
The following table summarizes the classes generated by Muki for the iOS application (client), when invoking the process with the option:generate-swift:
| Class / Interface | Comments |
|---|---|
| Model | For each definition of <model ... >, Muki generates a class representing the resources and objects traveling between the iOS clients and the server. These objects are serialized in XML and JSON. |
| Model parser delegates | Helper classes that handle XML serialization. It generates a delegate for each model. These classes implement the NSXMLParserDelegate protocol |
| MukiControllerStub | It is the superclass of all stubs and implements the functionality to communicate with the remote server |
| Controller Stubs | They represent the controllers on iOS client side. Client applications invoke operations on the stubs and the stubs encode and send HTTP requests to the server controllers. Muki creates a stub for each server controller |
| XmlSerializer XmlAttribute ObjectParserDelegate | Helper classes used to serialize in XML |
| JsonSerializer JsonDeserializer |
To handle the serialization from JSON. Framework is based on the SBJson framework |
| SwiftyJSON.swift | Source code of SwiftyJSON (this is not a library!) |
The following table summarizes the classes generated by Muki for the iOS application (client), when invoking the process with the option:generate-objc:
| Class / Interface | Comments |
|---|---|
| Model | For each definition of <model ... >, Muki generates a class representing the resources and objects traveling between the iOS clients and the server. These objects are serialized in XML and JSON. |
| Model parser delegates | Helper classes that handle XML serialization. It generates a delegate for each model. These classes implement the NSXMLParserDelegate protocol |
| MukiControllerStub | It is the superclass of all stubs and implements the functionality to communicate with the remote server |
| Controller Stubs | They represent the controllers on iOS client side. Client applications invoke operations on the stubs and the stubs encode and send HTTP requests to the server controllers. Muki creates a stub for each server controller |
| XmlSerializer XmlAttribute ObjectParserDelegate | Helper classes used to serialize in XML |
| JsonSerializer JsonDeserializer |
To handle the serialization from JSON. Framework is based on the SBJson framework |
| NSDataBase64 | Implements an extension to NSData allowing Base64 encoding and decoding. The original implementation was made by Matt Gallagher (Cocoa with love) |
| SBJson classes | Source code of the SBJson framework |
Generally speaking, all generated classes are compatible with the ARC (Automatic Reference Counting) memory management scheme.
To integrate the classes generated by Muki, do the following:
STEP 1) In the application project (Xcode), use the ARC memory management model
PASO 2) Add all generated classes in the project, with the option Add Files to ...
PASO 3) Compile. No compilation errors should appear.
PASO 4) In the application code, instantiate stubs and models and to make the service invocations. For example:
Swift:
let newTrack = TrackData()
newTrack.title = "New track"
newTrack.lengthInSeconds = 247
newTrack.price = 1.25
newTrack.newRelease = true
newTrack.catalogId = 0
let stub = TrackControllerStub(url: "http://localhost:8080/demo-server/store")
var localError: NSError?
let addedTrack = stub.addTrack(newTrack, error: &localError)
let myTrack = stub.getTrack("3", error: &localError)
Objective-C:
TrackData *newTrack = [[TrackData alloc] init];
newTrack.title = @"New track";
newTrack.lengthInSeconds = 247;
newTrack.price = 1.25;
newTrack.newRelease = YES;
newTrack.catalogId = 0;
TrackControllerStub *stub = [[TrackControllerStub alloc] initControllerUrl: @"http://localhost:8080/demo-server/store"];
NSError *error;
TrackData *addedTrack = [stub addTrack:newTrack error:&error];
TrackData *myTrack = [stub getTrackId:@"3" error:&error];
Note that *error is an output parameter sent by reference so we can see if an error occurred during the remote server invocation. This is the correct way to handle errors in Cocoa. See more details.
STEP 1) Add the libraries of a framework that implements the specification JAX-RS, like RESTEasy or other
STEP 2) Add the Java classes generated by Muki
STEP 3) Create the classes that implement the *Delegate interfaces. These interfaces contain all the methods of controllers generated by Muki
STEP 4) Integrate the classes that implement the *Delegate interfaces with the controllers. This can be done by directly instantiating the classes in the controllers, but you may use the Spring Framework and its dependency injection mechanism
STEP 5) Declare the full name of the class MukiExceptionMapper as a parameter in the web.xml configuration file of the application. The name of the parameter depends on the implementation of JAX-RS you use. The following is the declaration required by Resteasy:
<context-param>
<param-name>resteasy.providers</param-name>
<param-value>package.name.MukiExceptionMapper</param-value>
</context-param>
We provide a complete demo that shows how Muki generates the classes for an iOS client that connects to a RESTful service implemented in JEE.
The service in the example uses the RESTEasy implementation of JAX-RS and Spring Framework to connect the parts (inyecting dependencies, etc).
To run the demo: download the file /Muki/example/Muki_demo.zip. Unzip the file and follow the instructions available in the instructions_en.html file you'll find inside. The demo includes all necessary libraries so you can have it up and running quickly.