Chronos library: make writing long operations easier

Hi, Habr! I want to tell you about the Chronos for Android library (API level> = 9), the purpose of which is to facilitate writing long operations, such as network requests, or database calls.

What problem we solve?

It's no secret that for Android, the task of performing asynchronous operations has always been one of the most frequently encountered. Indeed, very few applications work exclusively offline, and where you can do without network interaction. And absolutely tiny part of them goes without reference to the device’s permanent memory, be it a database, Preferences or a regular file. However, throughout the history of the development of the system, we have never been offered a single, fairly convenient solution out of the box.



What does Chronos offer?



Chronos does all the work for you in performing the task in a parallel thread and delivering the result or execution error to the main thread. Roughly speaking, this library provides a container for any kind of long operations.
There is a full-fledged wiki in the project, part of the code from there will be used in the article, but for a more complete guide, please contact github.com/RedMadRobot/Chronos/wiki .

Example

Let's solve a typical problem using Chronos: in the Activity, you need to request some object from a certain repository, access to which is long enough not to make a request in the UI stream. First, we write the code, and then we analyze what we did.

1. The first thing you need to connect Chronos to the project. To do this, simply write the dependency in the gradle:

 compile 'com.redmadrobot:chronos:1.0.5' 

2. Now we will describe Activity. The base class ChronosActivity is one of the library components, however you can easily write its analogue, examples of which are in the documentation. Also Chronos can be used in fragments, the code will not differ.

 class MyActivity extends ChronosActivity { @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); Button startButton = (Button) findViewById(R.id.button_start); startButton.setOnClickListener(new View.OnClickListener() { @Override public void onClick(final View v) { runOperation(new MyOperation()); } }); } public void onOperationFinished(final MyOperation.Result result) { if (result.isSuccessful()) { showData(result.getOutput()); } else { showDataLoadError(result.getError()); } } private void showData(BusinessObject data){ //... } private void showDataLoadError(Exception exception){ //... } } 

3. And finally, we describe the business logic of receiving data in the class MyOperation :

 class MyOperation extends ChronosOperation<BusinessObject> { @Nullable @Override public BusinessObject run() { final BusinessObject result ; // here you should write what you do to get the BusinessObject return result; } @NonNull @Override public Class<? extends ChronosOperationResult<BusinessObject>> getResultClass(){ return Result.class; } public final static class Result extends ChronosOperationResult<BusinessObject> { } } 

That's all. Let's see in detail what happens in this code. Start over.

Setting UI Class

 class MyActivity extends ChronosActivity { 

To work with Chronos, the Acvitity base class or a fragment must either inherit from those offered in the library, or contain specific code in the life-cycle methods, examples can be seen in the documentation .

Running operation

 runOperation(new MyOperation()); 

This is where the base method of the ChronosActivity class is called, to which the newly created activity is passed. Immediately after calling this method, Chronos will take the operation into the queue and begin its execution in a parallel thread.

Processing the result of the operation

 public void onOperationFinished(final MyOperation.Result result) { if (result.isSuccessful()) { showData(result.getOutput()); } else { showDataLoadError(result.getError()); } } 

This method will be called after the operation is completed, or an exception is thrown during execution. Such handler methods must have a signature public void onOperationFinished (ResultType) . The important point: the method will be called only between the onResume () and onPause () calls, that is, in it you can easily change the UI, without fear that it has already become invalid by that moment. Moreover, if the Activity was recreated due to rotation, going into the background, or other reasons, Chronos will return the result anyway (the only exception is that the system has run out of memory, in this case, to prevent OutOfMemory, Chronos can erase the old results data).

Setting the class of operation

 class MyOperation extends ChronosOperation<BusinessObject> { 

The ChronosOperation class encapsulates the business logic for retrieving an object of a particular type, in this case BusinessObject . All user operations must be inherited from ChronosOperation .

Business logic

  @Nullable @Override public BusinessObject run() { final BusinessObject result ; // here you should write what you do to get the BusinessObject return result; } 

This abstract method of the ChronosOperation class is responsible, in fact, for the business logic of receiving an object. It runs in a parallel thread, so you can do as long as you want in it, it will not cause lags in the application interface. Also, any exceptions thrown in it will be carefully passed to the caller without causing the application to crash.

Result Naming

  @NonNull @Override public Class<? extends ChronosOperationResult<BusinessObject>> getResultClass(){ return Result.class; } public final static class Result extends ChronosOperationResult<BusinessObject> { } 

The following method and class are designed to enable the Activity code to write a result handler for each specific operation, specifying the class as the parameter type of the onOperationFinished method. You can use the same result class for different operations if you want their result to be processed in the same way.

I summarize: we will collect the minimum set of code sections needed for working with Chronos.

• Class of operation
• Operation invocation code in a UI object
• Result handling code in a UI object

What else is there?

• In order not to lose the already running query when the screen is rotated, Chronos provides the ability to “name” operation launches .
• It is possible to cancel operations .
• If you want the result of the operation to receive not only the object that caused it, but also everything subscribed to it, you can do Broadcast launches .
• In addition, if desired, operations can be performed synchronously using the Chronos class.

So why and why can Chronos be used?

• Chronos assumes the transfer of data between threads, leaving you to worry only about business logic.
• Chronos takes into account all the nuances of the Life cycle of the Activity and fragments, delivering the result only when they are ready to process it, saving the data until then.
• Chronos does not leak memory. You no longer risk catching crashes because too many Activity objects flowed away.
• Chronos is covered by unit tests.
• And finally, Chronos is an open-source project. You can always take the code and rewrite it to fit your needs. Thanks to the tests, it will be easy for you to validate code changes.

Link to the project in GitHub . There you will find a complete library guide, usage examples and, of course, source code.

See also:
We put controllers on a diet: Android
Architectural design of mobile applications: part 1
Architectural design of mobile applications: part 2