Friday, March 14, 2014

Introducing the WorxForUs Open Source Database & Network Helper for Android

WorxForUs Android Framework (Database and Network helper tools)

This article is an introductory guide to the Android helper library by WorxForUs.  The Android SDK has a lot of built in functionality, but there are certain things that it does not take care of for you.  The API guides only get you so far.  This framework is an attempt to pick up where the Android Samples leave off and address some of the trickier issues.  Hopefully you will find features in this library to help your code become more robust.

Major Features of the WorxForUs Android Library:

  • Database management (How To)
    • Serialized access framework for writing thread safe (multi-threaded) applications
    • Allows upgrade on a per table level instead of per database
    • Supports methods to keep track of data synchronization to a remote server

  • Network Tools (How To)
    • Allows easy detection and handling of network errors
    • Built in support for cookies
    • Allows easy use of network retry mode (ie. will attempt 5 times before returning an error)
    • Deals with authenticated and non-authenticated network requests 

  • Obscuring Shared Preferences Data (How To) - com.worxforus.ObscuredSharedPreferences
    • Shared data is normally stored in plaintext.  This tool easily encrypts your SharedPreferences data.
  • Object Pools - com.worxforus.Pool 
    • Put objects into a pool to keep memory usage low and minimize object creation



There are two ways to use the library.
1. Clone the source code at the github WorxForUs Library and import into your IDE.  Link the WorxForUs Library project to your project.
2. Download the jar file from github and include in your project/lib files.

If you are using the Network Tools, you may want to get the latest Apache HttpClient package from their download page here.  You will want the httpcore-4.x.x.jar, httpclient-4.x.x.jar, httpclient-cache-4.x.x.jar, and httpmime-4.x.x.jar.  Import these into your referenced jar library.  The latest binary release as of this writing is the 4.3.3 package.

Why was this Framework created? 

Aside from the typical utilities one generally collects or creates when writing software for a long time, I had a few specific needs for robust database access and network handling.

Database Management

A typical example of using a SQLite database in Android shows that you extend the SQLiteOpenHelper.  This is good, but what if you have several tables each with their own version?  Also, the sample projects show doing a dbHelper.getWritableDatabase(), but do not say anything about how to handle multiple threads contending for the same resource.  This may work fine on single core CPU devices, but suddenly your app may crash on a multi-Core Nexus 7 because your database access is not serialized. This package use a Singleton to provide access to the SQLite database and Semaphores to provide the locking which by default serializes the database access and prevents many common database exceptions from occurring.

Network Tools

I needed to handle cookies and detect when network connections were failing and identify what type of failure occurred.  Was the problem a server failure or a bad connection on the user device?  In a mobile network errors are the norm and it is important to handle them correctly.  I also wanted a way to easily retry a connection several times until it was successful.  This package is based on the Apache HttpClient because it easily supported the things I needed such as cookies and error detection.  Future versions are planned to use the Velocity framework.

*Additional Source of code, including but not limited to:
The Android Open Source Project - for the Base64Support code.
Obscuring Shared Preferences - much of the code for this came from help by emmby at