Java service integration
Installation · Integration · Sockets · Messages · Provider · Embed
The app receives a scoped client JWT from its authenticated service backend. Only the backend holds URNETWORK_ and provisions clients through POST /network/. The shared integration contract defines new-client allocation, authorized reissue and the credential boundary.
Client setup
The reusable bootstrap is UrSession.java. Use try (var session = new UrSession(false)) for messages or the default constructor for sockets. Close Device work before the AutoCloseable session; its manager remains alive until Device shutdown.
JDK 17+ and Maven are required. The messages POM adds this source directory and defaults urnetwork.sdk. to 0.0.1-dev.0. Install the matching local SDK artifact or pass -Durnetwork.sdk. to Maven; see Messages. From java/, build and check the sibling client program:
cd ../messages
mvn -q compile
mvn -q exec:java -Dexec.args=--versionThe version check needs no client credentials. In that same messages directory, configure the app and print its assigned client identity:
export URNETWORK_ CLIENT_ JWT= 'scoped-client-jwt-from-your-service'
export URNETWORK_ INSTANCE_ ID= 'persisted-installation-uuid'
mvn -q exec:java -Dexec.args=selfThe JWT must contain its assigned client_id. Generate an installation UUID once, save it in installation storage and reuse it; for example, uuidgen generates one on macOS. The program requires both environment variables and does not persist a new UUID for you. Two messaging terminals need distinct client JWTs/client IDs and distinct persisted instance IDs in the same network. Use Messages for live watch/send commands and Sockets for HTTP/TCP/UDP.
Backend allocator
The server-only executable is Allocator.java and pom.xml. JDK 17+ and Maven are required. The server uses java.net.http. and Jackson. The classpath below uses the POSIX separator; use ; on Windows. Run these commands from java/:
mvn -q compile dependency: copy-dependencies
java -cp 'target/ classes: target/ dependency/ *' Allocator --self-test--self-test needs no credentials or network; dependency installation and compilation may download build inputs. It checks first allocation versus reissue, invalid service-user/client-ID arguments, private mapping persistence and response parsing.
Configure the backend process and invoke the allocator with a service-user key supplied internally after your service authenticates that user:
umask 077
mkdir -p /absolute/ path/ to/ private-service-state
chmod 700 /absolute/ path/ to/ private-service-state
export URNETWORK_ CLIENT_ MAP= '/ absolute/ path/ to/ private-service-state/ clients.json'
export URNETWORK_ API_ URL= 'https:// api. bringyour.com'
export URNETWORK_ ROOT_ JWT= 'backend-root-jwt-from-your-secret-store'
java -cp 'target/ classes: target/ dependency/ *' Allocator user:aliceReplace the example state directory with an absolute, service-owned path. URNETWORK_ and URNETWORK_ are required. URNETWORK_ is optional and defaults to the HTTPS origin shown; explicit localhost HTTP is accepted only for a test/mock endpoint. The allocator appends /network/ itself.
user:alice means the authenticated service user alice. The backend constructs this user: key; it is never a URnetwork client ID or an untrusted request field. The allocator accepts exactly one such key, owns the mapping and accepts no caller-selected client ID. A new key omits client_id and source_ from the request; another invocation for the same key reissues only its stored client_id.
An exclusive per-map lock covers provisioning and an atomic private map update. The mapping stores client IDs, not JWTs. On success the allocator writes JSON containing client_id and by_ to stdout. Capture that result inside the authenticated backend and hand only the scoped credential to the authorized app as URNETWORK_; keep tokens out of ordinary logs. See the shared contract for locking, key validation and configuration details.