JSON:API is a widely used specification for modeling client–server API’s. It’s built on top of the JSON notation standard, to make sharing objects with relationships and all other relevant information such as errors, links, and meta data standardized.

However, in Kotlin, it has been poorly covered by libraries that would make the use of JSON:API easier for the developer.

While considering how to make the usage as simple as possible, we decided to go with the annotation processor and code generation approach. The goal was to come up with a set of annotations that would make the bridge between Kotlin classes and JSON:API, without any additional effort.

As will be shown in this article, our JsonApiX library has achieved just that.

JsonApiX is an annotation processor library made on top of the Kotlinx serialization, to make implementing JSON:API specification much easier. With the use of just a few annotations, it generates JSON:API wrappers for the Kotlin classes.

Wrappers are modeled in a way to follow the JSON:API specification format, using the annotated class’s properties to model the data and relationships part. They are serializable, so parsing in both directions is supported.

The library also has a retrofit module, with a converter to support the API implementations.

It was built for Kotlin, so it can be used on all Kotlin based projects such as Android apps and Kotlin multiplatform apps.

Let’s take the example of a simple class called Book.

Book has two simple parameters: name and pageCount.

Every class annotated with @JsonApiX needs to also be annotated with @Serializable , because JsonApiX is leveraging the Kotlinx serialization to serialize and deserialize classes. 

@JsonApiX takes a type parameter, which is one of the mandatory JSON:API parameters, and its value will be used as the value for the key type in the output.

When we annotate a class with the @JsonApiX annotation, the processor will generate the implementations of a number of interfaces, based on the annotated class. They are made to convert it to the JSON:API format and offer a way to parse it. 

Two most important interfaces are shown below.

JsonApiX interface is a root-level wrapper for a class. Data property wraps the primitive attributes of the original class and relationship references. Included array contains the data of the relationships if any are present. Other properties of this interface are optional fields from the JSON:API specification. Every generated implementation is serializable, allowing the serialization and deserialization of all the parameters from the specification.

Along with the wrappers, the library also generates helper functions and extensions to support the serialization/deserialization processes. Aiming to prevent the developers from having to know and use them, we’ve come up with the idea of an adapter. For each annotated class, an adapter implementation will be generated, as a composition of all the operations needed in the serialization/deserialization process. 

Here is the interface we use for the adapter implementations with its most important methods.

To get the type adapter for your specific class, use the generated TypeAdapterFactory class.

Now, let’s extend our model and take a look at how to handle relationships in our classes.

Our Book now has an author and a list of characters. Both of these attributes are classes themselves, so they need to be treated as relationships.

Generated wrappers and adapters will now account for the relationships in serialization and deserialization. No additional work is needed.

Our Book model looks great now, right? However, do all books necessarily have characters? I don’t think so, and I’m speaking from personal experience – as a person who read a couple of physics books while studying.

Let’s make a small change in our Book model and make the characters list nullable.

As I mentioned before, all non-nullable relationships must be present in the included array of the JSON:API input. Otherwise, the deserialization process will fail. 

However, nullable relationships do not suffer the same fate. They will simply be assigned to null if the input is missing their data.

We’ve made our deserialization process with nullable properties in mind, so it’s safe to have nullable attributes, both primitive and relationships. The JSON:API input can be deserialized without their values.

For example, the following JSON:API input:

Will be successfully parsed to a Book instance with characters list assigned to null.

According to the JSON:API specification, each object should have an optional errors array. The following interface is used as a root-level wrapper for JSON:API responses. It contains a nullable errors list.

A single error is modeled to wrap the most common arguments of an error. In the future, we plan to extend the error model with some optional fields, and give the developers an ability to model their custom errors.

When using Retrofit in the event of a network error, a HttpException will be thrown. To extract the Error model from a response, you can use the HttpException.asJsonXHttpException() extension, which will then return a JsonXHttpException, containing the original response as well as the errors list.

JSON:API specification includes resources that are not necessarily a part of the original models. For that reason, JsonApiX provides a way to retrieve the links and meta values from the JSON:API input without including those fields in your model. To achieve this, your model needs to extend the JsonApiModel abstract class.

JsonApiModel is an abstract class which will provide you with getters and setters for links and meta objects.

JsonApiX currently supports retrieving links from the root object, relationships and resource object(data key) from the JSON:API specification. By default, the links model has the following implementation.

And they can be retrieved in the following way.

Developers can define their own custom link models to adapt to their specific requirements. Let’s take this custom Book links model as an example. Every custom links model must extend the Links interface and have a JsonApiXLinks annotation.

In this example, the annotation processor will automatically make the root-links type of a Book class to be BookLinks. 

Developers need to make sure that the type parameter value in JsonApiXLinks matches the one in the JsonApiX annotation of the original model. 

To retrieve them, a generic variant of the rootLinks() method is used.

LinksPlacementStartegy enum is used to determine which links from the whole JSON:API object will be replaced by a custom model. It currently supports ROOT, RELATIONSHIPS and DATA links.

In JSON:API specification, meta is an optional object. Unlike links, it doesn’t have a predefined default model. For that reason, in order to use the meta feature, the developer must define a custom meta model for each class with which he wants to use it.

Let’s take the BookMeta model as an example. Every custom meta model must extend the Meta interface and have a JsonApiXMeta annotation, with its type parameter matching the one from the JsonApiX annotation of the original model.

In this example, the annotation processor will automatically make the meta type of a Book class to be BookMeta. To retrieve a meta object, a generic variant of the meta() method is used.

To enable the Retrofit integration, JsonApiX generates the converter implementation which can be added to the retrofit builder. It takes an instance of TypeAdapterFactory as a parameter.

JsonXConverterFactory converts the input all the way down (or up) to the original model, so there is no need for any additional wrappers in the API service definition.

Making this library was a long and exciting journey for me and my colleagues. We had to overcome many challenges, and I can’t even count how many times I was busting my head for hours, even days, over some parsing issue. 

We give great thanks to the creators of Kotlinx serialization and Kotlin poet, because our work is heavily based on the features of those libraries. However, the journey is still not over, it’s rather just starting. And we have big plans for the future of the library.

Some of the most exciting upgrades we are planning to do are:

We welcome your contributions, so we’ve decided to make this library open-source! Feel free to peek through the code and open pull request.

The Croatian Automobile Club (HAK) oversees and carries out all driving exams in Croatia. To introduce a digital dimension to the whole process, Infinum built an application that helps the examiners track the course of an exam.

The app notes the applicant’s mistakes, exam duration, driving path and records the exam using a third-party WiFi camera connected to the tablet while the app is used.

In this article, we will focus on the camera implementation aspect.

The development process wasn’t free of hurdles. The first significant one was WiFi discovery and connection. We realized that there was no cohesive and understandable API before Android 10 to perform these tasks. Eventually we came up with a solution, but in all honesty, we had a complete mess on our hands.

We had to use dozens of deprecated methods and properties as well as massive methods with a lot of try/catch clauses just to get our app to scan for a camera and connect with one. We were also worried about a deprecation notice saying that the app-initiated WiFi scans are going to be completely removed in future versions. However, there is no need to dive into pre-Android 10 network API in this article.

Somewhere along the road we decided to move the minimum version of the app to Android 10. We could afford to do so, because HAK examiners use only one type of device, and that device was updated to Android 10. This also allowed us to obtain access to WifiNetworkSpecifier API, which helped a great deal.

We discovered some more challenges in the recording feature:

For the recording feature we decided to use a car digital video recorder or a dashcam. The camera is placed on the car’s dashboard or windshield and connected to the app over WiFi.

These are the camera’s features:

The camera connects to the application over WiFi. The user can control the recording through that connection and send some additional commands. Two connections are made with the camera:

When the recording is initiated, the camera records videos and stores them on the SD card. Each recording session is stored in a separate folder for easier navigation and the videos are recorded in multiple 1-minute recordings. Each video has a timestamp and the exam’s ID so that they can be sorted for each exam.

Android 10 introduced a new API to handle in-app WiFi connections. In-app connection here means literaly that. The connection is established while the application is used and then automatically disconnected when the application is closed.

Thanks to the new API, the whole process became much easier to implement.

Let’s dive into it step by step:

WifiNetworkSpecifier is a kind of a query object for available network connections. We specified the SSID (name) of the network we wanted to connect to in its builder.

In this case we had predefined SSID patterns for our dashcams so that’s what we were passing in the variable SSID.

PatternMatcher.PATTERN_PREFIX is a constant that says we will use the value passed in SSID and use it as a prefix for possible access points. Access points that do not start with the SSID value are ignored.

For example:

val ssid = "Dashcam_"

Available networks:

Networks shown by the WiFi connection dialog:

We filtered out all access points that are not a dashcam. Optionally, we could have added a password so the connection is established faster. Otherwise, the dialog asks for password input. In our case the passwords were also predefined, so we used:

setWpa2Passphrase(password)

After specifying the access point, we needed to build a NetworkRequest object with some additional configuration for our connection. First, we set the transport type to TRANSPORT_WIFI, by which we said that the connection would be established over WiFi. We then removed the connection’s internet capability, as our camera and application were communicating peer-to-peer. We finally added the specifier that we had built earlier to NetworkRequest.

With everything set up, let’s move on to requesting a connection using ConnectivityManager.

Since it is a fairly simple procedure, we decided to use ConnectivityManager and define a callback to handle all the outcomes.

After defining a callback we just needed to call connectivityManager.requestNetwork(), passing in the request and the previously defined callback.

A native dialog would pop up showing the available access points that meet the parameters passed to the specifier object. In the following picture there is a dialog showing one of our cameras named “BlackVue HAK 1613”.

In case the connection is lost or not found we needed to unregister the request by calling:

connectivityManager.unregisterNetworkCallback(networkCallback)

With the connection successfully established, let’s dive deeper into the implementation of camera communication.

We have two separate clients communicating with the camera in the application. The first one is a TCP socket used for commands and simple data correspondence. The second one is an HTTP connection client that transfers the camera’s live feed to the application.

Before moving on to the network request callback, we needed a utility interface to propagate connection events to the corresponding view components. Every view component requiring a connection with the camera would be implementing this interface.

In the network callback for requesting a connection, we handled the outcomes of that request:

In addition to notifying the listener about the connection, we also bound the connection to the process. You might notice the canceled flag. We used it so that the user can cancel a connection attempt. The flag can be set from WifiConnectionManager, which is just a wrapper class for all the WiFi-related code. The manager is used on every screen that leverages the WiFi connection.

To account for connection time-out and other methods from WifiConnectionListener, here are other methods from WifiConnectionManager:

This way we have successfully propagated the callback to the screen. The listener covers all the bad cases so we can show the appropriate message or try to connect again if we want to. Maybe we’ll want to try and reconnect if the camera disconnects in the middle of an exam. In that case, we just start the whole process again until we get that onConnectionEstablished callback again.

After establishing the connection and propagating the callback to the caller, there was still some work to do. We had to set up the clients to communicate with the camera over WiFi.

The first client to set up was the dashcam command interface client. We decided to use a third-party library that provides a TCP socket implementation for Android called OkSocket.

The socket is set up in the following block of code:

It creates the socket that connects to a given IP address and port. In our case, these were predefined by the camera manufacturer. The method returns a so-called IConnectionManager object that we could use to check the connection status.

The command’s requests and responses come as a predefined set of bytes. Not to go into details about what each of the bytes represents, those interested can take a look at the IReader and DashcamCommand implementations that serve as a custom mapper for headers and payload in each of our requests and responses.

With the socket and protocol set up, all we needed to do is make a client that would use these implementations to communicate with the camera. In the following section, we are going to go over the most important methods from DashcamClient.

The commands need to be executed one at a time. The client uses a command queue so that all the commands can be kept and executed sequentially. Before executing a command we have to check that the connection is alive and there is no other command executing at the time. After executing a command we use the following method to make sure everything is ready for the next one.

Finally, the following block of code shows how we send commands and receive responses from the camera.

The socket connection adapter handles sending and receiving data from the camera. When the response arrives, it calls the processResponse method shown above. Every command takes a callback action in the constructor, invoked when the response arrives.

The GetSdCardInfo command takes an additional parameter in the callback, showing the SD card storage information.

The client and commands just described are enough to cover all of the camera operations during an exam. They work well even if the connection is lost during the exam because of the command queue that keeps all of the unexecuted commands.

When the connection is lost, the WifiConnectionManager attempts to re-establish connection and the commands are executed afterwards.

The second client we made is called LivestreamManager. It transfers the stream from the camera to the app in real-time. There are 2 use-cases for this feature in our application:

LivestreamManager features:

IP Cam View library offers a series of classes that help with subscribing to the stream and displaying it on screen. Streaming can be heavy on the device’s resources, so we added an observer on the screen lifecycle. That way we can stop streaming when the app is not in the foreground. LivestreamManager implements LifecycleObserver, which means it is tied to the lifecycle events of its host component and can react to them, given that the component implements LifecycleOwner.

Similar to DashcamClient, LivestreamManager uses WifiConnectionManager to handle camera connection. If the camera disconnects, the app will try to re-establish the connection and notify LivestreamManager so it could resume streaming.

Here are some significant code blocks that show how LivestreamManager works.

Stream events are sent to the activity or fragment through the LivestreamListener interface since LivestreamManager is not a UI component. The listener interface handles two possible cases, as can be seen in the following code block.

When the stream is connected and passed to the screen, it is passed as a source to MjpegSurfaceView, which is just a custom view for displaying a video stream. It is also a part of the library that we used to subscribe to the stream.

The sections above explain the technical side of what is needed for successfully recording a driving exam.

These are the key takeaways:

It was a challenging but very educational journey. We implemented a feature that an average Android developer doesn’t see every day. Connecting an application to a camera was not a simple task, considering all the features, commands, streaming, etc. WiFi Network Specifier really saved us some work, because the old network scanning API was very difficult to work with.

We did have to move the minimum Android version to API level 29, but luckily for us this specific client uses only one tablet model and that one has an Android 10 update.

OkSocket and IP Cam View did their part in transferring the data between the application and camera and we took all the measures to keep the connection alive or reconnect if needed.

Thanks to camera integration, the driving examination app now has an extra feature. Exams are recorded and documented through the app, so if there happens to be a complaint about an exam’s result, the examiner, the candidate, and the Croatian Automobile Club now have solid evidence for everything that happened during the exam.

Digitizing the driving evaluation process means less paperwork and more transparency – and hopefully many more great drivers on the road!

Hilt is an Android library that reduces stress levels and stabilizes the blood pressure while using Dagger. If you’ve used Dagger before, we can agree that it has a steep learning curve, a long setup process and often hardly understandable errors.

In some ways, Hilt is a remedy for all three problems.

It’s developed by Google and at the time of writing this blog post, it’s still in the alpha stage. So please check for the latest version before using it in production. It looks very promising! Judging by the official documentation page already being full of examples, we can expect a powerful and stable tool soon. Make sure to check the official documentation.

Hilt uses annotations to generate some parts of the dependency structure that you would normally have to write yourself. For example: @HiltAndroidApp will generate ApplicationComponent, ApplicationModule, ActivityBuilderComponent etc. This annotation is a starter pack solution for Dagger setup.

Since the topic of Hilt has already been covered in the documentation, this post will focus on migrating an example project from Dagger to Hilt, so I will assume that you are already familiar with Dagger.

Note this before we begin: It’s highly recommended that you do the migration all at once. Having both Hilt and Dagger (the old way) in your app will result in large overhead as Dagger and Hilt generate their dependency graphs separately. Also, each of your modules must be included in some Hilt component, or else the application won’t build.

The application component is usually the entry point for Dagger dependency graph. Dependencies that are included here will be available through the whole application. This is an example of an application setup with Dagger.

Along with the Application component, it is common practice to also make an Application context module and Fragment and Activity builder modules for your application.

Then you would make a module with specific dependencies for every fragment or activity and so on.

Well that’s exactly what you can get by using Hilt. All you need to do is to place @HiltAndroidApp annotation above your application class and Hilt will do all the magic for you.

Adding this annotation here will generate:

You might have noticed that you don’t have to use the @ContributesAndroidInjector annotations anymore. So how does the Hilt generated dependency graph know about your entry points? The answer is – @AndroidEntryPoint.

Adding this annotation above any of the entry points will automatically add them to builder components generated by @HiltAndroidApp, making them injection ready. Hilt will also provide a predefined @ActivityContext annotation to inject activity context anywhere you need.

Everything available in the main application graph can now be injected to your entry points. If you need some specific dependencies for your entry point, you need to make a component that will only be available for that entry point. However, including your modules in ApplicationComponent or any of the generated components will work just as well.

@AndroidEntryPoint can be placed above:

Almost every project will have some modules that will provide some dependencies, such as network clients or databases. You can keep your existing modules. All you need to do is to add an @InstallIn annotation to each one.

The@InstallIn annotation takes the component class as a parameter and you can add any of the generated components and even your own component in case you need to restrict access for some dependency. This must be done for every module, otherwise your app won’t build.

@InstallIn can also be used with @EntryPoint annotated classes. While @AndroidEntryPoint will automatically add your class to globally available components, with @EntryPoint you can define the component it will be installed in. This is a way of restricting some dependencies to specific screens or services.

We have already managed to reduce the boilerplate code amount significantly, but there is more of what you can do with it. Hilt offers a handy solution for ViewModel injection in your android apps. Firstly you need to add some additional dependencies to your app-level build.gradle file.

Then you need to add @ViewModelInject to your ViewModel.

And you are all set. Hilt will even go a step further and it will override the default ViewModelProvider factory with the injected ViewModel ‘s so you can use the viewModels property extension to get your ViewModel ‘s.

Hopefully, by going through the steps you can reduce the setup time for dependency injection in your application and make it generally more readable. If you decide to migrate your application to Hilt, I would like to encourage you to keep watching for new updates and changes to Hilt. It is a promising library and plugin, and it could be bringing even more benefits in the future.

View Binding is Google’s new method of referencing views. It generates a binding class for each of your XML layout files, and is used to interact with all views that have an assigned id value in a null-safe and type-safe way.

In comparison to the well-known methods such as Kotlin synthetics, Butterknife and findViewById, it provides a safer and more concise way of handling view interactions inside your views. Before we compare them all side by side, let’s dive in the features of View Binding.

Some of the most relevant benefits of using View Binding are:

On the other hand, there are also some limitations:

View Binding is available since Android Studio 3.6. It has to be enabled in your application module’s build.gradle.

This setting will enable generation of a binding class for every layout XML file in the module on the next build. However, if you would like to skip generating a class for specific layout, the following tag must be added in root element of that layout.

The generated binding class is called ResultProfileBinding. This class has two fields: a TextView called name and a Button conveniently called, well, button. The ImageView in the layout has no ID, so there is no reference to it in the binding class.

If layout includes another layout file with \ tag, a property will be generated, holding the included layout generated view binding. The included layout, same as all other generated views, must have an id tag.

The following code block shows the initialization and usage of the generated View Binding class in activity.

In addition to the described way of initializing, View Binding can also be injected in activities and fragments, using one of the dependency injection libraries such as Dagger. This makes the “view controller” classes even more cohesive and independent from view initializing.

Before View Binding, there was no convenient way to achieve this. In order to inject the View Binding, you need to @Provide it in the module of your activity or fragment.
The following example shows View Binding injection in activity.

In the following sections, I will try to make the case of why developers should start using View Binding by comparing it to other popular methods of handling view interaction: Kotlin synthetics, Butterknife, and the good old findViewById.

The following is an example of referencing and setting a text in TextView using all four methods.

Using View binding requires using an instance of generated binding class, which means there is an additional variable in each view reference. On the other hand, you don’t have to create properties for views that you will be using in your activity, as is the case with Butterknife and findViewById.

Kotlin synthetics definitely wins this one, because an extension is created for each view with id tag and it’s referenced just by the id value.

In terms of the generated code, Butterknife and ViewBinding behave very similarly. Each creates classes which bind views to properties based on the view’s id. The difference is that the Butterknife-generated class is based on the view controller class passed in the initialization, while View Binding is based on the XML layout file.

In the case of Butterknife, this can lead to nullability and safety issues as activities and fragments can inflate more than one different layout. Kotlin synthetics generate an extension. In order to reference the view, it must be inflated.

However, Kotlin synthetics have no way of checking if the right layout is inflated, so referencing a view that is not currently on the screen is allowed and leads to a null pointer exception.

FindViewById approach is easily the winner of this category, as it doesn’t generate any additional code, even though it does require some additional properties and is far from being safe.

View Binding is the only member of this group that ensures existence and the right type of every view for a given layout. This is one of the main advantages of View Binding, as it also works for different configurations of the layout. View Binding must be inflated with the layoutInflater from the screen controller, which means it ensures referencing the right layout.

Butterknife and Kotlin synthetics are not safe in terms of referencing the current layout and this can lead to null pointer exceptions. The same goes for findViewById as it is completely layout-ignorant and uses only the id to reference a view.

Kotlin synthetics work only with Kotlin classes, which is a main disadvantage of this approach as there are still many Java Android developers and projects. Other mentioned approaches work with both Java and Kotlin.

It’s worth noting that View Binding generates Java performance optimized code and outperforms the rest of the group.

View Binding and Butterknife have a lot in common in terms of the idea behind the approach. However, View Binding addresses and successfully solves some of the issues of using Butterknife. That is probably why the official Butterknife Github page recommends switching to View Binding.

Even though it might seem that Kotlin synthetics offers a cleaner way of referencing views, the issues of null and type safety, as well as performance and interoperability issues should be reason enough to go with View Binding instead. As for the findViewById approach, it is legacy and it should stay that way considering all the disadvantages.

When in need of a safe way of interacting with your views, without having to worry about null and type issues, View Binding is definitely the way to go.