https://github.com/eclipse-uprotocol/up-transport-android-java
Java Client Library to connect to the Android implementation of uProtocol
https://github.com/eclipse-uprotocol/up-transport-android-java
android java up-transport uprotocol
Last synced: 4 months ago
JSON representation
Java Client Library to connect to the Android implementation of uProtocol
- Host: GitHub
- URL: https://github.com/eclipse-uprotocol/up-transport-android-java
- Owner: eclipse-uprotocol
- License: apache-2.0
- Created: 2023-05-04T11:57:45.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2024-10-02T01:02:30.000Z (almost 2 years ago)
- Last Synced: 2025-04-12T21:53:29.245Z (over 1 year ago)
- Topics: android, java, up-transport, uprotocol
- Language: Java
- Size: 154 KB
- Stars: 3
- Watchers: 8
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.adoc
- Contributing: CONTRIBUTING.adoc
- License: LICENSE
Awesome Lists containing this project
README
= uProtocol Transport Android Java Library
:toc:
:toclevels: 4
:sectnums:
:source-highlighter: coderay
== Overview
The following is the uProtocol library that implements uTransport defined in https://github.com/eclipse-uprotocol/up-java[uProtocol Java Library] using Android Binder. It also includes some commonly used utilities for error handling.
== Getting Started
=== Importing the Library
If you are using Gradle, add the following to your _build.gradle_ file's dependencies:
[,groovy]
----
android {
dependencies {
implementation 'org.eclipse.uprotocol:up-transport-android-java::0.1.+'
}
}
----
=== 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
[, xml]
----
com.example.core/.UBusService
----
=== Using the Library
==== 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:
[,java]
----
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)
----
[%hardbreaks]
`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
[,xml]
----
...
----
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
[,xml]
----
...
----
Then open connection to uBus using a reactive API below:
[,java]
----
CompletionStage open()
----
When you are done with the `UTransportAndroid` you should close the connection:
[,java]
----
void close()
----
You cannot use other methods until the `UTransportAndroid` is connected. When this happens the `CompletionStage` returned by open() will be completed. You may query the connection status using this method:
[,java]
----
boolean isOpened()
----
==== Sending a UMessage
The method below is used to send messages to consumers:
[,java]
----
CompletionStage send(UMessage message)
----
==== Registering a UListener
In order to start receiving messages, a consumer should register a listener:
[,java]
----
CompletionStage registerListener(UUri sourceFilter, UListener listener)
CompletionStage 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:
[,java]
----
CompletionStage unregisterListener(UUri sourceFilter, UListener listener)
CompletionStage unregisterListener(UUri sourceFilter, UUri sinkFilter, UListener listener)
----
=== 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:
[,bash]
----
gradlew tasks
----
The following outlines some of the standard tasks employed in the development process:
. *clean*: Deletes the build directory.
. *build*: Assembles and tests this project.
. *lintAnalyzeRelease*: Run lint analysis on the release variant.
. *jacocoTestReport*: Generate Jacoco coverage reports.
. *connectedDebugAndroidTest*: Installs and runs the tests for debug on connected devices.
. *publishReleasePublicationToMavenLocal*: Publishes Maven publication 'release' to the local Maven repository.