JSONApi is a Blessing For Offline Ready Apps

Recently, I was talking to friend who is working on a new startup. We were talking about how they are planning to handle mobile clients and he mentioned that they are using JSON API. I remember seeing it before but didn’t pay much attention. After talking to my friend, I decided to read more about it and I loved it.

JSON API is a well defined response format that is targeting to put an end to API response format debates and maximize response caching benefits. It has a bunch of good ideas but what made me love it is the fact that relationships are not nested, rather they are returned as id references and the response has a root item which has the array of included (referenced) objects.

For example, if you have an API that returns a list of Books and each book has its own Author, rather than having an Author object in the Book response JSON, it includes a Relationship object in the Book JSON that has an id field that keeps the Author‘s id and a type that is set to authors. Then, there is an additional included array in the response that includes the Author object.

So instead of this:

  "id" : 4,
  "name" : "Framework Design Guidelines",
  "author" : {
    "id" : 42,
    "name" : "Brad Abrams"

Your response JSON looks something like this:

"data" : {
  "type" : "books",
  "id" : "4",
  "attributes" : {
    "name" : "Framework Design Guidelines",
  "relationships" : {
    "author" : {
      "type" : "authors",
      "id" : "42"
"included" : [{
  "type" : "authors",
  "id" : "42",
  "attributes" : {
    "name" : "Brad Abrams"

Now you might be asking yourself, “So what? What does it have to do with offline ready app architecture?”

I helps you solve a great problem, relations.

The #1 building block for an offline ready app is driving the UI from a persistent model. This means you never* fill your UI from a network request. You never write a code that makes a web service query and updates the UI based on that. Instead, you always build your UI from the model and you have business logic that updates the persistent model based on user’s current state (e.g. the page they are visiting etc).

When it comes to persistence, relationships are a problem. Relational databases solve this problem with foreign keys and there are many ORMs trying to map it to the application code. This always brings the question, do I load the object light (w/o relationships) or full (w/ relationships). In other words, if we look at the example above, when we load the book, do we load the author field as well?

The answer depends on the UI and most ORMs give you the option. They also give you the option to do lazy loading where the relationship will not be loaded until it is accessed (e.g. unless you call book.getAuthor()). It works great on the server side, not so much on the client side where when you access the data matters a lot.

This is like a mine planted that will explode eventually.

Lets look at an example. Assume you are showing list of books where the author name is not visible. So when developing the page, you use the lazy loading. Months after, PM changes their mind and wants to display author name. Easy, you just call book.getAuthor().getName() in the onBind method of your RecyclerView. BOOM you are querying the database to fetch the author on the UI thread. Worse, you probably won’t notice the problem in your tests because it is fast or cached. But not when the database is busy handling a write, which will block all reads (for sqlite). Even w/o that, accessing disk on the main thread should be avoided when possible so even though it is fast 95% of the time, it is still a very bad idea. For instance, if you do reads while Play Store is updating applications on the background, you’ll notice the slow down and probably an ANR if the read happens on the main thread.

You can easily see this getting more complex when the relationship becomes a list.

There is another problem with these relationships. When the same object shows up in multiple lists, the source of truth becomes a problem. Which data is more correct, the Author that showed up in book search query or the one that was returned from the authors list. When user marks an author as favorite, how do you find all copies of that Author object and update it? These are solvable by all means, just a lot of complexity and easy to get it wrong. And side effects will be showing inconsistent data on the UI, confusing the user.

Last but not least, there is also the problem of updating the data. What happens if I call book.setAuthor() ? Does it go and change the author in the database or just for this book. Even worse, what happens if I call author.books.add(newBook)? Does this go ahead and update the database? You don’t know, you cannot answer this question by looking at it, so yet another mine planted in the codebase.

So how does JSON API fix this? It does not, but it guides you to the correct direction:

  • Data does not come in relationships nested so that you can easily save it to the database as is. Each reference becomes an id reference on the object.
  • Data does not come in relationships nested so you are incentivized to create a view model.
  • To support persistence, all you need is a single saveToModel method that will get the response and save everything in the included array into the database. Each object has its type in the response so this can be an independent code piece that does the work for all responses.

Now you are guided to start the right way, you can continue by creating ViewModels for your UI and fill this ViewModel from the data that was persisted.

For example, for the list of books, it can be something like:

class BookListViewModel {
  List<Book> books;

Now when the PM wants to add author to the results, you change the ViewModel to include the information.

class BookListViewModel {
  List<Book> books;
  Map<String, Author> authors;

Now it is super easy to observe these because there is no depth. For instance, you can observe the Author database for changes and when something is changed, update the BookListViewModel‘s authors map. You can make it generic such that you can have a mechanism to observe a list of (ResourceType, String) tuples and have automagically updating ViewModel classes.

If you need to get the author of a Book, you write the following code:

Book book = ...;
Author author = viewModel.authors.get(book.getAuthorId());

You did it right the first time, you didn’t plant any mines and you can scale this code going forward. There is no room for inconsistencies because it is easy to track objects viewed in the UI.

Yes, you wrote more code to achieve this but I think the benefits outweigh the cost. Plus, it is an easy code to write and can be automated if desired.

Note that JSON API is not the first thing that returns results in this format. Indeed in Path, our API was very similar, returning everything as maps. Also, when I was writing the Architecture Demo for Android Dev Summit 2016, I’ve used a similar architecture on the API. What JSON API does is to put this mentality into a well defined format that can be adopted in a variety of technologies, which is great.

I’ve also created a sample parser project on GitHub that parses JSON API responses as separate entity maps. It is just a sample project so no maven url (maybe one day, when i have more time :)).

Kudos to JSON API people.

  • Never is a strong word, there is always exceptions.

Rewriting Android Priority JobQueue – Lessons Learned

Earlier this year (2016) I’ve decided to rewrite the internals of the Android Priority JobQueue, which is a task queue that I’ve written when I was working at Path to provide a decent offline experience in the app.

Over the 4 years, it has grown organically from a simple task manager to a complex one that allows fine grained control over how background tasks are managed. There were also changes in the Android scene especially the addition of the JobScheduler.

It was getting really hard to improve the JobManager to adapt these changes due to some bad decisions that I made in its earlier development. So I thought it is a good idea to share these as I’ve recently completed the rewrite and feeling much better for the future of the project.

Do not communicate by sharing memory; instead, share memory by communicating

This is the single most important thing in the rewrite and also was the most wrong thing I’ve done in v1. The JobManager is multithreaded by nature since it has to run multiple jobs in parallel. It is intuitive to put shared resources behind locks so that only 1 thread accesses them at a given time. Even though this works well at the beginning, it is very hard to manage especially if you have APIs that would trigger access to these resources. JobManager V1 had some thread lock bugs that were almost impossible to solve. You also need to be careful with memory barriers or mark all necessary fields volatile which is very hard to track.

In V2, I’ve changed this communication entirely to make JobManager single threaded. JobManager gets its own thread which is the only thread that can access shared resources. Jobs that runs on other threads can communicate with the JobManager only via message passing. They cannot access resources. Indeed, they don’t have a way to grab a reference to the shared resource anyways so mistakes cannot be made in the future. Any public API also goes through this message passing, just like Job consumer threads.

This solution is not without its downsides either. There was a bug during development which created a message passing loop between the JobManager and Job consumers which meant JobManager is constantly running. This is a much easier problem to solve by making one item (JobManager) as the master to initiate any conversation and much easier to keep under control compared to deadlocks.

Also, read the Awesome Go Article on Share Memory By Communicating as a background.

If you code needs to do clock related stuff, abstract it out

JobManager provides the ability to delay execution of jobs. Java has built in functionality to defer things or get current time. They work great until you run your tests on a CI server. Your “solid” tests become flaky. Or in other words, they were always flaky, you just didn’t know that. It is only half the story. You also have no way of testing race conditions because you don’t control time, you cannot.

In V2, I’ve abstracted all time related tasks into a helper class. I even wrote lint checks to ensure that the real time is never accessed. This abstraction does not just abstract System.nanotime calls. It also abstracts message queue delay timing or any timer that is used across the codebase.

Of course this introduce the risk of not using real time in tests but this relatively simple abstraction can itself be tested with real time to mitigate this risk.

Think twice and then think again before adding a new API

This is something I learned while working on the Android Framework, seeing all these functionality which we need to support going forward but does not make sense or not well designed for flexibility. JobManager had APIs like this, the worst one being the addJob method which returns a long id that is only unique when composed with the persistent property of the Job. So a persistent and non-persistent job could have the same id. It worked this way because ids were provided by the Job queues which had default implementations but could be swapped by the developer.

API breaking V2 gave the opportunity to clean these and I had fun :). I’ve moved long ids to UUIDs that are assigned when Job is created so that it is easier for the developer to tie things to the job lifecycle w/o relying on a response. The worst part of this story is that I knew it was a bad API when added but added anyways. So don’t do it. No matter what the use case it. Just wait until you have a better solution before implemented whatever functionality requested by the user.

Overall, writing V2 was a fun experience for me to try new things. There are more things that I would like to change but didn’t as there is a balance between providing the most desired API vs backward compatibility. I’m happy with I have right now as I release V2 and I hope you enjoy using it and develop the most responsive apps that work offline.

Go check it out!

RecyclerView Animations Part 2 – Behind The Scenes

This is the second part of a 2 articles series. Please read Part 1 first if you’ve not read it yet.

In the first article, I’ve covered the main idea on how predictive animations run in RecyclerView. There is actually a lot more going on to achieve this simplicity (for the LayoutManager). Here are some important points that you should know about.

RecyclerView keeps some children attached although they have been removed by the LayoutManager. How does it work? Does it invalidate the contract between the LayoutManager and RecyclerView?

Yes it does ‘kind of’ violate the contract with LayoutManager, but:

RecyclerView does keep the View as a child of the ViewGroup but hides it from the LayoutManager. Each time LayoutManager calls a method to access its children, RecyclerView takes into account the hidden Views. Lets look at the example at Part 1 where ‘C’ was being removed from the adapter.

Predictive Animation

While ‘C’ is fading out, if LayoutManager calls getChildCount(), RecyclerView returns 6 although it has 7 children. If LayoutManager calls getChildAt(int), RecyclerView offsets that call properly to skip child ‘C’ (or any hidden children). If LayoutManager calls addView(View, position), RecyclerView offsets the index properly before calling ViewGroup#addView.

When the animation ends, RecyclerView will remove the View and recycle it.

For more details, you can check ChildHelper internal class.

How does RecyclerView handle item positions in the preLayout pass since they don’t match Adapter contents?

This is doable thanks to the specific notify events added to the Adapter. When Adapter dispatches notify** events, RecyclerView records them and requests a layout to apply them. Any events that arrives before the next layout pass will be applied together.

When onLayout is called by the system, RecyclerView does the following:

  1. Reorder update events such that move events are pushed to the end of the list of update ops. Moving move events to the end of the list is a simplification step so I’ll not go into details here. You can check OpReorderer class for details if you are interested.
  2. Process events one by one and update existing ViewHolders’ positions with respect to the update. If a ViewHolder is removed, it is also marked as removed. While doing this, RecyclerView also decides whether the adapter change should be dispatched to the LayoutManager before or after the preLayout step. This decision process is as follows:
    • If it is an add operation, it is deferred because item should not exist in preLayout.
    • If it is an update or remove operation and if it affects existing ViewHolders, it is postponed. If it does not effect existing ViewHolders, it is dispatched to the LayoutManager because RecyclerView cannot resurrect the previous state of the item (because it does not have a ViewHolder that represents the previous state of that Item).
    • If it is a move operation, it is deferred because RecyclerView can fake its location in the pre-layout pass. For example, if item at position 3 moved to position 5, RecyclerView can return the View for position 5 in pre-layout when View for position 3 is asked.
    • RecyclerView rewrites update operations as necessary. For example, if an update or delete operation affects some of the ViewHolders, RecyclerView divides that operation. If an operation should be dispatched to LayoutManager but a deferred operation may affect it, RecyclerView re-orders these operations so that they are still consistent.

    For example, if there is an Add 1 at 3 operation which is deferred followed by a Remove 1 at 5 operation which cannot be deferred, RecyclerView dispatches it to the LayoutManager as Remove 1 at 4. This is done because the original Remove 1 at 5 was notified by the Adapter after Add 1 at 3 so it includes that item. Since RecyclerView did not tell LayoutManager about the Add 1 at 3, it rewrites the remove operation to be consistent.

    This approach makes tracking items dead simple for a LayoutManager. The abstraction between the Adapter and the LayoutManager makes all of this possible, which is why RecyclerView never passes the Adapter to the LayoutManager, instead, provides methods to access Adapter via State and Recycler.

    ViewHolders also have their old position, pre layout position and final adapter positions. When ViewHolder#getPosition is called, they return either preLayout position or final adapter position depending on the current layout state (pre or post). LayoutManager doesn’t need to know about this because it will always be consistent with the previous events that were dispatched to the LayoutManager.

  3. After Adapter updates are processed, RecyclerView saves positions and dimensions of existing Views which will later be used for animations.
  4. RecyclerView calls LayoutManager#onLayoutChildren for the preLayout step. As I’ve mentioned in the first article, LayoutManager runs its regular layout logic. All it has to do is to layout more items for those which are being deleted or changed (LayoutParams#isItemRemoved , LayoutParams#isItemChanged). As a reminder, the deleted or changed item still ‘appears’ in the Adapter API given to the LayoutManager. This way, LayoutManager simply treats it as any other View (adds, measures, positions etc).
  5. After preLayout is complete, RecyclerView records the positions of the Views again and dispatches the remaining Adapter updates to the LayoutManager.
  6. RecyclerView calls LayoutManager’s onLayout again (postLayout). This time, all item positions match the current contents of the Adapter. LayoutManager runs its regular layout logic again.
  7. After post layout is complete, RecyclerView checks positions of Views again and decides which items are added, removed, changed and moved. It ‘hides’ removed Views and for views not added by the LayoutManager, adds them to the RecyclerView (because they should be animated).
  8. Items which require an animation are passed to the ItemAnimator to start their animations. After the animation is complete, Item Animator calls a callback in RecyclerView which removes and recycles the View if it is no longer necessary.

What happens if LayoutManager keeps some internal data structure using item positions?

Everything works… kind of :). Thanks to the re-writing of Adapter updates by the RecyclerView, all LayoutManager has to do is to update its own bookkeeping when one of its adapter data changed callbacks is called due to Adapter changes. RecyclerView ensures that these updates are called at the appropriate time and order.

At any time during a layout, if LayoutManager needs to access the adapter for additional data (some custom API), it can call Recycler#convertPreLayoutPositionToPostLayout to get the item’s Adapter position. For example, GridLayoutManager uses this API to get the span size of items.

What happens if notifyDataSetChanged is called? How do predictive animations run?

They don’t, which is why notifyDataSetChanged should be your last resort. When notifyDataSetChanged is called on the adapter, RecyclerView does not know where items moved so it cannot properly fake getViewForPosition calls. It simply runs animations as a LayoutTransition would do.

I hope this two part series helped you understand how animations work in RecyclerView and why they work this way. Feel free to ask more questions in the comments and I’ll try to update the article with answers.

Disclaimer: After joining the Android Framework Team on March 2014, I spent fair amount of my time working on RecyclerView.

  • Special thanks to Chet for reviewing early versions of this blog post!

RecyclerView Animations Part 1 – How Animations Work

ListView is one of the most popular widgets of the Android Framework. It has many features, yet it is fairly complex and hard to modify. As the UX paradigms evolved and phones got faster, its limitations started to overshadow its feature set.

With Lollipop, the Android team decided to release a new widget that will make writing different collection views much easier with a pluggable architecture. Many different behaviors can be controlled easily by implementing simple contracts to change:

  • how items are laid out
  • animations!
  • item decorations
  • recycling strategy

This great flexibility comes with the additional complexity of a bigger architecture. Also, there are more things to learn.

In this post, I want to deep dive into RecyclerView internals, particularly on how animations work.

On Honeycomb, the Android Framework introduced LayoutTransition, which was a very easy way to animate changes inside a ViewGroup. It works by taking a snapshot of the ViewGroup before and after the layout changes, then creating Animators to move between these two states. This process is fairly similar to what RecyclerView needs to do to animate changes in the adapter.

LayoutTransition example:

LayoutTransirion example

Unfortunately, lists have one major difference which makes LayoutTransitions a bad fit for their animations. Specifically, items in lists are not the same as views in a ViewGroup. This is an important distinction that needs to be understood to handle animations on “items” while using mechanisms that animate the “views” that show the item contents.

In a normal ViewGroup, if a View is newly added to the View hierarchy, it can be treated like a newly added View and thus it can be animated accordingly (e.g. fade in). For collections, it is a bit different. For example, a View for an item may become visible just because an item before it has been removed from the Adapter. In this case, running a fade in animation for the new item would be misleading because it was already in the list though the view is new because the item just entered the viewport. RecyclerView knows if the item is new or not but it does not know where it was if the item is not new. The same case is valid for disappearing Views, RecyclerView does not know where the view went if it is not removed from the Adapter.

LayoutTransition failure for a list:

LayoutTransirion bad example

To overcome this problem, RecyclerView could ask LayoutManager for the previous location of the new View. Although this would work, it would require some bookkeeping on the LayoutManager end and may not be trivial to calculate for more complex LayoutManagers.

The way that RecyclerView handles animating appearing and disappearing items (that is, animating the appearance and disappearance of views that refer to items that were and are still in the list) is by relying on the LayoutManager to handle predictive layout logic. One one hand, the RecyclerView wants to know where views would have been had they been laid out prior to this change. On the other hand, the RecyclerView wants to know where views would be laid out after this change if the LayoutManager went to the trouble of laying out items that are not currently visible.

To make it easy for the LayoutManager to provide this information, RecyclerView uses a two step layout process when there are adapter changes which should be animated. The mechanisms for handling these predictive layout passes are described below.

  • In the first layout pass (preLayout), RecyclerView asks LayoutManager to layout the previous state with the knowledge of the additional information. For the example above, it would be like requesting “Layout items again, btw, ‘C’ has been removed”. The LayoutManager runs its usual layout step but knowing that ‘C’ will be removed, it lays out View(s) to fill the space left by ‘C’.
    The cool part of this contract is that RecyclerView still behaves as if ‘C’ is still in the backing Adapter. For example, when LayoutManager asks for the View for position 2, RecyclerView returns ‘C’ (getViewForPosition(2) == View('C')) and if LayoutManager asks for position 4, RecyclerView returns the View for ‘E’ (although ‘D’ is the 4th item in the Adapter). LayoutParams of the returned View has an isItemRemoved method which LayoutManager can use to check if this is a disappearing item.

  • In the second layout pass (postLayout), RecyclerView asks LayoutManager to re-layout its items. This time, ‘C’ is not in the Adapter anymore. getViewForPosition(2) will return ‘D’ and getViewForPosition(4) will return ‘F’.
    Keep in mind that the backing item for ‘C’ was already removed from the Adapter, but since RecyclerView has the View representation of it, it can behave as if ‘C’ is still there. In other words, RecyclerView does the bookkeeping for the LayoutManager.

Every time onLayoutChildren is called on the LayoutManager, it temporarily detaches all views and lays them out from scratch again. Unchanged Views are returned from the scrap cache so their measurements stay valid, making this relayout fairly cheap and simple.

LinearLayoutManager pre layout result: (pink rectangle marks the area visible to the user)

LinearLayoutManager pre layout

LinearLayoutManager post layout result:

LinearLayoutManager post layout

After these two layout passes, RecyclerView knows where the Views came from so it can run the correct animation.

Predictive Animation

You might ask: The View ‘C’ was not laid out by the LayoutManager, how come it is still visible?

To be clear, ‘C’ was laid out by the LayoutManager in the pre-layout pass because it looked like it was in the Adapter. It is true that ‘C’ was not laid out by the LayoutManager in the post-layout pass because it does not exist in the Adapter anymore. It is also true for the LayoutManager that ‘C’ is not its child anymore but not true for the RecyclerView. When a View is removed by the LayoutManager, if ItemAnimator wants to animate it, RecyclerView keeps it as a child (so that animations can run properly). More details on this in Part2.

Disappearing Items

With these two layout passes, RecyclerView is able to animate new Views properly. But now, there is another problem with Views that are disappearing. Consider the following case where a new item is added to the list, pushing some other items outside the visible area. This is how it would look with LayoutTransitions:

Add Animation Failure

When ‘X’ was added after ‘A’, it pushed ‘F’ outside the screen. Since LayoutManager will not layout ‘F’, LayoutTransition thinks it has been removed from the UI and runs a fade out animation for it. In reality, ‘F’ is still in the adapter but has been pushed out of bounds.

To solve this issue, RecyclerView provides an additional API to LayoutManager to get this information. At the end of a postLayout pass, LayoutManager can call getScrapList to get list of Views which are in this situation (not laid out by the LayoutManager but still present in the Adapter). Then, it lays out these views as well, as if the size of RecyclerView was big enough to show them.

LinearLayoutManager post layout result: (pink rectangle marks the area visible to the user)

LinearLayoutManager post layout

One important detail is that, since these Views are not necessary after their animations are complete, LayoutManager calls addDisappearingView instead of addView. This gives the clue to the RecyclerView that this View should be removed after its animations is complete. RecyclerView also adds the View to the list of hidden views so that it will disappear from LayoutManager’s children list as soon as postLayout method returns. This way, LayoutManager can forget about it.

Predictive Add Animation

Initially, at least for a LinearLayoutManager, you might think that it can calculate where the Views came from or where they went (if disappeared) and thus won’t need a two pass layout calculation. Unfortunately, there are many edge cases when multiple types of adapter changes happen in the same layout pass. In addition to that, for a more complex LayoutManager, it is not always trivial to calculate where an item would be placed (e.g. StaggeredGridLayout). This approach removes all burden from the LayoutManager and it can support proper animations with little effort.

So far, I’ve covered the main idea on how predictive animations run in RecyclerView. There is actually a lot more going on to achieve this simplicity (for the LayoutManager). You can read about how all this works in Part 2 – Behind The Scenes.

Disclaimer: After joining the Android Framework Team on March 2014, I spent fair amount of my time working on RecyclerView.

  • Special thanks to Chet for reviewing early versions of this blog post!

A Recipe for writing responsive REST clients on Android

Android development is easy but making the app resilient is hard.

Apps are developed under perfect conditions. Test phones with few applications running on top of them with a reliable network conditions. When the app is handed off to end users, environment change dramatically. People use their apps everywhere and network connection is very unreliable.

When developers don’t take care of such cases, it results in a sh*tty user experience. In this blog post, I will share my personal architectural choices with library references.
Continue reading

How to Solve LinearAlloc Problem

skip drama

Imagine you’ve been working on your Android app for a while adding new big features. You’ve been developing it on your beautiful ICS phone. New features are almost ready so it is now time to test  them on older devices.

The first time you try installing it on a Gingerbread device, you realize that it does not work. bummer! It does not even install! How the hack did that happen? You run adb logcat and try to reinstall. You see a buch of errors and on top a messages saying

E/dalvikvm( 7815): LinearAlloc exceeded capacity (5242880), last=3906240

You start googling and realize that Android has a 8MB linear alloc limit on Gingerbread devices. You would not think hitting that limit anytime soon but Android has a bug that makes you hit that limit a lot faster if you are using a complex library or your code tree is complex & well(over) abstracted.
Continue reading

Don’t Dress Your Android App with iPhone Clothes

Many companies go with iPhone when they develop the first version of their app and I personally support this decision for various reasons.

  • Developing for 3-4 similar hardwares is a lot more easier than developing for X inconsistent hardware sets.
  • iOS is a far better OS compared to Android 2.x (FYI I think ICS is better than iOS).
  • App Store is known to have better distribution. Users are richer, spend more money etc…
  • Developing for Android requires more resources and takes more time to test.
    Continue reading

The Real Problem with Android Fragmentation

Many people complain about the Android fragmentation, mostly referring to different screen dimensions, densities and android versions. In this post, I will try to mention them and share my biggest complaint.

It is true that writing an app that can handle multiple screen dimensions/densities is harder than supporting 1-2 screen sizes. Yet I don’t think this is very important. first of all, dp is quite a good unit that makes your design easy to manage. In addition to that, c’mon, we’ve been developing websites for various screens for many years. I believe we have developed enough many design guidelines to handle different screen sizes. So, please stop bringing this argument in any other conversation.
Continue reading