Gradle, dependency and Local Repository

If you are an android developer, working on non collaborative projects on your own computer, you have definitely faced the situation where you need to use some piece of software among many projects (mainly utils).

This situation is nothing else than a dependency requirement. So what are our choices to make it smooth ?

step 1 : create an Android library module

I am sure many of you are making copy/paste of piece of sofware from one project to another. Who didn’t, right ?
First of all, get rid of this archaic habit and simply put this reusable software into an android Library module . That’s easy and cheap. Moreover, that gives you the power to make your software evolve peacefully, with adding quality and consistency through time.

step 2 (optional) : make it public and deploy it on maven central

This module is hosted on your computer. You can make the choice to publish your library into github and make the source available to the world. Then, you can simply deploy your artifact to maven central and easily fetch it into any of your project (and let others use it too). To do so, please read my previous article where I detailed the entire process of publishing and deploying an open source project.

But you probably won’t go that far. Your need is to keep your software private but benefit from the gradle dependency mechanism.

step 2 : keep it private

You will probably keep this peace of software private for any valid reason (high end technology you haven’t patented yet oO … or … software not high quality enough …or… pure selfishness…) Whatever the reason is, it’s ok, it’s your decision 🙂
However, even if it is private, do not forget to version your source code into private repository.

step 3 : publish on local directory

The idea here is to publish your artifact into a local directory of your file system. Bear in mind that this directory (used as repository) will host many versions of the same library, and even multiple private libraries, so don’t forget to backup it (using dropbox or google drive for instance) in case you switch computer.

Based on the Gradle Repository Handler documentation, gradle supports many repositories where your project can fetch artifacts. Among them, you can find jCenter(), mavenCentral(), mavenLocal() or any maven() custom repository.

Why don’t we use directly mavenLocal() as our local repository ?
We could of course install our artifact into mavenLocal (/home/.m2/repository) but this repository has another goal. It’s mainly used for caching artifacts to save network requests. Moreover, we loose our sync-ing requirement. Indeed, there is no need to backup the the .m2 folder, it’s just non sense.

So we need to choose a local folder of our choice (for instance /Users/turhan/LocalRepository/).

step 3.1 : configure your library’s build.gradle

We have to configure our library’s build.gradle to specify the directory where to deploy our artifact

We have here created the uploadArchives task by defining the repository url where the artifact will be deployed by maven(here it is a local file:// path).
As you can see, we have to include the maven plugin  (highlighted on the first line) so the mavenDeployer can work.
Finally, don’t forget to specify a group, an archiveBaseName as well as a version. And for each release, do not forget to increment the version  (better put it into a variable inside grade).

step 3.2 : upload your artifact

So now, to deploy our artifact into our local directory called LocalRepository, we simply call the task

step 4 : fetch your artifact into your project

step 4.1 : configure the repository url

On any other other project of yours, open the top build.gradle. We will specify there the path to our local repository

step 4.2 : import the dependency

Now, we can easily define our library as a dependency, such any other dependency. Gradle will look into each repositories we have defined (mavenCentral() and or custom local repository)

Conclusion

We could have installed a Nexus repository locally, but to be honest with you, this is overkill (credentials + web server & so) for our need (non collaborative projects). We need something that could be setup quickly, something that could be backuped easily.
The setup detailed here is not complicated at all and gives you the opportunity to manage your private dependencies easily.
I hope you could save some time with that and make your development process more smooth.

Enjoy 🙂

 

AlarmManager Unit Test using Robolectric 3.0

Alarm Manager feature

AlarmManager is an Android component available since API level 1.

I wanted to use this component in the following scenario :
– automatic and repeated triggers that ignite an operation n times a day
– any new scheduling should cancel previous ones (to avoid unconsistent multiple calls)
– when the device restarts (boot completed), the scheduling should be activated without running the app hosting the AlarmManager.
– the BootComplete operation is not enabled by default, but programatically.

AlarmManager Unit Tests

# Setting alarm

So I created an AlarmController that simply set repeated alarm and activate/desactivate scheduling on bootcomplete

The setAlarm() function simply triggers a broadcast at the given interval (here one hour).

To test this with Robolectric 3.0, we have to use a shadowAlarmManager that will store the parameters of the scheduled Alarm. We can thus simply test the interval set, the trigger time as well as the alarm type (here elapsed_realtime) of the ScheduledAlarm.

# Ensuring one Alarm at a time

Let’s say we call setAlarm() api multiple times (if called for instance during a lifecycle callback). Then, we have to ensure that only one alarm dealing with the same operation is set, avoiding thus any unconsistent and unnecessary mutliple wakes up.

# Checking Operation triggered by the Alarm

To test which PendingIntent operation is triggered by the Alarm, we have to use now a ShadowPendingIntent which will give, once again, extra information, especially regarding the component.

# Checking Operation triggered by the BroadcastReceiver

Our broadcast receiver has 2 goals : setting the alarm if BootCompleted and triggering a service (hosting the operation).

To Unit Test that the service is properly started when broadcast is received, we have, once again, to shadow application so we can access to startedServices.

# Checking BroadcastReceiver will init Alarm on BootCompleted

To Unit Test that the Alarm is properly set onBootComplete, we simply verify, using mockito, the colloboration between the System Under Test (namely the BroadcastReceiver) and the AlarmController

#Activating / Desactivating Broadcast receiver on Demand

As you know, a Broadcast Receiver is a main component of Android Architecture and any receivers should be declared in the Android Manifest. However, let’s suppose we want to activate our broadcast receiver only in a particular scenario  (after an in-app purchase for instance  or only during specific lifecycle callbacks), then how to proceed ?

To do so, we have to declare the Broadcast receiver with the enable=false flag. This gives us the control on programatically enabling/disabling the receiver. Then, we can use the Android PackageManager and set the state of our component (namely the receiver) on demand, as follow :

To Unit Test this with Robolectric 3.0+, we rely on the RobolectricPackageManager accessible through the RuntimeEnvironment object. This will give access to any component state, especially the one we are interested in (our receiver).

 

Android Unit Test : source code on Github

I have create a new Open Source Project called Android Unit Test including this Alarm Manager testing. This project will gather interesting Android Unit Test scenario using Robolectric 3.0, Juni4.+, Mockito 1.9.+

Writing quality Unit Tests on Android requires sometimes quite struggling. This is why this open source project will help you save some time hopefully.

Lean Startup – Go Startup Smartly

Sharing knowledge is part of my life vision. I have learned from others and learned from experimenting myself too, so passing this to others is the ultimate reward.

Few weeks back, I have been kindly asked by the organizers if I could join the AndroidDeveloperDays 2015 as a speaker. I did the previous edition (speaking about ReactiveProgramming) and was more than happy to participate to this new one. But instead of talking about technical stuff on Android (which is my passion), I wanted to share this time best practices on Startup-ing. The reason why I choosed this topic is the tremendous amount of time that human being is wasting on building « products that nobody wants ». We often forget that our most precious assest in life is our time and our health. Once spent, nobody will give it back to you. So creating a product in condition of extreme uncertainty shouldn’t be done by working blindly hard, but by working smartly. This is all the purpose of this presentation.

Unfortunately, there was a technical issue while recording some talks during AndroidDeveloperDays, and my talk was among the missed one :'( So I can only share with you the slides.
Maybe I’ll give this talk once again one day so I’ll share the video too.

Android Developer Days 2015

Reactive Directory Chooser – An Open Source journey

I am developing applications for years now, but only in professional area, where everything you produced is proprietary, and does not belong to you, but to the client who paids or employs you…
So I have decided to publish a simple Android library, just to experiment the journey of open source. But you’ll see, this journey is not as marvelous as it looks like, but definitely worth it, especially for the learning process.

The library

Most of the android applications save data to the external storage of the device. The storage location is often empirically defined by the application itself. It would be better to give back the control to the user; the latter should be able to choose the folder in which he wants to save his data. To do so, the user should be able to navigate through the external storage, create custom folders if he needs to and select the appropriate one for his needs.
The library I have created, called Reactive Directory Chooser, answers these needs; It is available on GitHub and Maven Central.
There is, of course, no need to reinvent the wheel, so obviously I checked first. Others libraries exist out there but were not exactly matching my requirements.

The requirements

The required functionalities are basic :
– listing folder’s content (content should be folders only)
– navigating from one folder to another
– creating folder
– notifying client of the selected folder.

Based on the current Android Dashboard (march 2015), it worths supporting back from android API 10 (gingerbread, almost 6% of the market) to the latest known API 22.
The others available libraries on the market are only supporting starting from honeycomb (API 11), which is sadly a waste.

Technical side

– RxJava (Observers, Observable, Operation)

The operations of listing a folder and creating a folder are quite simple. But obviously, these operations have to be processed asynchronously. More over, as we wanted to only display folders (and not regular files), there is here a process of filtering.
Technically speaking, Reactive Programming is a proper answer to these operations : indeed, we can easily trigger operation in an IO thread for instance and also filter the stream to keep only folder type files.
I am a convinced advocate of Reactive Programming (check my conference given in 2014 during AndroidDeveloperDays). Many frameworks exist out there, but the only one I have tested so far is RxJava.
How I proceed ? I isolate the Observable, which produces items asynchronously , from the Observer, that consumes the items in the Android main Thread. These object are encapsulated into Operation objects that trigger the computation on demand, with canceling the previous one if still processing.

– Clean code

As a developer, I try to continuously improve myself as much as possible, and believe me, producing clean code is not easy but so challenging, a life long journey.
The first question I ask myself is « what is the responsibility of this object ? », trying to keep in mind the Single Responsibility Principle. This really is a starting point that will keep your code from being insignicantly polluted. When I review code, from other open source projects for instance, I am really upset/sad/annoyed to see classes that are very long, mixing all kind of non sense operations… This should end! As open source developer, we have a huge responsibility. Our duty is to try to donate to the community good examples of codes, otherwise how will we improve ? Remember, improve every single day if you could. I am not saying the code I produce is clean nor perfect, I’m just saying that I try to make the effort in that way.

Another point that I try to give importance is to keep modules of your software independent from each other as much as possible; in other word, uncoupling objects. For this part, using a Bus, such as EventBus, is a proper answer from my point of view. It lets independent objects producing event and others consuming events.

– Coding

I first started to develop the backend side, then the UI and finally wiring up all.
I like this approach in the fact that they are independent, and force you to properly split your modules. This also gives you the freedom to adapt or change your UI more easily. Also, most of the time, when you deal with UI, you have a great chance to apply the MVC or MVP pattern.
Keep in mind that Fragment or Activity are not exactly controller, their main responsability is to deal with lifecycle callbacks as well as saving/restoring ui states (if not delegated to the low level UI widget).

– Unit Testing

I shouldn’t dissociate Unit Test from coding, because Unit Test are important piece of code. On the contrary, I’ve done that to highlight its importance. Applied in Test Driven Development practice, it gives you a high level of understanding of your object and gives you pointers on how to properly apply Single Responsibility Principle. I am a huge fan of TDD even if, I confess, I’m not applying it everytime, especially when dealing with Android components. However, depending on the quality of the code you want to produce, Unit Test are mandatory. It’s also a good documentation for the developer and could prevent from breaking code. So lots of benefits as you can see.
For the Unit tests, I am using Robolectric in combination with Mockito.
The latest Version of Android Studio as well as the Android Gradle Plugin brings support for Unit Testing within the IDE. However, you need to follow this process first. As an android developer, I start feeling annoyed when I have constantly to configure my IDE whenever a new release is on the air.
Then, you need to explicitly add the roboletric gradle plugin to your root build.gradle file, such as :

It’s not finished; you have to apply the ‘org.robolectric’ plugin to the build.gradle file of your module, as described in the documentation.

Also, in order to let Robolectric find the Manifest and properly plays the tests, we need to annotate our testing classes such as :

Finally, if you are a mac user, you need to make another configuration to the IDE, as follow.

Some configuration again that is a waste, blocking you to directly create value.

– Fresh UI

This open source library has been the opportunity to properly implement fresh and interesting components such as RecyclerView, CardView, FloatingActionButton.

– Code Review

I was working alone on the project. So it is important that you ask to friends or other developer to try to review your code. This gives you a very important feedback that could considerably improve the quality of your code.

Continous Integration

It’s very important, when you change your code (and this will happen a lot) that you prevent your change from integration issues. This could easily be detected, with modern and common practice called Continuous Integration. Of course, with no or few tests on your code, continuous integration is useless. But once set up, it’s very convenient.
My Open Source library is hosted on github. I decided to go with TravisCI service, cause it is free, integrated with GitHub and support Android.
Travis is very easy to use. After being signed and linked your github account to the service, you just have to add a « .travis.yml » file to your repository such as described in the documentation. As an example, my travis.yml file looks like :

It simply says to use or to install required version of android, extras & so… Very easy. Then, whenever you push a commit to your repository, a travis job will be triggered.

Publishing on Maven Central

– Process

Pushing your code publicly to github is one step. To make it available on Maven Central as Open Source Software Repository Hosting (OSSRH) is another step. The process requires few steps that could unfortunately take some time. The precise process is as follow :
– First, we need to create an account and a Ticket to provide project information. This will create you a dedicated groupId.
– Then we need to generate signing keys as explained in the requirement pages . To do so, we need to download and install gpg
– We need then to configure our build.gradle to define the uploadTask, as described here.
– Then, we can upload our AAR module by calling the uploadArchives task :

Finally, once deployed to OSSRH, we need to get the component public by closing and releasing the artifact.

As you can see, the process is quite long for the first time. But once set up, you only need to call the uploadArchives task (of course, increase your build version first inside your build.gradle) then make your component public and that’s it.

– Issues and Solutions

#1 SemVer

When trying to release for the first time, the deployment fails. It was due to the fact that the dependencies of my module was using the Semantic Versioning + notation for the patch, such as :

To fix this failure, we have to explicitly set the version, without permissivity, such as :

Unfortunately, by doing this, we loose all the benefits of being permissive with dependency.

#2 transitive dependency

Once deployed publicly, I try to include the freshly released AAR artifact inside another empty android project, by adding this dependency :

However, no matter what, the dependencies of my dependencies were not present. There is probably an issue between the android studio version vs the gradle version of the wrapper vs the android gradle plugin version… The only solution I have found so far is to explicitely enable transitivity when setting dependency, such as :

#3 Unit Testing not working first time

It could happen that the tests are not working on the first launch. This is a know bug. Simply run on your terminal $ ./gradlew clean test

The License

Just for fun, I have decided to create my own license instead of going with traditional license such as gpl or so. This new license is called the « THE VIRGIN-MOJITO-WARE LICENSE » and is highly inspired from the BeerWare License.

Conclusion

Woaa! It’s done now, I can feel released to have gone through all this process.
There is a huge difference between coding on your own computer and hiding the software somewhere in the hard drive, versus making the code available to anyone. Your code belongs now to anyone. The way you code and you designed your application is open to any review. Constructive or not. If you have a big ego, this could be disturbing. But from my point of view, we have to be very humble and I think that any kind of review could only gives you one step forward for self improvement.
It has actually been a very pleasant exercice, even if I was frustrated of the development environment. I spend more time setting up environment (especially for testing, deployment and transitive dependency issue) than creating my code, the value. To be honest with you, I probably have spent 3,5 mornings for coding the entire library and sample (from unit test, designing software architecture, coding in a reactive programming paradigm, learning components that I haven’t used before (such as RecyclerView) to the entire UI).
I hope you’ll find useful information in this post and also hope that the issues I’ve gone through could save you some time. Do not hesitate to use the library, or even better, to review and improve it 🙂

Mocking Bound Services on Android

Let’s suppose we have a Fragment that we want to unit test.
However, let’s also suppose that this fragment binds to/unbinds from a service through its lifecycle callback (onStart(), onStop()).

The main advantage of Bound Service  is that the latter lives only if at least one client is bound to it. By binding to/unbinding from a Service through a Fragment or Activity’s lifecycle, we are in full control of the existence of that Service and triggers it only when the user needs it.

To use a bound service, you mainly need 2 classes : an Android Service and a ServiceConnection that monitors the state of the service connection (Service connected/disconnected).

Below a very simple Service and ServiceConnection :

 

As you can see, as soon as the service is created, an expensive task is triggered within the onCreate() callback.

To bind to the service, we will make proper use of the ServiceConnector within our Fragment’s life cycle :

The Unit Test

As we have already seen, as soon as the service is created, an expensive task is triggered within the onCreate() callback. This could lead to pollute and add uncertainty to the result of our unit test (such as the IBinder being null within the onServiceConnected() callback). Just to remind you, a good unit test should be consistent, which means that it should always return the same result for the same test.

So in order not to be disrupted by the Service, we are goind to mock not only the Service, but also stub the IBinder. Thus, anytime a client (the fragment in our case) wants to bind to the Service, it will receive a stub IBinder that will return a mock Service.
Let’s have a look to the Unit Test (we will use Robolectric and Mockito to do so ) and specifically to the mockBoundLocalService() method:

The Robolectric’s ShadowApplication object has a method called setComponentNameAndServiceForBindService() that allows to set a IBinder for the given Service ComponentName. Using this setter, we are able to pass a stub IBinder within the onServiceConnected() callback whenever a client tries to bind to our service.

 

Unit test Android : testing Fragment’s onSaveInstanceState

On a previous article, we saw how to retain some state of a custom Fragment when the latter is killed and recreated. Below a simple custom logical Fragment that saves a Parcelable into the state bundle and restore it.

The specificity of the test here will be to simulate an activity recreation (as the lifecycle of a Fragment is higly tight to the
Activity’s one) that has the CustomFragment as child.
As testing environment, we will use Robolectric with Mockito.

 

After having instanciated a CustomFragment as well as an Activity, we add that fragment to the activity.
There after, we modify the value of our parcelable (here a Point) that will be saved and restored through the Fragment lifecycle.
Then, we need to go through that life cycle, this is why we use the recreate() method of Activity that will create a new instance of that activity (note that this API is level 11, this is why we annotate our test with @TargetApi(11)), as well as a new instance of our Fragment.
So we get a reference of this new recreatedFragment and simply test that the initial customFragment is a different instance of the newly recreated one and of course, we test that the parcelable has the proper value (the one set before the saving).

Conclusion :

Instead of testing that the Parcelable is saved into the outState Bundle of the onSaveInstanceState() method and properly restored on the onCreateView() method, we simply verify that the Parcelable is correctly handled through the whole lifeCycle. This gives us the elegancy of ignoring where the savedInstanceState is restored (as there are various methods that could do that) and test that at a higher level.

Unit Test Android : starting an activity

In this article, we will cover how to test « starting an Activity ».
As you should know – if you are an android developer – you can start an activity by either calling startActivity(Intent) or
startActivityForResult(Intent, int). The first method belongs to the Context objet while the latest belongs to the Activity object.
As testing environment, we will use Robolectric with Mockito.

For the sake of this study, we will create an ActivityLauncherController that has 2 methods to launch an Activity.

 

We rely on the Android framework, so the idea here is not testing that the NextActivity instances is effectively created when
calling startActivity(), but rather testing that the ActivityLauncherController has properly called the android API that will start
that Activity.

 

As you can see, to test the collaboration with the Context object on the first test, we need to spy a real Context instance so we
can verify the proper startActivity() call on that context.

On the second test, as our startNextActivityForResult() method requires an Activity instance, we can build that instance thanks to Robolectric.buildActivity() and then verify methods call on it.

Conclusion

Starting an activity is very simple on android. Testing it is not that difficult as we are testing the collaboration with the
framework and not the effective creation of the activity.