DEV Community: Nishant Srivastava

Is your Android Library, Lifecycle-Aware?

Nishant Srivastava — Sun, 08 Oct 2017 01:20:24 +0000

Lifecycle events in Android.

It has been a pain point for Android developers all over the world. It is no brainer that, most of the times the main cause of a memory leak in the codebase is because an invalid state is accessed which is out of sync with the lifecycle of the activity/fragment of the app. What this means is that as an Android Developer you are forced to put up a lot of checks in place, making sure that your code state is in sync with the lifecycle of the Activity/Fragment.

Things start to get a bit more messy when that is something you expect from others to do, which is the case when you are an Android Library Developer. As an android library developer, you need other app developers to conform to unregistering callbacks/call cleanup methods or specific functions to re-initialize at certain points in the lifecycle of Activity/Fragment.i.e onDestroy(), onResume(), onCreate(), etc.

Now that is a lot to expect and ask for. We all know developers tend to avoid going through documentations (..to build features quickly and achieve deadlines, obviously ðŸ˜… ). So what that means is sometimes the cleanup part is missed or not understood quite properly for them to put in the right places in code. For example, if an Activity receives a callback after it’s been stopped, then it’s pretty likely that your app is going to crash due to memory leak. Unregistering the callback is right before the Activity is destroyed is what is the needed, which is possible if the app developer calls the cleanup() method from your android library, but it is expected of them. You cannot make sure that they will conform to it.

Well that is a problem, so what is the solution?

The solution is to make your android library Lifecycle-Aware. Making android library aware of the states of the lifecycle of Activity/Fragment gives us, the Android library developers greater control over making sure that callbacks are unregistered and calls to cleanup methods or re-initialization happens at the right state in the lifecycle of Activity/Fragment. At the same time it means less dependence on app developer to conform to putting more code and checks in their app to handle the states of your android library. Sounds like a win-win for both, eh! ðŸ˜Ž

But how do we make our library code Lifecycle AwareÂ ?

Enter, Lifecycle Arch Components!

Lifecycle Arch Components are a new set of lifecycle-aware components that can track the lifecycle of an activity or fragment, and adjust their behavior accordingly.

They are created by good folks at Google, were introduced at Google I/O 2017 and are currently in beta stage. Being in beta does not mean they aren’t ready. They seem to be the way most people are going to be moving forward in the near future as the library itself becomes stable. But we can get on the band wagon right now, as they are fairly ready.

Update: Core lifecycle artifacts (runtime, common) have reached stable version v1.0.0. The lifecycle compiler and extensions are now at version v1.0.0-beta1

Without taking much time, lets jump right into understanding how to wire these lifecycle components for your own android library…

I will be using a simple example to demonstrate the wiring up process, which is available as a completely functional example app on github here.

Lets start by creating a new app. Once done, you can add a new library module

Your folder structure should look like the below

Next add this awesomelib module as a dependency to the app module, so that the app module has access to the public classes contained by the awesomelib library module. To do that add the below to the build.gradle of the app module.

implementation project(':awesomelib')

Next you want to add a class to your awesomelib library module. I created mine named as AwesomeMainLibÂ . This class is just to showcase the code for library which will be referenced in the app module later on. For simplicity sake, lets make AwesomeMainLib class a singleton. The code in that case would look like below

and in your app module you would call init() method via AwesomeLibMain.getInstance().init() in onCreate() and cleanup() method via AwesomeLibMain.getInstance().cleanup() in onDestroy() respectively. Here is the code of MainActivity.java class in app module

But thats not the point here, right! We do not want the app developer to be calling these themselves. Also what happens if you want to trigger more methods at specific points in lifecycle of Activity/Fragment? The dependence on app developer increases by many folds and expecting them to do everything right is a like a chink in the armour.

Well let us solve this situation by integrating with Lifecycle Arch Components.

The first thing we need to do is add the required dependencies to build.gradle to each module.

Add the below to the build.gradle for awesomelib module

implementation "android.arch.lifecycle:runtime:1.0.0"
annotationProcessor "android.arch.lifecycle:compiler:1.0.0-beta1"

and add the below to the build.gradle for app module

implementation "com.android.support:appcompat-v7:26.1.0"

Note: We are using the latest support lib v26.1.0Â , which now has AppCompatActivity implementing LifecycleOwner interface from Architecture Components. More about this, later in the post. For now just know you need support lib v26.1.0

… that done, sync your project.

Now is the time for us to integrate Lifecycle Arch Components into our android library module, awesomelib

We start by first implementing LifecyleObserver class in our AwesomeLibMain class.

From android official docs: LifecycleObserver is an interface which does not have any methods, instead, relies on OnLifecycleEvent annotated methods to mark the class for lifecycle events.

Now comes the magic. Once you have integrated Lifecycle Arch components, you have access to annotations which correspond to lifecycle events of Activity/Fragment such as

@OnLifecycleEvent(Lifecycle.Event.ON_CREATE)
or 
@OnLifecycleEvent(Lifecycle.Event.ON_DESTROY)
..and so on

Once you annotate the right method with the specific annotation, that method would be triggered at the specified lifecycle event state, during the execution of Activity/Fragment.

Lets have a look at what our AwesomeLibMain class look, after we have annotated the methods

as you can see I added more methods and annotated them to get triggered at specific lifecycle event state.

But we are not done here yet. This just tells which method will be triggered when a specific lifecycle event state is reached for the Activity/Fragment. What is still required is to add our AwesomeLibMain class as an Observer for the lifecycle of the desired Activity. Turns out it is a really simple step, as can be seen below

Note: MainActivity here extends AppCompatActivity because we are using the latest support lib v26.1.0Â , which now has AppCompatActivity implementing LifecycleOwner interface from Architecture Components.

From android official docs: LifecycleOwner is a single method interface that denotes that the class has a Lifecycle. It has one method, getLifecycle(), which must be implemented by the class.

If you are using a version of support lib below v26.1.0 then MainActivity will need to extend LifecycleActivity and app module’s build.gradle will need to include to get access to LifecycleActivity.

implementation "android.arch.lifecycle:extensions:1.0.0-beta1

so you basically needed to add it as an Observer for lifecycle in onCreate() of Activity via

// Add Lifecycle Observer
getLifecycle().addObserver(AwesomeLibMain.getInstance());

…and then remove the Observer for lifecycle in onDestroy() of Activity via

// Remove Lifecycle Observer
getLifecycle().removeObserver(AwesomeLibMain.getInstance());

Thats it! No, really thats all there is. You have successfully integrated lifecycle arch components in your awesomelib and now it is observing Activity Lifecycle events and triggering the right methods at the right time, without requiring the app developer to worry about anything.

Note: This is the only step app developer needs to do when going to use your android library in terms of integrating your library code in the activity, apart from adding it in the build.gradle dependency section. All methods will be triggered automatically when a said lifecycle event state is reached during the execution of the Activity/Fragment.

What I have tried to explain here is more like a proof of concept, I am sure one can very easily implement it in an existing android library code and make use of the benefits lifecycle arch components bring along.

For people worried about adding a lot of method counts to their app, below is a snapshot of method counts (used Classyshark Tool) for the used arch component libs, awesomelib module and the sample app itself (from the sample app I have linked below)

Simple rundown shows the method count for

arch component libs–122 methods
awesomelib-5 methods

So as you can see they are pretty light in terms of adding method count. Support library is part of the app module and something usually all apps nowadays have, so you are basically not shipping your android library with that. ðŸ˜…

As mentioned at the start of this post, the code for above is available on github here.

If you have suggestions or maybe would like me to add something to the content here, please let me know.
Till then keep crushing code ðŸ¤“

I gave a talk on this topic at Droidcon Berlin ’17, checkout the slides here.This post got featured in Android Weekly Issue 276! ðŸ˜Ž

P.S. : This post is also published on medium. and my own blog

Want To Step Up Your Android Learning Game? You Need To Read This First

Nishant Srivastava — Sun, 30 Jul 2017 06:28:30 +0000

DISCLAIMER: If you consider yourself a beginner, intermediate, expert or a ninja in the Android realm, this secret sauce still applies to you.

TL;DR: Build Something.

No really! I am not kidding here. Hear me out on this.

The secret to becoming better at Android development, with all the new shiny stuff being released every year and making you go through the fear of missing out and what not is just to build out something that’s functional, even before reading a blog post or documentation.

It is really very easy to say you read up the documentation and you have gone through a blog post that explains the intricate concepts/a new library introduced by either Google or some 3rd party developer/company. I am not saying it’s not required or a waste of time because it’s very important to understand the concepts and then proceed with the using the new and shiny library or a new concept you just came to know about. You SHOULD always understand the underlying concepts to keep yourself from misusing the API/framework/architecture approach.

But here is where I would like to pause and mention a different approach which has worked for me always and with people I have introduced this concept to. The concept isn’t anything new. It’s a simple extra step of approaching a new library/architecture in Android realm, which is to…

..build a simple, isolated and bare bone example android app to see a working example of what your are trying toÂ learn.

That’s all. I call this Example Driven Development(EDD) approachðŸ¤“.

The reason this works out very well is that these simplified examples Android apps are devoid of any complexity you would have in your own apps. If you are like me who likes to see things working before jumping into implementing it in the complex app I am working on, this approach will be very interesting to you (unless of-course you are already aware of it and use it, in that case, jump to the bottom of this story ðŸ˜… )

These simplified examples android apps also provide you opportunities to experiment with concept/library you are trying to implement as well as spot possible bugs or issues far before you would have done otherwise if you would have implemented it directly inside your complex Android app.

Some people might argue that it is a time taking process and eventually a waste of time and energy because at the end of the day the example app is thrown out of the window and the concept/library has to be implemented into the android app you are working on.

I strongly disagree to that point, with my own personal reasons to justify that (based on my experience). This might not be true for everyone, but I have found it to work for the majority of people I have suggested this approach. I believe such simplified example android apps are like

Unit Tests, simple and focused to understand the functionality and working of the concept/library.
Comments in code, they are there for you to comeback to, understand how the concept/library works and plays along with on the platform at the most basic level.

It wouldn’t make sense for me to advocate an approach if I can’t show how I use it for myself, correct?

So I happen to be following this approach for sometime now and it so happens some people in the community reached out to me to share the same with them. And thus Android Example came to exist as it is today…

…I created this repo last year where I started putting in all the example apps I had built while working on a feature/library/concept as I was doing android development at work or while just learning something new for myself. Turns out it has grown quite big now with 100+ android examples (including sample apps from android libraries I have built myself)

Do check it out, to get a taste of what I have been blabbering about up until now. Just jump in and build up one of the apps demonstrating concept/library implementation that you always wanted to understand and get your hands dirty hacking on the code!

Better still, contribute back to the repo with more (missing) simplified android examples or improving the ones that exist in the Github repo. Contributions of any size are always welcome.

If you still think that this approach is flawed, I am more than happy to hear about anything else that has worked for you.

If you have suggestions or maybe would like me to add something to the content here, please let me know.

P.S: I did a write up sometime back about how I manage dependencies for such a huge number of example apps. If you are interested in that you can find that here

This post was originally shared on my blog Crushing C.O.D.E, here and is also published on medium.

Checkout my Github or simply follow me on Twitter ðŸ˜

Until next post keep crushing code ðŸ¤“

Things I wish I knew when I started building Android SDK/Libraries

Nishant Srivastava — Tue, 21 Mar 2017 18:07:54 +0000

Note: This post was originally published on medium. and also featured in Android Weekly

It all starts when some android developer tries to figure out a solution to a problem he/she is having while building their "Awesome Android App". During the process, most developers would encounter a couple of issues and in tandem, to those, they would come up with possible solutions.

Now here is a thing, if you are like me, who believes that if the problem was big enough for me to spend some time on it and there wasn’t an existing solution out there, I would abstract the whole solution in a modular manner, which eventually turns out to be an android library. Just so that whenever in future I encounter this problem again, I can reuse this solution easily.

So far, so good. So you have built the library and probably started using it completely privately or if you think someone else could make use of the same solution you release the code as an android library i.e.you open source the code. I believe (..or rather that is what it looks like..) at this point everyone thinks they are done.

WRONG! This very point is where most people usually miss out that this android library code is going to be used by other developers that do not sit next to you and that to them this is just some android library they wish to use to solve a similar problem. The better your approach of designing the API the better the chances of making sure that the library will be used as it is intended to be and whoever is using it isn’t confused. It should be clear from the very start what needs to be done to start using the library.

Why does this happen?

The devs that write these android libraries are usually the ones who don’t care about the API design when building one. At least the majority of them don’t. Not because they are indifferent but I think most of them are just beginners and there is no set rules that they can look up to be better at designing the API. I was in the same boat some time back, so I can understand the frustration of not having a lot of information in this field.

So I have had my experiences and I happen to release some of the code as android libraries (which you can check out here). I have come up with a quick list of points which each and every developer who designs an API in the form of Android Library should keep in mind (some of them may apply to designing API in general too).

Point to note here, my list isn’t exhaustive and I may not be covering everything. It covers things I have encountered and wished I knew it when I started and thus I will keep on updating this post as and when I learn with more experience in the future.

Before we dive into anything let’s first answer the most basic questions that everyone would have regarding building Android SDK/Library. So here goes

Why would you create an android SDK/Library?

Sure it is...well, you do not have to create an SDK/library in all cases. It makes more sense to decide on building one based on the understanding of what value you bring to the table. Ask yourself the below

Is there some existing solution that would solve the problem?
If your answer is Yes, then possible try and use that existing solution.
Say that does not solve your specific problem, even in that scenario it is better to start by forking the code, modifying it to solve the problem and then using it versus starting from scratch.

Bonus Points to you if you go ahead and submit a Pull Request to get the fix you made pushed into the existing library code so that the community can benefit from it.

If your answer is No, then go ahead and build the android SDK/library. Share it with the world later on so that others can make use of it in their projects.

What are the packaging options for your artifacts?

Even before you start building your library you need to decide on how do you want to deliver your artifacts to developers.
Let me start here by describing some terms which we might use in the post here. To begin with let me describe what is an artifact first,

In general software terms, an "artifact" is something produced by the software development process, whether it be software related documentation or an executable file.
In Maven terminology, the artifact is the resulting output of a maven build, generally a jar , war , aar or other executable files.

Let’s look at the options you have

Library Project: Code that you have to checkout and link into your project. It is the most flexible one as you can modify the code once you have it in your code, but also introduces issues such as being in sync with upstream changes.
JAR: Java ARchive is a package file format typically used to aggregate many Java class files and associated metadata into one file for distribution.
AAR: Android ARchive is similar to JAR with added functionality. Unlike JAR files, AAR files can contain Android resources and a manifest file, which allows you to bundle in shared resources like layouts and drawable in addition to Java classes and methods.

We have the artifact, Now what? Where does one host these artifacts?

Not really...
Turns out you have a couple of options here too, each having its own pros and cons. Let’s take a look at each

Local AAR

If you happen to be very specific about not wanting to put your android library artifact into any repository, you can generate your local aar file and use that directly. Read this stackoverflow answer to understand how to do that.

In a gist is you need to put the aar file in the libs directory (create it if needed), then, add the following code in your build.gradle :

dependencies {
   compile(name:'nameOfYourAARFileWithoutExtension', ext:'aar')
 }
repositories{
      flatDir{
              dirs 'libs'
       }
 }

..what comes with this is that now whenever you want to share your android library you are passing around your aar file(…which is not the best way to share your android library).

Avoid doing this as much as you can, since it is prone to a lot of problems the biggest one being manageability and maintainability of the code base.
Another issue with this approach is you cannot make sure that the users of this artifact are in sync with the latest code.
Not to mention the whole process is lengthy and prone to human error, just to integrate the library in an android project.

Local/Remote Maven Repositories

What if you wanted to use the android library privately?
The solution for that is to deploy your own instance of artifactory (read about how to do that here) or using Github or Bitbucket repository as your own maven repository (read about how to do that here).

Again this is specific to you using your android library privately. If you want to share this with others its not the approach you wanna stick to.

The first issue that this approach has is that your artifact is in a private repository, to give access to this library you have to give access to the private repository which could be a security issue.
The second issue is that to use your android library one would need to include an extra line in their root build.gradle file

allprojects {
    repositories {
        ...
        maven { url 'http://url.to_your_hosted_artifactory_instance.maven_repository' }
    }
}

..which to be fair is an extra step and we are all here to make the process simpler. It is easier on the creator part to push the android library out quickly but adds an extra step for the users to use the library code.

Maven Central, Jcenter or JitPack

Now the easiest way to push it out immediately is via JitPack. So you would want to do that. JitPack takes your code from a public git repository, checks out the latest release code, builds it to generate the artifacts and later publishes to their self-hosted maven repository.
However, the issue at hand is same as the one for local/remote maven repositories that users of your android library would need to include an extra line in their root build.gradle file

allprojects {
    repositories {
        ...
        maven { url 'https://www.jitpack.io' }
    }
}

You can read about how to publish your android library to JitPack here.

The other option you have is of Maven Central or Jcenter.

Personally I would suggest you stick to Jcenter as it well documented and better managed. It is also the default repository that is looked up for dependencies in Android projects (…unless someone changed it).

If you publish to Jcenter, bintray the company behind it gives you the option to sync with Maven Central from within their publishing platform. Once published it is as simple as adding the below line to your build.gradle file to use the library in any android project

dependencies {
      compile 'com.github.nisrulz:awesomelib:1.0'
  }

You can read about how to publish your android library to Jcenter here.

With all those basic questions out of the way, let us look at things one should take care of while building an Android SDK/Library

Avoid multiple arguments

Every android library has to be usually initialized with some arguments and to do that you would usually be passing a set of arguments to either a constructor or have an init function to setup your library. Whenever doing that consider the below

Passing more than 2–3 arguments to your init() function is bound to cause more headaches than provide ease of use.

Just because its hard to remember the exact mapping of these arguments and the order in which they are declared in the library code.It also is prone to more mistakes as anyone can make a mistake of passing int value in a String field or vice versa.

// DONOT DO THIS
void init(String apikey, int refresh, long interval, String type);
// DO this
void init(ApiSecret apisecret);

where ApiSecret is an Entity Class, declared as below

public class ApiSecret{
    String apikey;
    int refresh;
    long interval;
    String type;
    // constructor
    /* you can define proper checks(such as type safety) and
     * conditions to validate data before it gets set
     */

    // setter and getters
}

Or you can also use Builder Pattern as an alternative approach to the above.

You can read more about Builder Pattern here. JOSE LUIS ORDIALES talks in depth about how to implement it in your code, take a look here.

Ease of use

When building your android library, keep in mind the usability of the library and the methods you expose. It should be

Intuitive

For everything that's happening in the android library code, there should be some feedback either in the logs or in the view. Depends on what kind of an android library is being built. If it does something that cannot be comprehended easily, the android library basically “does not work in the language of devs. It should do what the user of android library expects it to do without having to look up the documentation.
Consistent

The code for the android library should be well thought and should not change drastically between versions. Follow semantic versioning.
Easy to use, Hard to misuse

It should be easily understandable in terms of implementation and its usage in the first sight itself. The exposed public methods should have enough validation checks to make sure people cannot misuse its functionality other than what it was coded and intended for.Provide sane defaults and handle scenarios when dependencies are not present.

In short…

Minimize Permissions

In the current times, when everyone just wants to jump the road and ask as many permissions, you should pause and think about do you really need that extra permission. Take care of these points especially

Minimize your permissions as much as you can.
Use Intents to let dedicated apps do the work for you and return the processed result.
Enable and disable your features based off if you have the permission for it. Do not let your code crash just because you do not have the said permission. If at all, you must educate the user well before requesting the permission and that why it is required. If possible have a fallback functionality if the permission isn’t approved.

This is how you check if you have a said permission granted or not:

public boolean hasPermission(Context context, String permission) {
  int result = context.checkCallingOrSelfPermission(permission);
  return result == PackageManager.PERMISSION_GRANTED;
}

Some of the devs would say that they really need that specific permission, what to do in that case. Well, your library code should be generic for all types of apps that need the specific functionality. If you can provide hooks such as functions to let users of your android library pass the data you need the dangerous permission for. In that way, you do not force the devs to require a permission they do not want to. In absence of the permission provide a fallback implementation. Simple.

/* Requiring GET_ACCOUNTS permission (as a requisite to use the 
 * library) is avoided here by providing a function which lets the 
 * devs to get it on their own and feed it to a function in the 
 * library.
 */
MyAwesomeLibrary.getEmail("username@emailprovider.com");

Minimize Requisites

We have all been there. We have a specific functionality that requires that the device has a certain feature. The usual way you would approach this is by defining the below in your manifest file

<uses-feature android:name="android.hardware.bluetooth" />

..the problem with this is that when this is defined in the android library code, this would get merged into the app manifest file during the manifest-merger phase of build and thus hide the app in Play Store for devices that do not have the Bluetooth unit (this is something the Play Store does as filtering). So basically an app that was earlier visible to a larger audience would now be visible to a smaller audience, just cause you added that to your library code.

Well, that’s not we want, do we? Nope. So how do we solve this?
Well what you need to do is not include that uses-feature in your manifest file for the android library but rather check for the feature during runtime in your code as below

String feature = PackageManager.FEATURE_BLUETOOTH;
public boolean isFeatureAvailable(Context context, String feature) {
 return context.getPackageManager().hasSystemFeature(feature);
}

.. this way there is no entry in the manifest and once it merges into the app, it won’t let the app get filtered in the Play Store.

As an added feature though if the feature is not available you can just disable the functionality in your library code and have some fallback functionality in place. It is a Win- Win for both the android dev who built the library and the dev who integrates the lib in their app.

Support different versions

_How many are out there exactly?_

If you have a feature that’s available in a certain version of android, you should do the check for that in code and disable the feature if the version is lower than supported.
As a rule of thumb support the full spectrum of versions via defining in minSdkVersion and targetSdkVersion. What you should do internally to your library code is check for the android version at runtime and enable/disable the feature or use a fallback.

// Method to check if the Android Version on the device is greater than or equal to Marshmallow.
public boolean isMarshmallow(){
    return Build.VERSION.SDK_INT>= Build.VERSION_CODES.M;
}

Do not log in production

_Just DO NOT._

Almost every time I am asked to test an app or an android library project the first thing that I have seen is that they log everything up in the open, in their release code.
As a rule of thumb, never log in production. You should use build-variants with timber to help you in the process to separate logging info in production vs debug builds. A simple solution can be to provide a debuggable flag that the devs can flip to enable/disable logging from your android library

// In code     
boolean debuggable = false;
MyAwesomeLibrary.init(apisecret,debuggable);
// In build.gradle     
debuggable = true

Do not crash silently and fail fast

I have seen this a lot of times now. Some of the devs would not log their errors and exception in logcat! Which basically adds a headache to the users of the android library when they are trying to debug the code. In tandem to the last tip about not logging in production, you must understand that exceptions and errors need to be logged irrespective of being in debug or production. If you do not want to log in production, at least provide a functionality of enabling logs via passing some flag when you initialize your library. i.e

void init(ApiSecret apisecret,boolean debuggable){
      ...
      try{
        ...
      }catch(Exception ex){
        if(debuggable){
          // This is printed only when debuggable is true
          ex.printStackTrace();
        }
      }
      ....
}

It is important that your android library fails immediately and shows an exception to the user of your android library instead of being hung up on doing something. Avoid writing code which would block the Main Thread.

Degrade gracefully in an event of error

What I mean by this is that when say your android library code fails, try to have a check so that the code would not crash the app instead only the functionality provided by your library code is disabled.

Catch specific exceptions

Continuing with the last tip, you might notice that in my last code snippet I am using a try-catch statement. Catch statement specifically catches all Exception as its a base class. There is no specific distinction between one exception vs the other one. So what one must do is define specific types of Exception as per the requirement at hand. i.e NUllPointerException, SocketTimeoutException, IOException, etc.

Handle poor network conditions

_…this gets on my nerves, seriously!_

If the android library you wrote deals with making network calls, a very simple thing that usually goes unnoticed is that you should always consider a case of what happens if the network is slow or non-responsive.

What I have observed is that library code developers assume that the network calls being made will always go through. A good example will be if your android library fetches some config file from the server to initialize itself. Now when developing the library the devs assume that the config file will always get downloaded. What they forget is that on a flaky network, the library code will not be able to download the config file and hence would crash the whole codebase. If simple checks and a strategy to handle such situations are built right into the android library code, it saves quite a number of people the headaches they would have otherwise.

Whenever possible batch your network calls and avoid multiple calls. This also saves a lot of battery, read here
Reduce the amount of data you transfer over the network by moving away from JSON and XML to Flatbuffers.

Reluctance to include large libraries as dependencies

This one goes without much explanation. As most of fellow Android Devs would be knowing, there is a method count limit of 65K methods for android app code. Now say if you have a transitive dependency on a large library, you would introduce two undesirable effects to the android app your library is being included

You will considerably increase the method count of the android app, even though your own library codebase has a low method count footprint since you would transitively download the larger library and thus it will contribute to the method count too.
If the method count hits the 65K limit, just because of your library code that transitively downloaded the larger library, the app developer will be forced to get into the lands of multi-dexing. Trust me on this, no one wants to get into the multi-dexing world. In such a scenario, your library has introduced a bigger problem than solving the initial problem. So most probably your library will be replaced by some other library that does not add to the method count or basically that takes care everything in a better way.

Do not require dependencies unless you very much have to

Now this rule is something that I think everyone knows, right? Do not bloat your android libraries with dependencies you do not need. But the point to note here is that even if you need dependencies you do not have to make the users of the library download it transitively. i.e the dependency does not need to be bundled with your android library.

Well, then the question arises as to how do we use it if it is not bundled with our library?

Well, the simple answer is you ask your users to provide that dependency to you during compile time. What this means is that not every user might need the functionality which requires the dependency. And for those users, if you cannot find the dependency as provided to you, you just disable the functionality in your code. But for those who need it, they will provide you the dependency, by including it in their build.gradle .
How to achieve this? Check in classpath

private boolean hasOKHttpOnClasspath() {
   try {
       Class.forName("com.squareup.okhttp3.OkHttpClient");
       return true;
   } catch (ClassNotFoundException ex) {
       ex.printStackTrace();
   }
   return false;
}

Next, you can use provided(Gradle v2.12 and below) or compileOnly(Gradle v2.12+)(Read here for complete information), so as to be able to get hold of the classes defined by the dependency during compile time.

dependencies {
   // for gradle version 2.12 and below
   provided 'com.squareup.okhttp3:okhttp:3.6.0'
   // or for gradle version 2.12+
   compileOnly 'com.squareup.okhttp3:okhttp:3.6.0'
}

A word of caution here, you can only use this functionality of requiring a dependency if its a complete java dependency. i.e if its an android library you want to include at compile time, you can not reference its transitive libs as well as resources which need to be present before compilation. A pure java dependency, on the other hand, has only java classes and they are the only ones that would be added to classpath during the compilation process.

Try not to hog the startup

_no kidding…_

What I mean by this is that, as soon as the app starts up try not to initialize your android library greedily. What that would tend to do is that it will increase the startup time for the App itself, even though the app does simply nothing at startup except off course initialize your android library.

The solution to such a problem is to do all work of initializing off the main thread i.e in a new thread, async. Better if you use Executors.newSingleThreadExecutor() and keep the number of thread to just one.

Another solution would be to initialize components of your android library on demand i.e Load them up/initialize them only when they are needed.

Remove functionality and features gracefully

Do not remove your public functions between versions as that would lead the builds of many users of your android library break and they would be clueless as to why did that even happen.

Solution: Deprecate the functions by marking them @deprecated and then define a roadmap of their removal in future versions.

Make your code Testable

Making sure you have tests in your code isn’t actually a rule to follow. You should be doing this everywhere and for every project app or library without saying.

Test your library code by making use of Mocks, avoiding final classes, not having static methods, etc.

Writing code with interfaces around your public API also makes your android library capable of swapping implementations easily and in turn, makes the code more testable.i.e you can provide mock implementations easily when testing.

Document Everything!

Being the creator of the android library you would know about your code, but the people who are going to use it won’t know about it unless you expect them to figure out by reading your source code (you should never need that).

Document your library well including every detail about how to use it and detailing every feature you have implemented.

Create a Readme.md file and place it at the root of your repository.
Have Javadoc comments in your code, covering all public functions. They should cover and explain
- Purpose of the public method
- The arguments passed
- Return type
Bundle a sample app which demonstrates a working example of how the library and its features are used.
Make sure you keep a detailed change log for your changes. A good place to do that would be to add the information right in your release section for the specific version tag.

_Screenshot of Github Releases section for Sensey android library_

…and here is the link to releases section for Sensey

Provide a most minimalistic Sample App

This goes without saying. Always provide the most minimalistic Sample app with your library code, as that is the first thing other devs will checkout to understand a working example of using your android library.

The simpler it is the easier it is to understand. Making the sample app look fancy and code complex would only undermine the actual goal of the sample app, that is to provide a working example of using your android library.

Consider putting up a License

Most of the time developers forget about the Licensing piece. This is one factor that decides the adoption of your android library.

Say you decided to license your android library in a restrictive manner i.e Using GPL license, would mean that whoever uses your library and makes modification will have to contribute back to your codebase in order to keep using the android library. Putting such restrictions hampers the adoption of android libraries and developers tend to avoid such codebases.
The solution to this is that you stick to more open licenses such as MIT or Apache 2.

Read about licensing at this simple site and about need of copyright in your code here

Last but not the least, get feedback

Yeah, you heard that right! Your android library was built to cater to your needs initially. Once you put it out for others to use, you will come to know a lot of issues in it. Hear out your fellow devs and gather feedback. Act on it considering and weighing on the functionality to introduce or fix while maintaining the goals of the android library intact.

Summary

In short, you need to take care of the below points while building

Avoid multiple arguments
Ease of use
Minimize permissions
Minimize requisites
Support different versions
Do not log in production
Do not crash silently and fail fast
Degrade gracefully in an event of error
Catch specific exceptions
Handle poor network conditions
Reluctance to include large libraries as dependencies
Do not require dependencies unless you very much have to
Try not to hog the startup
Remove features and functionalities gracefully
Make your code testable
Document everything
Provide a most minimalistic sample app
Consider putting up a license
Get feedback, lots of them

As a rule of thumb follow the rule of SPOIL-ing your Library

Simpleâ€Š–â€ŠBriefly and Clearly expressed
Purposefulâ€Š–â€ŠHaving or showing resolve
OpenSourceâ€Š–â€ŠUniversal Access, Free license
Idiomaticâ€Š–â€ŠNatural to the native environment
Logicalâ€Š–â€ŠClear, Sound Reasoning

I read this some time back in a presentation by some author I cannot recall. I took note of it as it makes a lot of sense and provides a clear picture in a very concise manner. If you know who the author is, please comment it and I will add his link and give due credit.

Ending Thoughts

I hope this post helps fellow android devs in building better android libraries. Android Community benefits extensively from using android libraries published daily by fellow android devs and if everyone starts to take care of their API design process keeping in mind the end user (other android developers) we would all be a step closer to an even better ecosystem as a whole.

These guidelines are compiled on my experience of developing android libraries. I would love to know your views on the pointers mentioned above. Please leave a comment, and let me know!

If you have suggestions or maybe would like me to add something to the content here, please let me know.

Checkout my Github or simply follow me on Twitter and keep on crushing code!ðŸ¤“ ðŸ˜

I could not find a simple Gesture Detection android library, so I built one

Nishant Srivastava — Sun, 19 Mar 2017 06:01:18 +0000

Note: This post was originally published on medium.

While working on various projects, there have been times when I have had to implement various gesture-based events. Every time I have had to do that I had to write the whole code for getting the SensorManager and getting access to the SensorEvent, plus the extra logic to detect the gesture. At first, it was just fine to do that since I was a beginner around that time. Then soon I got weary of the whole boilerplate. Around this time I started looking for a solution like an android library which would help me avoid all that boilerplate as well as enable me to maintain my code properly.

Problem

Well, the problem at hand is basically the boilerplate code and the need to maintain your code. Duplicating code across projects and remembering the logic for each gesture was bound to end up in one of the projects in some form of error. It was no doubt inefficient and very repetitive. I was looking for a solution to all this because as Software Engineers we all strive to automate tasks or remove the need for duplicating code. As Douglas Crockford has said

“Code reuse is the Holy Grail of Software Engineering.”

What was disappointing was that everything available was either too complex in terms of implementation or was very limiting.
..and that's when I decided to write my own Android Library, Sensey.

Sensey was born out of a need to be able to make Gesture Detection in android as simple as it can get. Not everyone needs to look up x, y, z values of Accelerometer or Azimuth, Pitch and Roll values of Orientation Sensor*. There are other devs who only wish to detect if a certain Gesture was detected or not (period).

So when I set out to build Sensey, I had a very clear mindset that I want it to be exactly thatâ€Š–â€Šsimple and clean.
When I first wrote Sensey, it wasn't perfect. But it did the job well for me. Since I couldn't find the solution for myself in the first place, I guessed (or assumed) that at least a few devs in the community would be in the same boat as me and thus from the start I was sure to make it open sourced (You can check it out on Github).

I recently released the version 1.6.0 of Sensey and you can tell that it has come a long way from what it was in version 1.0. Let's walk through the process of integrating Sensey.It is super simple to integrate Sensey in your current android project.

Simply add the below to your build.gradle file

compile 'com.github.nisrulz:sensey:1.6.0'

..sync your gradle and then initialize Sensey in your activity

Sensey.getInstance().init(context);

That's it! Sensey at this point is integrated into your app. Now based on what kind of Gesture you want to detect, you will need to start and stop detectors provided by Sensey.

Say for the sake of a simple example, if we wanted to detect a Shake Gesture. All you need to do is

Create an instance of ShakeListener

ShakeDetector.ShakeListener shakeListener=new ShakeDetector.ShakeListener() {
    @Override public void onShakeDetected() {
       // Shake detected, do something
   }
   @Override public void onShakeStopped() {
       // Shake stopped, do something
   }
};

Now to start listening for Shake gesture, pass the instance shakeListener to startShakeDetection() function

Sensey.getInstance().startShakeDetection(shakeListener);

To stop listening for Shake gesture, pass the instance shakeListener to stopShakeDetection() function

Sensey.getInstance().stopShakeDetection(shakeListener);

Yup, that's about all it takes to know if a shake gesture was performed and when it stopped.

Let's check out the complete list of gesture detectors Sensey provides

Flip Detector

Sensey can detect if your device facing up or facing down. Check out the implementation here.

Light Detector

Sensey can detect if your device in a position where it is receiving any light or not. Check out the implementation here

Orientation Detector

Sensey can detect if your device's top side is up or bottom side is up. It can tell if your device's left side is up vs right side being up. Check out the implementation here.

Proximity Detector

Sensey can detect if there is an object in the proximity of the device i.e either it is far or near to the device. Check out the implementation here.

Shake Detector

Detects a Shake gesture performed on the device and also when the gesture stops.Check out the implementation here.

Wave Detector

This one is a simple implementation. It uses proximity sensor with timing to detect if a hand wave gesture is performed in front of the device screen. Check out the implementation here.

Chop Detector

Added in release 1.6.0 this one is brand new. It allows you to detect if a Chop gesture is performed with the device. Check out the implementation here.

Wrist Twist Detector

Added in release 1.6.0 this one is another brand new detector. This one allows you to detect if the wrist was twisted in a circular manner while holding the device. Check out the implementation here.

Movement Detector

Another brand new detector added in release 1.6.0, it allows you to know if the device was moved or not. Once moved, it will also detect when the device becomes stationary. Check out the implementation here.

Sound Level Detector

Another brand new detector added in release 1.6.0, it allows you to measure the loudness of sound in the environment around the device (calculated on a scale of dB i.e decibel).Check out the implementation here.

Pinch Scale Detector

Sensey can use this detector to know if the user is executing a pinch scale in or out gesture on the touch screen. It will also be able to detect when the scale gesture was stopped. Check out the implementation here.

Touch Type Detector

This one can do a lot of things, you can choose which one to use or not to use. It can detect when someone on the device screen does the following:

Single Tap
Double Tap
Two Finger Tap
Three Finger Tap
Scroll Up, Down, Left or Right
Swipe Left or Right
Long Press

Check out the implementation here.

Phew! That's a lot of gesture detectors packed inside one android library. Well, the list will keep on growing when more gestures get implemented in future releases. The core focus though would always remain the same,

simplicity over complexity and ease of use.

Who is it for

For people who simply want to detect gesture as an event.

Who is it not for

For anyone who wishes to get more advance and wants to tap into the raw SensorEvent values.

That said, the android library isn't perfect and I would love it if you can try it out and file issues on Github to make it better.

Check out Sensey on Github (Star the repo if you find it useful)

If you have suggestions, please let me know in the comment section.

Checkout my Github or simply follow me on Twitter and keep on crushing code!ðŸ¤“ ðŸ˜

Hi, I'm Nishant.

Nishant Srivastava — Sat, 18 Mar 2017 05:05:14 +0000

Hi, I'm Nishant Srivastava.

I am a Software Engineer/Founding Team Member (at) OmniLabs, Inc. with 4 years of experience in Android SDK Engineering, DSP and Interaction Design. I am an avid dreamer, doodler, FOSS enthusiast and a caffeine-dependent life-form.

I am also the lead organizer (at) Google Developer Group, New Delhi.

I am recommended by 4 out of 5 people that recommend things ;)

You can find me on

Twitter as @nisrulz
Github as nisrulz