uProtocol Transport Android Java Library

Table of Contents

• 1. Overview
• 2. Getting Started
  • 2.1. Importing the Library
  • 2.2. Configuring the Library
  • 2.3. Using the Library
    • 2.3.1. Connecting to uTransport
    • 2.3.2. Sending a UMessage
    • 2.3.3. Registering a UListener
  • 2.4. Building the Library

1. Overview

The following is the uProtocol library that implements uTransport defined in uProtocol Java Library using Android Binder. It also includes some commonly used utilities for error handling.

2. Getting Started

2.1. Importing the Library

If you are using Gradle, add the following to your build.gradle file’s dependencies:

android {
    dependencies {
        implementation 'org.eclipse.uprotocol:up-transport-android-java::0.1.+'
    }
}

2.2. Configuring the Library

UTransprtAndroid, by default, establishes a connection to uBus service that is integrated into the system as part of "org.eclipse.uprotocol.core" package.

If a service that implements IUBus.aidl interface is integrated in a different package, you should configure the library by specifying that component or just that package.

Example: config.xml

<resources>
    <string name="config_UBusService" translatable="false">com.example.core/.UBusService</string>
</resources>

2.3. Using the Library

2.3.1. Connecting to uTransport

Before using the UTransportAndroid APIs, a uE must create an instance and open connection to uBus.

First create an instance with one of static factory methods:

static UTransportAndroid create(Context context, Handler handler)
static UTransportAndroid create(Context context, Executor executor)
static UTransportAndroid create(Context context, UUri source, Handler handler)
static UTransportAndroid create(Context context, UUri source, Executor executor)

context is an application context.
source is an address of uE containing its name and major version (MUST match the meta data in the manifest).
handler is a handler on which callbacks should execute, or null to execute on the application’s main thread.
executor is an executor on which callbacks should execute, or null to execute on the application’s main thread executor.

Note	Every Android uE MUST declare its id and major version in the manifest.

For the example below you may use any create(…​) factory method.

Example 1: Single Android uE

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="org.eclipse.uprotocol.example.client">
    ...
    <application android:label="@string/app_name" ...>
        <meta-data
            android:name="uprotocol.entity.id"
            android:value="100" />
        <meta-data
            android:name="uprotocol.entity.version"
            android:value="1" />

        <activity
            android:name=".ExampleActivity">
        </activity>
    </application>
</manifest>

For the next example you should create a separate instance of UTransportAndroid for each uE using create(…​, UUri source,…​) factory method.

Example 2: Several Android uEs bundled together in APK

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="org.eclipse.uprotocol.example.service.lighting">
    ...
    <application android:label="@string/app_name">
        <service
            android:name=".ExteriorLightingService"
            ... >
            <meta-data
                android:name="uprotocol.entity.id"
                android:value="100" />
            <meta-data
                android:name="uprotocol.entity.version"
                android:value="1" />
        </service>

        <service
            android:name=".InteriorLightingService"
            ... >
            <meta-data
                android:name="uprotocol.entity.id"
                android:value="101" />
            <meta-data
                android:name="uprotocol.entity.version"
                android:value="1" />
        </service>
    </application>
</manifest>

Then open connection to uBus using a reactive API below:

CompletionStage<UStatus> open()

When you are done with the UTransportAndroid you should close the connection:

void close()

You cannot use other methods until the UTransportAndroid is connected. When this happens the CompletionStage<UStatus> returned by open() will be completed. You may query the connection status using this method:

boolean isOpened()

2.3.2. Sending a UMessage

The method below is used to send messages to consumers:

CompletionStage<UStatus> send(UMessage message)

2.3.3. Registering a UListener

In order to start receiving messages, a consumer should register a listener:

CompletionStage<UStatus> registerListener(UUri sourceFilter, UListener listener)
CompletionStage<UStatus> registerListener(UUri sourceFilter, UUri sinkFilter, UListener listener)

A consumer can use the same listener for multiple filters, or register different listeners with the same filters.

To unregister a listener from receiving messages:

CompletionStage<UStatus> unregisterListener(UUri sourceFilter, UListener listener)
CompletionStage<UStatus> unregisterListener(UUri sourceFilter, UUri sinkFilter, UListener listener)

2.4. Building the Library

The Android Gradle Plugin provides several standard tasks that are commonly used in Android projects. To view the complete list, you can use the following command:

gradlew tasks

The following outlines some of the standard tasks employed in the development process:

1. clean: Deletes the build directory.

2. build: Assembles and tests this project.

3. lintAnalyzeRelease: Run lint analysis on the release variant.

4. jacocoTestReport: Generate Jacoco coverage reports.

5. connectedDebugAndroidTest: Installs and runs the tests for debug on connected devices.

6. publishReleasePublicationToMavenLocal: Publishes Maven publication 'release' to the local Maven repository.