MVVM in iOS

MVVM ("model/view/view-model") is design pattern that helps promote a separation of concerns in software development. It is an extension of the well-known "model/view/controller" (MVC) pattern that is often used in user interface design.

In a traditional MVC application, a "controller" object is used to mediate interaction between two other objects known as the "model" and the "view". The model is an abstract representation of data managed by the application, and the view is a visual representation of the data contained in the model. The controller notifies the view of changes to the model, and updates the model in response to user input events received from the view.

MVVM expands on MVC by further decoupling the view from the controller. Instead of requiring the controller to explicitly manage the view's state, a view in an MVVM application uses data binding to be automatically updated in response to changes in a "view model" object exposed by the controller. This object adapts the data provided by the underlying model so that it can be easily consumed by the view. The additional level of indirection allows the view and controller to vary independently without the risk of breaking one or the other.

MVC Example

For example, consider a simple custom table view cell implemented using MVC:

The cell class might provide a set of outlets that the table view controller can use to update its state:

class CustomCell: UITableViewCell {
    @IBOutlet var headingLabel: UILabel!
    @IBOutlet var detailLabel: UILabel!

    ...
}

The controller would use the outlets to populate the cell's contents when a new cell is requested. In this example, row data is provided by dictionary instances containing "heading" and "detail" values for each cell:

override func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
    let row = rows[indexPath.row]

    let cell = tableView.dequeueReusableCell(withIdentifier: "customCell") as! CustomCell

    cell.headingLabel.text = row["heading"] as? String
    cell.detailLabel.text = row["detail"] as? String

    return cell
}

However, this design creates a tight coupling between the controller and the custom cell view. Any time the view class changes, the controller must also be updated.

MVVM Example

MVVM solves this problem by decoupling the view from the controller. Rather than exposing its implementation details via outlets, the view registers itself as an observer on the properties of the view model. Using this approach, the view and controller both become dependent on the view model, but neither is dependent on the other. As long as the view model doesn't change, either one can be modified without impact.

For example, the following markup shows a custom table view cell implemented using MarkupKit, an open-source framework for building native iOS and tvOS applications using a simple, HTML-like markup language. The cell contains two labels arranged vertically in a column:

<root accessoryType="disclosureIndicator">
    <LMColumnView>
        <UILabel class="label.heading" text="$content.heading"/>
        <UILabel class="label.detail" text="$content.detail"/>
    </LMColumnView>
</root>

Instead of outlets, the custom cell class exposes a content property representing the view model. The labels' text properties are bound to the properties of this object:

class CustomCell: LMTableViewCell {
    // View model
    dynamic var content: [String: AnyObject]?

    ...    
}

With the bindings established, the controller can be implemented as shown below. It simply dequeues a cell and sets its content property to the dictionary for the corresponding row. Because they are bound to the properties of the view model, the cell's labels are automatically updated to reflect the new values. No direct manipulation of view elements is required:

override func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
    let cell = tableView.dequeueReusableCell(withIdentifier: "customCell") as! CustomCell

    cell.content = rows[indexPath.row]

    return cell
}

Summary

This article introduced the MVVM design pattern and provided an example of how it can be used to simplify the implementation of a custom table view cell. The complete source code for the example can be found here.

For more information, see the MarkupKit README.

MarkupKit 3.0 Released

MarkupKit 3.0 is now available for download. The primary focus of this release was not the addition of new features but improvements to an existing feature.

In earlier versions, custom table and picker view data sources and delegates could call back into the source view to obtain information about static content. However, this approach relied on overrides of UIKit view methods such as numberOfSections, numberOfRowsInSection:, and cellForRowAtIndexPath:, which already have established and documented semantics. The redefined behavior did not always reflect the original intent, which could (and did) lead to bugs.

As of MarkupKit 3.0, a custom data source or delegate can call directly into the respective protocol implementations provided by LMTableView and LMPickerView. The view methods are no longer overridden, allowing them to retain their original behaviors.

However, while this approach provides a much cleaner and more deterministic delegation model, it is not backwards-compatible. All custom data source and delegate implementations must be updated to call the delegate methods instead of the view methods. Specifically, table view controllers that provide custom content should now extend the new LMTableViewController class and delegate to the base method as needed. For example:

override func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
    let n: Int
    if (tableView.name(forSection: section) == "dynamic") {
        n = ...
    } else {
        n = super.tableView(tableView, numberOfRowsInSection: section)
    }

    return n
}

override func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
    let cell: UITableViewCell
    if (tableView.name(forSection: indexPath.section) == "dynamic") {
        cell = ...
    } else {
        cell = super.tableView(tableView, cellForRowAt: indexPath)
    }

    return cell
}

override func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) {
    if (tableView.name(forSection: indexPath.section) == "dynamic") {
        ...
    } else {
        super.tableView(tableView, didSelectRowAt: indexPath)
    }
}

Additionally, controllers that provide custom content for LMPickerView instances should be updated to delegate to the picker view as shown below:

func numberOfComponents(in pickerView: UIPickerView) -> Int {
    return pickerView.numberOfComponents(in: pickerView)
}

func pickerView(_ pickerView: UIPickerView, numberOfRowsInComponent component: Int) -> Int {
    let n: Int
    if (pickerView.name(forComponent: component) == "dynamic") {
        n = ...
    } else {
        n = pickerView.pickerView(pickerView, numberOfRowsInComponent: component)
    }

    return n
}

func pickerView(_ pickerView: UIPickerView, titleForRow row: Int, forComponent component: Int) -> String? {
    let title: String
    if (pickerView.name(forComponent: component) == "dynamic") {
        title = ...
    } else {
        title = pickerView.title(forRow: row, forComponent:component)!
    }

    return title
}

For more information, see the following examples or the project README:

MarkupKit 2.8 Released

MarkupKit 2.8 is now available for download. This release adds support for declarative data binding, facilitating development of MVVM-style applications using MarkupKit.

Using data binding, developers can eliminate a lot of the tedious boilerplate code that is typically required to manage the state of user interface elements explicitly. For example, the following markup binds the text property of a text field to the name property of the document’s owner:

<UITextField text="$name"/>

Any time the value of the owner’s name property changes, the new value will be automatically reflected in the text field’s text property, and vice versa.

For more information, see the following examples or the project README:

  • Custom Cell View – custom table view cell implemented in markup. Cell values are updated via data binding.

  • Form View – demonstrates how to create a simple form using auto layout. Data binding is used to manage the form values.

HTTP-RPC 4.0 Released

HTTP-RPC 4.0 is now available for download. This release adds support for application/x-www-form-urlencoded and application/json request encodings. In addition to submitting request arguments as multipart/form-data, client applications can now POST arguments as URL-encoded key/value pairs and POST or PUT argument values as JSON.

For example, the following Java code would submit a JSON-encoded POST request to the resource located at /example:

serviceProxy.setEncoding(WebServiceProxy.APPLICATION_JSON);

serviceProxy.invoke("POST", "/example", mapOf(
    entry("string", "hello"),
    entry("number", 123),
    entry("flag", true)), (result, exception) -> {
    // ...
});

In Swift, the code might look like this:

serviceProxy.encoding = WSApplicationJSON

serviceProxy.invoke("POST", path: "/example", arguments: [
    "string": "hello",
    "number": 123,
    "flag": true
    ]) { result, error in
    // ...
}

In either case, the body of the request would contain the following:

{
  "string": "hello",
  "number": 123,
  "flag": true
}

For more information, see the project README.

Named Parameters in JDBC Queries

Prepared statements are a common way to execute parameterized queries in JDBC. For example, the following SQL might be used to retrieve a list of all users whose first or last name matches a particular character sequence:

SELECT * FROM user WHERE first_name LIKE ? or last_name LIKE ?

Parameter values are supplied at runtime via indexed setter methods defined by the PreparedStatement class:

statement.setString(1, pattern);
statement.setString(2, pattern);

This works fine for simple queries, but it becomes increasingly difficult to manage as the number of parameters grows. It is also redundant – although this query only requires a single argument, two parameter values must be supplied.

The Java Persistence API (JPA) provides a more convenient alternative using named parameters. For example, the above query might be written as follows in JPQL:

SELECT u FROM User u WHERE u.firstName LIKE :pattern or u.lastName LIKE :pattern

This is more readable and less verbose, as the caller only needs to provide the value of the "pattern" parameter once. It is also more resilient to changes, as the arguments are not dependent on ordinal position. Unfortunately, it requires a JPA-compliant object-relational mapping (ORM) framework such as Hibernate, a dependency that may not be satisfiable in all situations.

The org.jtemplate.sql.Parameters class provided by the JTemplate framework brings named parameter support to JDBC. The parse() method of this class is used to create a Parameters instance from a JPA-like SQL query; for example:

SELECT * FROM user WHERE first_name LIKE :pattern or last_name LIKE :pattern

It takes a string or reader containing the query text as an argument:

Parameters parameters = Parameters.parse(sqlReader);

The getSQL() method of the Parameters class returns the processed query in standard JDBC syntax. This value can be used in a call to Connection#prepareStatement():

PreparedStatement statement = connection.prepareStatement(parameters.getSQL());

Parameter values are specified via the put() method:

parameters.put("pattern", pattern);

The values are applied to the statement via the apply() method:

parameters.apply(statement);

Once applied, the query can be executed:

ResultSet resultSet = statement.executeQuery();

Note that Parameters is not limited to queries; it can also be used for updates.

A complete example using the Parameters class can be found here. It is a simple REST service that allows a caller to search a database of pets by owner name.

See the JTemplate documentation for more information.

JTemplate: Data-Driven Presentation Templates for Java

Templates are documents that describe an output format such as HTML, XML, or CSV. They allow the ultimate representation of a data structure to be specified independently of the data itself, promoting a clear separation of responsibility.

The CTemplate system defines a set of "markers" that are replaced with values supplied by the data structure (which CTemplate calls a "data dictionary") when a template is processed. In JTemplate, the data dictionary is provided by an instance of java.util.Map whose entries represent the values supplied by the dictionary.

For example, the contents of the following map might represent the result of some simple statistical calculations:

{
    "count": 3, 
    "sum": 9.0,
    "average": 3.0
}

A template for transforming this data into HTML is shown below:

<html>
<head>
    <title>Statistics</title>
</head>
<body>
    <p>Count: {{count}}</p>
    <p>Sum: {{sum}}</p>
    <p>Average: {{average}}</p> 
</body>
</html>

At execution time, the "count", "sum", and "average" markers are replaced by their corresponding values from the data dictionary, producing the following markup:

<html>
<head>
    <title>Statistics</title>
</head>
<body>
    <p>Count: 3</p>
    <p>Sum: 9.0</p>
    <p>Average: 3.0</p> 
</body>
</html>

TemplateEncoder Class

JTemplate provides the TemplateEncoder class for merging a template document with a data dictionary. Templates are applied using one of the following TemplateEncoder methods:

public void writeValue(Object value, OutputStream outputStream) { ... }
public void writeValue(Object value, OutputStream outputStream, Locale locale) { ... }
public void writeValue(Object value, Writer writer) { ... }
public void writeValue(Object value, Writer writer, Locale locale) { ... }

The first argument represents the value to write (i.e. the data dictionary), and the second the output destination. The optional third argument represents the locale for which the template will be applied. If unspecified, the default locale is used.

For example, the following code snippet applies a template named map.txt to the contents of a data dictionary whose values are specified by a hash map:

HashMap<String, Object> map = new HashMap<>();

map.put("a", "hello");
map.put("b", 123");
map.put("c", true);

TemplateEncoder encoder = new TemplateEncoder(getClass().getResource("map.txt"), "text/plain");

String result;
try (StringWriter writer = new StringWriter()) {
    encoder.writeValue(map, writer);

    result = writer.toString();
}

System.out.println(result);

If map.txt is defined as follows:

a = {{a}}, b = {{b}}, c = {{c}}

this code would produce the following output:

a = hello, b = 123, c = true

Additional Information

This article introduced the JTemplate framework and provided a brief overview of its key features.

The latest JTemplate release can be downloaded here. For more information, see the project README.

Creating a Simple Android REST Client Using HTTP-RPC

HTTP-RPC is an open-source framework for simplifying development of REST applications. It allows developers to access REST-based web services using a convenient, RPC-like metaphor while preserving fundamental REST principles such as statelessness and uniform resource access.

The project currently includes support for consuming web services in Objective-C/Swift, Java, and JavaScript. It provides a consistent client API that makes it easy to interact with services regardless of target device or operating system.

This article provides a demonstration of how the HTTP-RPC Java client library can be used to invoke services provided by JSONPlaceholder, a "fake online REST API", in Android.

Service API

JSONPlaceholder offers a collection of web services that simulate common REST operations on a variety of resource types such as "albums", "photos", and "users". For example, the following URL retrieves a JSON document containing a list of simulated user records:

https://jsonplaceholder.typicode.com/users

The document is similar to the following:

[
  {
    "id": 1,
    "name": "Leanne Graham",
    "username": "Bret",
    "email": "Sincere@april.biz",
    "address": {
      "street": "Kulas Light",
      "suite": "Apt. 556",
      "city": "Gwenborough",
      "zipcode": "92998-3874",
      "geo": {
        "lat": "-37.3159",
        "lng": "81.1496"
      }
    },
    "phone": "1-770-736-8031 x56442",
    "website": "hildegard.org",
    "company": {
      "name": "Romaguera-Crona",
      "catchPhrase": "Multi-layered client-server neural-net",
      "bs": "harness real-time e-markets"
    }
  },
  ...
]

Additionally, the service provides a collection of simulated discussion posts, which can be retrieved on a per-user basis as follows:

https://jsonplaceholder.typicode.com/posts?userId=1

For example:

[
  {
    "userId": 1,
    "id": 1,
    "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
    "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
  },
  {
    "userId": 1,
    "id": 2,
    "title": "qui est esse",
    "body": "est rerum tempore vitae\nsequi sint nihil reprehenderit dolor beatae ea dolores neque\nfugiat blanditiis voluptate porro vel nihil molestiae ut reiciendis\nqui aperiam non debitis possimus qui neque nisi nulla"
  },
  ...
]

Sample Application

The sample application presents two views. The first one displays a list of users:

The second displays a list of posts by the selected user:

WebServiceProxy Class

The WebServiceProxy class is used to invoke service operations. Internally, it uses an instance of HttpURLConnection to send and receive data. Response data is deserialized automatically into appropriate Java types including String, Number, Boolean, List, and Map.

Service operations are initiated by calling the invoke() method, which takes the following arguments:

  • method – the HTTP method to execute
  • path – the resource path
  • arguments – a map containing the request arguments as key/value pairs
  • resultHandler – an instance of ResultHandler that will be invoked upon completion of the service operation

A convenience method is also provided for executing operations that don't take any arguments.

Arguments are passed to the service either via the query string or in the request body, like an HTML form. List arguments represent multi-value parameters and are handled similarly to <select multiple> tags in HTML.

The result handler is a callback that is invoked upon completion of the request. If successful, the first argument will contain the value returned by the server. Otherwise, the first argument will be null, and the second will contain an exception representing the error that occurred.

For example, the following code might be used to invoke an operation that returns the sum of two numbers, specified by the "a" and "b" arguments. The static mapOf() and entry() methods are provided by the WebServiceProxy class to simplify argument map creation:

// Get sum of "a" and "b"
serviceProxy.invoke("GET", "/math/sum", mapOf(entry("a", 2), entry("b", 4)), (result, exception) -> {
    // result is 6
});

ExampleApplication Class

An instance of WebServiceProxy is created by the example application at startup:

private static WebServiceProxy serviceProxy;

public static WebServiceProxy getServiceProxy() {
    return serviceProxy;
}

@Override
public void onCreate() {
    super.onCreate();

    URL serverURL;
    try {
        serverURL = new URL("https://jsonplaceholder.typicode.com");
    } catch (MalformedURLException exception) {
        throw new RuntimeException(exception);
    }

    serviceProxy = new WebServiceProxy(serverURL, Executors.newSingleThreadExecutor()) {
        private Handler handler = new Handler(Looper.getMainLooper());

        @Override
        protected void dispatchResult(Runnable command) {
            handler.post(command);
        }
    };
}

The user and post activities discussed below use this proxy to invoke their respective service operations.

UserActivity Class

The UserActivity class is responsible for presenting the list of users returned from /users. Internally, it maintains a collection of objects representing the user list. In onResume(), if the list has not already been loaded, it uses the service proxy to retrieve the user list from the server:

public class UserActivity extends AppCompatActivity {
    private ListView userListView;

    private List<Map<String, ?>> userList = null;

    private BaseAdapter userListAdapter = new BaseAdapter() {
        ...
    };

    private static String TAG = UserActivity.class.getName();

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        setContentView(R.layout.activity_main);

        userListView = (ListView)findViewById(R.id.user_list_view);

        userListView.setOnItemClickListener((parent, view, position, id) -> {
            Intent intent = new Intent(UserActivity.this, PostActivity.class);

            intent.putExtra(PostActivity.USER_ID_KEY, id);

            startActivity(intent);
        });
    }

    @Override
    protected void onResume() {
        super.onResume();

        if (userList == null) {
            ExampleApplication.getServiceProxy().invoke("GET", "/users",
                (List<Map<String, ?>> result, Exception exception) -> {
                if (exception == null) {
                    userList = result;

                    userListView.setAdapter(userListAdapter);
                } else {
                    Log.e(TAG, exception.getMessage());
                }
            });
        }
    }
}

A list adapter is used to present the user details for each row:

private BaseAdapter userListAdapter = new BaseAdapter() {
    @Override
    public int getCount() {
        return userList.size();
    }

    @Override
    public Object getItem(int position) {
        return userList.get(position);
    }

    @Override
    public long getItemId(int position) {
        return ((Number)userList.get(position).get("id")).longValue();
    }

    @Override
    public View getView(int position, View convertView, ViewGroup parent) {
        if (convertView == null) {
            convertView = getLayoutInflater().inflate(R.layout.item_user, null);
        }

        Map<String, ?> note = userList.get(position);

        String name = (String)note.get("name");

        TextView nameTextView = (TextView)convertView.findViewById(R.id.name_text_view);
        nameTextView.setText(name);

        String email = (String)note.get("email");

        TextView emailTextView = (TextView)convertView.findViewById(R.id.email_text_view);
        emailTextView.setText(email);

        return convertView;
    }
};

PostActivity Class

When a user is selected, an instance of PostActivity is presented. This class is responsible for presenting the list of user posts returned from /posts. Like UserActivity, it maintains a collection of objects representing the server response, and populates the list in onResume():

public class PostActivity extends AppCompatActivity {
    private ListView postListView;

    private List<Map<String, ?>> postList = null;

    private BaseAdapter postListAdapter = new BaseAdapter() {
        ...
    };

    public static final String USER_ID_KEY = "userID";

    private static String TAG = PostActivity.class.getName();

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        setContentView(R.layout.activity_post);

        postListView = (ListView)findViewById(R.id.post_list_view);
    }

    @Override
    protected void onResume() {
        super.onResume();

        if (postList == null) {
            long userID = getIntent().getLongExtra(USER_ID_KEY, 0);

            ExampleApplication.getServiceProxy().invoke("GET", "/posts", mapOf(entry("userId", userID)),
                (List<Map<String, ?>> result, Exception exception) -> {
                if (exception == null) {
                    postList = result;

                    postListView.setAdapter(postListAdapter);
                } else {
                    Log.e(TAG, exception.getMessage());
                }
            });
        }
    }
}

Again, a list adapter is used to present the details for each row:

private BaseAdapter postListAdapter = new BaseAdapter() {
    @Override
    public int getCount() {
        return postList.size();
    }

    @Override
    public Object getItem(int position) {
        return postList.get(position);
    }

    @Override
    public long getItemId(int position) {
        return ((Number)postList.get(position).get("id")).longValue();
    }

    @Override
    public View getView(int position, View convertView, ViewGroup parent) {
        if (convertView == null) {
            convertView = getLayoutInflater().inflate(R.layout.item_post, null);
        }

        Map<String, ?> note = postList.get(position);

        String title = (String)note.get("title");

        TextView titleTextView = (TextView)convertView.findViewById(R.id.title_text_view);
        titleTextView.setText(title);

        String body = (String)note.get("body");

        TextView bodyTextView = (TextView)convertView.findViewById(R.id.body_text_view);
        bodyTextView.setText(body);

        return convertView;
    }
};

More Information

This article provided a demonstration of how the HTTP-RPC Java client library can be used to build a simple Android REST client application. The complete source code for the sample application can be found here.

The latest version of HTTP-RPC can be downloaded here. For more information, see the project README.