I am personally a fan of clean designs and partitions.  Layering an architecture, e.g., UI, Business Logic, and Data Access (or, in some cases, Presentation, UI, Business Logic, Data Access, and Data Storage and Management) is just good practice and helps build extensibility and maintainability into your systems.  Understanding proven principles, such as the Open-Closed Principle (see my post) can reduce development time and ultimately increase the lifespan of a software system.  Also, using Repositories, POCO’s (& POJO’s, for Java) , and DTO’s comes naturally to provide clean separation of business logic and persistence.

Note:  Since the topic of POCO’s and POJO’s has become confusing in the software development community, I will instead use business object.  By business object I mean an object that is responsible for business logic only.  It is generally a “plain” object, encapsulates data via a DTO, and is persistence ignorant.  That is, it knows nothing of persistence.  We delegate persistence to the repository.

In this post, I discuss how to create a lightweight Business Object Framework that can drastically decrease your development time, and provide a solid, easy-to-use, and dependable framework that you and your team can use in your Android/Java applications.  I created this while developing my Android applications and believe others may find it useful.  If you have used business object frameworks before, you will find this simple and succinct, as it is lightweight.  By lightweight, I mean that I will not delve into deeper framework features such as undo and redo.  Although you can easily extend the framework to satisfy your needs.

A business object framework helps applications by providing the following benefits:

• clean separation of business logic and persistence
• a well-known place to implement business rules and work flow activities
• an easy-to-use interface for the UI to communicate with the business logic layer
• complete abstraction of the data access layer from the user interface
• a convenient way to support unit testing through IoC, inversion of control, using the repository pattern (more about this later)

Our lightweight business object framework will use the common design patterns,

• Repositories,
• Business objects, and
• DTO’s (data transfer objects).

Some of you may realize that these patterns are used in DDD (domain driven designs).  This is true.  Understand that this post is not about DDD, but rather creating a simple, easy-to-use, and clean framework for implementing your business objects.  I have also created several business object frameworks in the past and find them to be extremely useful and flexible for systems that have lots of business rules and/or work flow activities.  The clean separation of responsibilities is crucial in larger projects where business requirements change and/or are frequently added, and the same with team members.

Now let’s give a simple definition and example for each pattern.

Repository

Provides data persistence.

Example:

public class EmployeeRepository {
    // TODO: establish connection info
    protected String connectionInfo = "abc...";

    public static Employee create() {
        return new Employee();
    }

    public static Employee insert(Employee employee) throws InvalidBusinessObjectException {
        if (employee.isValid()) {
            ResourceHelper.insert(employee.DTO, this.connectionInfo);
        }
    }

    public static Employee update(Employee employee) throws InvalidBusinessObjectException {
        if (employee.isValid()) {
            ResourceHelper.update(employee.DTO, this.connectionInfo);
        }
    }

    public static Employee load(long id) throws JSONException {
        String serializedObjectString = ResourceHelper.load(id, this.connectionInfo);

        return new Employee(serializedObjectString);
    }

    public static ArrayList<Employee> loadMany(String condition) throws JSONException {
        String serializedObjectString = ResourceHelper.loadMany(condition, this.connectionInfo);
        JSONArray jsonObjs = new JSONArray(serializedObjectString);
        ArrayList<Employee> employees = new ArrayList<Employee>();

        for (int i=0; i<jsonObjs.length(); i++) {
            JSONObject jsonObj = jsonObjs.getJSONObject(i);
            employees.add(new Employee(jsonObj));
        }

        return employees;
    }

    public static void delete(Employee employee) {
        ResourceHelper.delete(employee.DTO, this.connectionInfo);
    }
}

Business Object

Provides the object containing the business logic.  And therefore is the business object.

Example:

public class Employee extends BusinessObject {
    public EmployeeDTO DTO;
    public int EntityState_Local = EntityState.UNCHANGED;

    public Employee() {
        this.DTO = new EmployeeDTO();
        this.EntityState_Local = EntityState.ADDED;
    }

    public Employee(EmployeeDTO DTO) {
        this.DTO = DTO;
        this.EntityState_Local = EntityState.UNCHANGED;
    }

    public Employee(EmployeeDTO DTO, String entityState) {
        this.DTO = DTO;
        this.EntityState_Local = entityState;
    }

    public Employee(String serializedObjectString) throws JSONException {
        this.DTO = deserializeObject(new JSONObject(serializedObjectString));
    }

    public String serialize() {
        return serialize(this.DTO);
    }

    public boolean isValid() {
        boolean result = false;

        if (this.DTO.FirstName.length() > 0) {
            // self correcting business rule
            this.DTO.FirstName = capitalizeName(this.DTO.FirstName);
        }

        if (this.DTO.LastName.length() > 0{
            // self correcting business rule
            this.DTO.LastName = capitalizeName(this.DTO.LastName);
        }

        // TODO: Complete

        return result;
    }
}

DTO

Provides the data transfer container, or object.  The DTO is owned by the POJO (business object) and persisted by the repository.

Example:

public class EmployeeDTO {
    public long Id = -1;
    public long DeptId = -1;
    public long SalaryGradeId = -1;
    public String FirstName;
    public String LastName;
    public String Email;
    public String Phone;
    public String Title;
    public boolean TakesLongLunches = false;
}

Here is a quick example demonstrating all of the above in action together:

Employee newbie = EmployeeRepository.create();

newbie.DTO.FirstName = "Fred";
newbie.DTO.LastName = "Flintstone";
newbie.DTO.DeptId = Depts.DIGGER;
newbie.DTO.SalaryGradeId = SalariesGrades.EIGHT;
newbie.DTO.Title = "Chief Digger";
newbie.DTO.Email = "fflintstone@bedrock.com";
newbie.DTO.Phone = "777-123-4567";
newbie.DTO.TakesLongLunches = true;

EmployeeRepository.insert(newbie);

Keep in mind that this is not the actual lightweight business object framework. I’m showing this to help define the core patterns involved in building the business objects that the framework will support.

One interesting point to make is that we will NOT persist our data to a database on our mobile device.  Instead, the repository (part of the data access layer) will accomplish CRUD (i.e., persistence) server-side, by communicating with RESTful services.  We will demonstrate this later.

Designing the Framework

As indicated earlier, persistence happens server-side for our demonstration.  Therefore the data, that is DTO’s, must be transferred to and from services.  This framework makes use of serialization, and I will specifically use JSON serialization.  Of course, I could have optionally used XML serialization just as easily.  For more information, please see my serialization/deserialization post found here.

Keep in mind that, client-side, all of this happens within the repository, as it is the primary component within the data access layer.  As a user of a business object, this fact is abstracted away from you, and persistence could have been accomplished via database, XML file, or other on the client, for example.

Let’s create a base business object class.  This will serve as our “base” for the business objects.  Note:  We will expand this class as we enhance the framework.

public abstract class BusinessObject<T> implements IEntityFactory<T>, Comparable<T> {
    protected IEntity DTO = null;
    protected boolean isNew = true;
    protected boolean isDirty = false;
    protected String insertUrl = null;
    protected String updateUrl = null;
    protected String loadUrl = null;
    protected String deleteUrl = null;

    public BusinessObject() {
    }

    public BusinessObject(JSONObject obj) throws JSONException {
        super();
        deserializeFromObj(obj);
    }

    public BusinessObject(String serializedObj) throws JSONException {
        super();
        deserialize(serializedObj);
    }

    public String serialize() throws JSONException {
        return serializeToObj().toString();
    }

    public T deserialize(String serializedObj) throws JSONException {
        JSONObject obj = new JSONObject(serializedObj);
        return deserializeFromObj(obj);
    }

    abstract JSONObject serializeToObj() throws JSONException;

    abstract T deserializeFromObj(JSONObject obj) throws JSONException;

    protected ArrayList<T> loadMany() throws JSONException {
        ArrayList<T> items = new ArrayList<T>();
        String result = "";

        result = ResourceHelper.loadManySerialized(this.loadUrl);

        if (result != null && result.length() > 0) {
            JSONArray jsonObjs = new JSONArray(result);
            for (int i=0; i<jsonObjs.length(); i++) {
                JSONObject jsonObj = jsonObjs.getJSONObject(i);
                T entity = (T)this.create(jsonObj);
                items.add(entity);
            }
        }

        return items;
    }

    public T save() throws ApplicationException {
        // intentionally left incomplete
        T entity = null;

        return entity;
    }
}

And let’s show a concrete business object deriving from our BusinessObject class.

public class Employee extends BusinessObject<Employee> {
    public EmployeeDTO DTO = new EmployeeDTO();

    public Employee() {
        super();
    }

    public Employee(JSONObject obj) throws JSONException {
        super(obj);
    }

    public Employee(String serializedObj) throws JSONException {
        super(serializedObj);
    }

    public Employee deserializeFromObj(JSONObject obj) throws JSONException {
        this.DTO = new EmployeeDTO();

        this.DTO.Id = obj.getLong("Id");
        this.DTO.DeptId = obj.getLong("DeptId");
        this.DTO.SalaryGradeId = obj.getLong("SalaryGradeId");
        this.DTO.FirstName = obj.getString("FirstName");
        this.DTO.LastName = obj.getString("LastName");
        this.DTO.Email = obj.getString("Email");
        this.DTO.Phone = obj.getString("Phone");
        this.DTO.Title = obj.getString("Title");
        this.DTO.TakesLongLunches = Boolean.parseBoolean(obj.getString("TakesLongLunches"));

        return this;
    }

    public JSONObject serializeToObj() throws JSONException {
        JSONObject serializedObj = new JSONObject();
        serializedObj.put("Id", this.DTO.Id);
        serializedObj.put("DeptId", this.DTO.DeptId);
        serializedObj.put("SalaryGradeId", this.DTO.SalaryGradeId);
        serializedObj.put("FirstName", this.DTO.FirstName);
        serializedObj.put("LastName", this.DTO.LastName);
        serializedObj.put("Email", this.DTO.Email);
        serializedObj.put("Phone", this.DTO.Phone);
        serializedObj.put("Title", this.DTO.Title);
        serializedObj.put("TakesLongLunches", this.DTO.TakesLongLunches);

        return serializedObj;
    }

    public static ArrayList<Employee> deserializeArray(String serializedArray) throws JSONException {
        JSONArray jsonObjs = new JSONArray(serializedArray);
        ArrayList<Employee> employees = new ArrayList<Employee>();
        for (int i=0; i<jsonObjs.length(); i++) {
            JSONObject employee = jsonObjs.getJSONObject(i);
            employees.add(new Employee(employee));
        }

        return employees;
    }

    @Override
    public Employee create() {
        // TODO Auto-generated method stub
        return new Employee();
    }

    @Override
    public Employee create(JSONObject jsonObj) throws JSONException {
        // TODO Auto-generated method stub
        return new Employee(jsonObj);
    }

    @Override
    public Employee save() throws ApplicationException {
        // TODO Auto-generated method stub
        return null;
    }

    @Override
    public int compareTo(Employee another) {
        // TODO Auto-generated method stub
        return new Long(this.DTO.Id).compareTo(new Long(another.DTO.Id));
    }
}

Example

Now let’s give a quick example demonstrating deserializing an array using our new Employee business object.

First, we will make use of the following ResourceHelper class that allows us to make a call to the server to obtain an array of serialized employee objects:

package com.demo.helpers;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;

import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.ClientProtocolException;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.DefaultHttpClient;

public class ResourceHelper {
    public static String loadManySerialized(String url)
    {
        HttpClient httpclient = new DefaultHttpClient();

        // Prepare a request object
        HttpGet httpget = new HttpGet(url);

        // Execute the request
        HttpResponse response;

        String result = null;
        try {
            response = httpclient.execute(httpget);

            // Get hold of the response entity
            HttpEntity entity = response.getEntity();
            // If the response does not enclose an entity, there is no need
            // to worry about connection release

            if (entity != null) {
                // A Simple Response Read
                InputStream instream = entity.getContent();
                result = convertStreamToString(instream);

                // Closing the input stream will trigger connection release
                instream.close();
            }
        } catch (ClientProtocolException e) {
            // TODO Auto-generated catch block
            e.printStackTrace();
        } catch (IOException e) {
            // TODO Auto-generated catch block
            e.printStackTrace();
        }

        return result;
    }

    private static String convertStreamToString(InputStream is) {
        /*
        * To convert the InputStream to String we use the BufferedReader.readLine()
        * method. We iterate until the BufferedReader return null which means
        * there's no more data to read. Each line will appended to a StringBuilder
        * and returned as String.
        */
        BufferedReader reader = new BufferedReader(new InputStreamReader(is), 8192);
        StringBuilder sb = new StringBuilder();

        String line = null;
        try {
            while ((line = reader.readLine()) != null) {
                sb.append(line + "\n");
            }
        } catch (IOException e) {
            e.printStackTrace();
        } finally {
            try {
                is.close();
            } catch (IOException e) {
                e.printStackTrace();
            }
        }

        return sb.toString();
    }
}

To retrieve a list of employee objects, we’ll call Employee.deserializeArray(…), passing it the serialized String obtained by calling ResourceHelper.loadManySerialized(…).

ArrayList<Employee> employees = Employee.deserializeArray(ResourceHelper.loadManySerialized("http://demos.brianbuikema.com/apps/soa_services/employees?format=JSON"));

Cool.  We have now successfully demonstrated our Employee business object.

Thanks and see you next time!

package com.demo.helpers;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;

import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.ClientProtocolException;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.DefaultHttpClient;

public class ResourceHelper {
    public static String loadManySerialized(String url)
    {
        HttpClient httpclient = new DefaultHttpClient();

        // Prepare a request object
        HttpGet httpget = new HttpGet(url);

        // Execute the request
        HttpResponse response;

        String result = null;
        try {
            response = httpclient.execute(httpget);

            // Get hold of the response entity
            HttpEntity entity = response.getEntity();
            // If the response does not enclose an entity, there is no need
            // to worry about connection release

            if (entity != null) {
                // A Simple Response Read
                InputStream instream = entity.getContent();
                result = convertStreamToString(instream);

                // Closing the input stream will trigger connection release
                instream.close();
            }
        } catch (ClientProtocolException e) {
            // TODO Auto-generated catch block
            e.printStackTrace();
        } catch (IOException e) {
            // TODO Auto-generated catch block
            e.printStackTrace();
        }

        return result;
    }

    private static String convertStreamToString(InputStream is) {
        /*
        * To convert the InputStream to String we use the BufferedReader.readLine()
        * method. We iterate until the BufferedReader return null which means
        * there's no more data to read. Each line will appended to a StringBuilder
        * and returned as String.
        */
        BufferedReader reader = new BufferedReader(new InputStreamReader(is), 8192);
        StringBuilder sb = new StringBuilder();

        String line = null;
        try {
            while ((line = reader.readLine()) != null) {
                sb.append(line + "\n");
            }
        } catch (IOException e) {
            e.printStackTrace();
        } finally {
            try {
                is.close();
            } catch (IOException e) {
                e.printStackTrace();
            }
        }

        return sb.toString();
    }
}