DEV Community: Shai Almog

Lies, Damn Lies and Benchmarks

Shai Almog — Fri, 18 Sep 2026 17:04:18 +0000

There's an old joke about three kinds of lies: lies, damn lies, and benchmarks. Codename One did very well in our benchmarks. But were they accurate? Were they representative?

What is Codename One? Codename One is an open-source framework for building native iOS, Android, desktop, and web apps from a single Java or Kotlin codebase. Learn more at codenameone.com.

Performance is the fitted sheet of programming. Just when you get the damn corner into place, the rest of the bed is a complete mess.

This week we made a concentrated effort to get a few more corners into place, and got a lot done. There's still work ahead that we'll discuss next week, but it's getting to a point where I feel confident saying Codename One is pretty fast. Not the best (yet), but fast.

The trouble with a good benchmark score is how little it can tell you about the next operation. Our map was fast at finding keys that existed. Asking for missing keys exposed a lookup that could walk hundreds of thousands of slots. A collector setting that looked reasonable for a larger process let a small process retain garbage without buying measurable throughput. A rendering benchmark had no reason to notice that a switch generated blurred artwork before anyone asked to paint it.

Those costs meet in an application. Opening a screen constructs styles and lays out components. Loading its data fills maps and boxes numbers. Displaying images creates results worth caching, until memory gets tight. We worked through those layers together because making one loop faster does not tell us whether the screen starts sooner or leaves less memory behind.

Last week, builders let us take responsibility for native integration that used to belong in each application's platform project. This week we are using the same reach inside the runtime: changing collection, object representation, UI internals, and generated JavaScript while keeping the application code in Java.

Two major additions let users take their work further. Native drag and drop lets them move files and content between your application and other apps. Cross-device continuity lets them continue a task on another device, as well as recover it after the OS closes the process. Both now have Java APIs in Codename One.

Coming up: less waiting, more room, and work that travels

Tomorrow's What Go Taught Us About Java Garbage Collection asks why a collector should keep memory that buys no speed, and how to stop a cache flush from making you decode every image again. On Sunday, Faster Maps: Chasing Swiss Speed follows our comparison with Go's map design into faster lookups and numbers that no longer need their own heap objects.

Monday brings Faster Starts, Less JavaScript Overhead. A margin calculation was waiting on AppKit, and a blocking method was making unrelated JavaScript calls suspend. Tuesday's Native Drag and Drop Meets Cross-Device Continuity puts the new integration APIs to work: offer a document to another app, resume a draft on another device, and keep account changes from restoring the wrong user's screen.

On Wednesday, Javadoc That Feels Like Your Website shows how to give your own Java API reference the site's layout and search. We finish on September 17 with Android 17 Without the Last-Minute Scramble: catching SDK changes early, letting the OS handle location consent, and removing more security-sensitive glue from application code.

Less garbage, more room for your app

As Java developers, HotSpot is the standard we tend to reach for. Comparing ParparVM with Go made me look beyond that familiar reference. My first suspicion was stack allocation: perhaps Go was simply creating fewer heap objects, the same sort of overhead that makes Valhalla's value objects interesting.

But Go's collection policy mattered too. ParparVM is an AOT runtime with a closed-world build, so we can experiment with allocation and collection together. We translate the application to C, own its object representation, and know what has to cooperate with the collector.

We started with the allowance for new garbage. Letting more accumulate can save collection work, but that extra memory should buy something.

In our trigger experiment, it bought very little. The stock 24 MB allocation floor was associated with 98 MB of loaded resident memory. Sweeping through lower trigger settings left throughput and p99 within run-to-run noise. A subsequent lower-floor configuration brought loaded RSS down to 38 MB. PR #5717 records the experiment.

Resident memory at each trigger setting. The final tuned configuration reached 38 MB; RSS includes memory outside the Java heap.

The live-set estimate was missing live objects

The tempting next step was to derive the floor from the amount of live data. That would let a small process collect sooner and a larger one keep more allocation headroom.

We tried it and backed it out. The sweep counters described retired pages, not the whole live population. Partial pages and the pages a mutator was still allocating into were outside that count; large objects had another path. Feeding that number into a proportional policy gave the policy an incomplete picture. One attempt retained an old live-set estimate long enough to suppress the sweeps needed to return pages to the OS.

The merged code lets a deployment choose its minimum instead:

#ifndef CN1_BIBOP_GC_MIN_TRIGGER_BYTES
#define CN1_BIBOP_GC_MIN_TRIGGER_BYTES CN1_BIBOP_GC_TRIGGER_BYTES
#endif

A runtime build can select the smaller floor. We kept the stock default while working through more workloads and the incomplete live-set counters.

Parallel marking is the other part of the investigation. In the recorded allocation loop, ParparVM's median and p99 matched Go. The worst pause still favored Go: about 20 ms, against 0.3 to 0.9 seconds with four ParparVM markers and 2.2 to 3.3 seconds with one. Parallel marking remains experimental. Allocation threads can help drain marking work instead of merely waiting at the run-ahead cap, but that assistance belongs to the parallel path, not the unchanged serial default.

A useful image should survive longer than a cold one

Collecting sooner cannot help if the collector treats disposable cached data as permanently reachable. ParparVM's old WeakReference held its referent in a field that the translator marked like any strong field. As long as the wrapper survived, so did the supposedly weak object.

The iOS port approximated soft references with a strong-reference table and a low-memory warning. flushSoftRefMap() replaced the table when pressure arrived. That could free a batch of cached artwork, but it also discarded the image the user was about to scroll back to.

PR #5732 gives the collector real weak and soft references. It discovers the referent as a special edge, decides whether a soft referent should survive, then clears references eligible for reclamation. Soft retention uses the age since the last successful get(). Repeatedly used images tend to stay recent; cold ones lose priority.

The application-facing contract looks like this on the updated ParparVM path:

final class PreviewCache {
    private SoftReference<Image> cached;

    Image get() throws IOException {
        Image result = cached == null ? null : cached.get();
        if (result == null) {
            result = Image.createImage("/preview.png");
            cached = new SoftReference<Image>(result);
        }
        return result;
    }
}

This excerpt uses java.lang.ref.SoftReference, com.codename1.ui.Image, and java.io.IOException, and assumes one calling thread. The local result keeps a successful read strongly reachable while it is used. A miss reconstructs the image. A soft cache is appropriate only when that reconstruction is possible.

The difficult case is a read during collection. A thread can call get() after the collector has scanned its roots. Freeing the referent without noticing that read would hand Java code a dangling native pointer. Reference reads now participate in the marking barrier, and the collector drains new work before deciding it can sweep.

In the simulated 160 MB budget test, ranked retention produced a 97.44% hit rate at 82.1 MB, compared with 87.99% at 91.0 MB for clearing on pressure. The next step is moving the iOS cache table and framework call sites onto the new reference machinery, then measuring the effect on real screens.

The collector and cache article follows both experiments in detail. Lowering garbage headroom and retaining useful cached results address different sides of the same memory budget.

Chasing Swiss speed without changing your Java maps

Our open-addressed HashMap stores entries in arrays. A key's hash selects its first slot. If that slot is occupied by another key, the map probes elsewhere until it finds the key or an empty slot.

Dense integer keys happened to make the first probe look excellent. Integer hashes preserve the value, and the usual h ^= h >>> 16 spread leaves small integers near their original positions. Insert consecutive integers starting at zero and occupied slots form a long run. A successful lookup often lands directly on its key. A missing key entering that run must walk to its end under linear probing. Tombstones left by deletion cannot terminate the search either.

At 100,000 entries, the measured miss averaged 16,742 probes. At a million entries, it averaged 222,721. Hits stayed at one probe. A benchmark dominated by hits had almost nothing to say about this failure.

Preserve the first probe and change what follows

Scrambling every hash fixed the misses, but made dense construction and scans 1.8 to 2.2 times slower in the measured cases. We wanted to keep the locality of that first slot.

PR #5722 keeps the first probe and changes the collision sequence using the recurrence associated with CPython's dictionary probing:

static int cn1NextSlot(int i, int perturb, int mask) {
    return ((i << 2) + i + 1 + perturb) & mask;
}

The caller shifts the unsigned perturbation right by five bits between probes. As those hash bits feed the recurrence, a collision can escape the occupied run. Once the perturbation reaches zero, the recurrence still visits the power-of-two table. Lookup, insertion, growth, and deletion have to agree on that sequence.

Workload	Before	After
Mean probes per miss, 100,000 entries	16,742	1.53
Three million calls in the miss-heavy workload	32,698 ms	44.9 ms
String-key workload	33.6 ms	25.5 ms
Large table with random hits	26.6 ms	33.3 ms

The last row got worse. That tradeoff belongs beside the spectacular miss result, because the change did not make every map operation hundreds of times faster.

Go's Swiss maps were another useful comparison. ParparVM already keeps compact metadata separate from its key and value arrays, so we were closer in structure than a map built around an allocation per entry. The merged lookup remains scalar perturbed probing. The SIMD-related improvement is on the string-key path: unequal cached hashes reject a match early, and compatible UTF-16 storage goes through native memcmp, where the platform can use optimized vector comparisons. Our probe sequence and string comparisons address different stages of the lookup. The timings here compare the old and new ParparVM implementations.

Hashtable also moves away from an Entry allocation per mapping. IdentityHashMap needed a different fix: ParparVM's identity hash comes from an aligned address, so copying an indexing expression suited to HotSpot's already-scrambled identity hashes left too many zero low bits. Folding high bits down improved its measured distribution.

A compact table can still be full of little allocations

A JSON parser filling a map may allocate a wrapper for every number. Our earlier performance work removed much of that cost for Integer. PR #5735 extends the representation to Short, Character, Float, Long, and Double.

Aligned object addresses leave three low bits free in this 64-bit runtime. The collector's root scan already distinguishes words with those bits set from ordinary object pointers. We use them as a type tag and put the value in the remaining 61 bits. The map slot contains the number's representation directly, instead of a pointer to a separate wrapper.

Long small = Long.valueOf(42L);             // Tagged on ParparVM
Long large = Long.valueOf(Long.MAX_VALUE); // Heap fallback
Double exact = Double.valueOf(12.5);       // Tagged
Double fraction = Double.valueOf(0.1);     // Heap fallback

Short, Character, and Float fit across their full ranges. Long fits from -2^60 through 2^60 - 1. Double fits when its low three mantissa bits are clear. Byte and Boolean already have bounded caches. Use equals() for value equality; application code should not infer identity from the runtime's allocation choices.

The JSON-like allocation census fell from 24.02 boxed allocations per map to 5.24. That is work the collector never has to do. This extends our “poor man's Valhalla” work: put a known wrapper value directly into its reference word. The tag travels with it, including when that word lives in a heap collection. Long and Double keep a heap fallback for values that do not fit.

The maps and boxing article covers the coverage measurements and dispatch hazards. A type tag must select the right hashCode and equals implementation. Reusing the Integer fast path for every tag would produce a fast, incorrect map.

Faster starts begin with work your app never needed

Before the first frame, a screen asks a lot of components how big they are. Padding and margin conversion needs the screen scale. Our native Mac path synchronously asked AppKit which screen contained the window, even though the answer usually had not changed since the previous component asked.

PR #5686 publishes screen identity and scale together when the window is created or moves. Layout reads that state atomically. Publishing the pair together also prevents a reader from combining one screen with another screen's scale.

The old query accounted for 35 ms of blocked event-dispatch-thread time in the recorded startup profile. Installing a window observer added another synchronous wait even though the caller needed no return value. That path accounted for 37 ms. The Mac profile gave us two specific waits to remove from startup.

The same profile found an uncontended lock announcing that it was about to park before trying to acquire its mutex. That announcement could wait on a GC handshake. The runtime now tries the lock first and enters the park protocol when it actually has to wait.

Layout was doing work that belonged to painting

UIManager scanned the whole theme table to find dark variants for each distinct UIID. We now build an index once per theme generation. First-use dark-variant lookup in the benchmark fell from 111,955 ns to 17,378 ns. The index is invalidated when a new theme changes the answer.

Switch.getPreferredSize() had a more surprising cost: generating switch artwork, including a Gaussian blur. A layout query could pay that cost for a component that was never painted. Preferred size now comes from the same dimensions used by the drawing code; generating the pixels waits until they are needed.

The Metal path also avoids taking each picture back through the CPU and retaining a decoded EncodedImage copy beside the texture. Rounded corners can be drawn in the shader. Removing an image representation saves both its construction cost and the memory it would occupy after startup.

JavaScript was preparing to suspend methods that could not block

The web compiler had a similar problem with an overly broad assumption. A Java method that might block becomes a JavaScript generator so execution can yield and later resume. Our analysis used the method name and descriptor without distinguishing its receiver class.

Consider these two unrelated classes:

final class WaitingTask {
    void run() throws InterruptedException {
        Thread.sleep(10);
    }
}

final class CounterTask {
    private int count;
    void run() {
        count++;
    }
}

A call on CounterTask cannot reach WaitingTask.run(). But treating run() as one blocking signature made unrelated calls suspension points, then spread that property into their callers.

PR #5755 reuses the receiver types already computed by reachability analysis. It considers implementations that can actually receive the call. Unresolved dispatch stays conservative, and analysis and code generation share the same model so they agree about where yield* is legal.

Generated sample output	Before	After
`yield*` sites	54,549	40,741
Generator methods	13,068	11,044
Bundle size	8,089,807 bytes	7,993,916 bytes

Yield sites fell 25.3% while bundle size fell only 1.2%. Counting bytes would barely notice the change in dispatch. Node throughput measurements found gains in several workloads, but iteratorWalk took 13.7% longer, with no established cause yet. That is on the list for further investigation.

The native and JavaScript performance article follows these paths and their tests. The common question is whether an operation needs to wait at all, before trying to make its waiting machinery faster.

Cross-device continuity: pick up where you left off

Start writing on your phone and continue on your tablet. Reopen an app after the OS reclaimed its process and return to the draft you were editing. Cross-device continuity lets an application preserve the task the user cares about, instead of making the current process its only home.

A Form saved in a field cannot do that. The field disappears with the process, and another device cannot reconstruct a screen from an object in the first device's memory. It needs a description of the work.

PR #5663 adds com.codename1.continuity. It saves application state and the router stack as a checkpoint that a new process can reconstruct. A route identifies the screen; a StateProvider supplies the data needed to resume the work. For a draft editor, that can be as small as the text:

Continuity.setStateProvider(new StateProvider() {
    public Map<String, Object> saveState() {
        Map<String, Object> state = new HashMap<String, Object>();
        state.put("draft", draftField.getText());
        return state;
    }

    public void restoreState(Map<String, Object> state) {
        Object draft = state.get("draft");
        draftField.setText(draft instanceof String ? (String) draft : "");
    }
});

Here draftField is the application's TextArea. Registering the provider enables continuity. Navigation schedules checkpoints; edits can call Continuity.checkpoint(). Keep the payload small, exclude credentials, and decide whether sensitive drafts belong in it.

Restoration happens after the application knows which account is active:

// Run after authentication and route registration.
if (!Continuity.restore()) {
    Navigation.navigate("/home");
}

Apple Handoff can offer the activity to another signed-in device. An application-owned StateRelay can carry state through your existing accounts and server, including across Android, Apple devices, and a browser. Codename One does not operate that relay or choose its account-isolation policy. iCloud key-value sync is a separate package with its own entitlement requirement.

Native drag and drop: take it outside your app

Drag a report into another application. Drop a file into your own import screen. Offer a selection as formatted HTML to an editor or as plain text to an application that only wants the words. These are operating-system drag sessions, with a destination outside your form.

PR #5662 adds that native drag and drop beside our existing lightweight API. In-form dragging still works as before. The new API connects components to the OS drag session using ClipboardContent, so the same representations that work for copy and paste can be offered to a drag receiver.

Label file = new Label("report.pdf");
file.setNativeDragOperation(NativeDragOperation.createFileDrag(paths));

inbox.setNativeDropTarget(true);
inbox.setAcceptedDropMimeTypes(ClipboardContent.MIME_FILE);
inbox.addNativeDropListener(event -> {
    String[] received = ((NativeDropEvent) event).getFiles();
    if (received != null) {
        queueImport(received);
    }
});

This excerpt assumes existing export paths, a receiving component named inbox, and an application queueImport that validates files and moves expensive parsing off the event dispatch thread. MIME acceptance is not a trust decision.

Provider timing depends on the port. JavaSE can request the representation lazily. Android assembles complete ClipData before starting the drag, so every provider runs then. iOS resolves file lists at drag start to count the items. Keep providers cheap enough for that moment, or prepare and cache an expensive export beforehand. Canceling a drag does not guarantee that its data was never generated.

The initial implementation covers JavaSE, Android, and UIKit ports, with cross-application behavior on Android, iPadOS, and Mac Catalyst. iPhone has a narrower interaction model. Native AppKit, Windows, Linux, and JavaScript do not implement this native-drag path yet. Check NativeDragAndDrop.isSupported() before relying on it.

The native drag and drop and continuity article includes the platform matrix, callback threading, and logout sequence. A received checkpoint must still pass the current account's authorization checks; a completed move must be confirmed before deleting the source. Moving work should not mean losing ownership of it.

Give your Javadoc the website it deserves

We kept improving the developer guide, but the API reference still carried standard Javadoc's layout and stylesheet into a wrapper inside our site. Search and dark mode made that separation particularly obvious.

PR #5743 changes what the doclet emits. Javadoc supplies the Java API model and documentation trees. The new maven/javadoc-hugo-doclet module writes Hugo content with structured front matter for signatures and members. Hugo renders it using the site's own templates and Markdown renderer.

The tooling uses Java 25 in a separate module from the Java 8 build. Markdown documentation comments themselves arrived in JDK 23. The doclet preserves their prose for Hugo and extracts recognized sections such as parameters and returns into member data. We still generate the standard javadocs.zip archive from the same sources.

A live site capture from September 10. API methods now appear in website search, grouped by type. The full developer guide retains its own navigation and browser search rather than joining this index.

This is reusable source for Java developers who want their own site generator to own the API pages. The doclet module, Hugo layouts, and build integration are available in the repository. You still need to adapt the templates and URL conventions to your site.

The migration also checked 2,272 pages and 29,583 fragments against the old output. A prettier member page is not much use if years of links to that member stop working. The doclet article includes a complete sample, build commands, and the anchor defects that parity testing caught.

Android 17 without the last-minute scramble

PR #5731 adds API 37 compilation checks and generated-application assembly. This matters before changing the default target SDK: compiling against the old platform cannot tell us which referenced classes the new one has removed.

The check compiles the same port sources against both platform jars and compares the errors. It removes duplicate android.jar entries so an old jar cannot silently supply a symbol missing from the new platform. A fault-injection test using removed fingerprint APIs proved that the check catches the failure it was designed to find.

Builder assumptions needed attention too. Platform names such as android-37.2 are no longer integer suffixes. Stripping punctuation would turn 37.2 into 372, which passes minimum-version checks for completely the wrong reason. The builder now extracts the major level correctly and uses the SDK manager belonging to the selected SDK root. The normal SDK floor remains 36 while this preparation continues.

Ask for location at the moment the user needs it

PR #5738 adds the Android 17 system location button, with an ordinary Codename One button and existing permission flow on older platforms:

LocationButton location = new LocationButton(
        LocationButton.TEXT_USE_PRECISE_LOCATION);
location.addLocationSharedListener(fix -> {
    if (fix != null) {
        searchNearby(fix.getLatitude(), fix.getLongitude());
    }
});
form.add(location);

searchNearby belongs to the application. Declined permission or an unavailable result can produce null. The component exposes isSystemRendered() so an application can verify which path is active.

The OS draws the supported control into a hosted surface and ties the request to a visible user action and a session-scoped location grant. The implementation uses the platform session API through reflection, avoiding an AndroidX dependency that would force a newer Android Gradle Plugin on every application using the button. The builder adds USE_LOCATION_BUTTON when it finds the component; the separate cloud-builder mirror still needs to be present in the builder serving the app.

The PR exercised the system button, a human tap, consent, and a returned location on an Android 17 emulator, with fallback on API 36. The regular screenshot suite still runs on API 36; broader API 37 coverage is part of the remaining migration work. The Android and security article separates those checks and links the current platform guidance.

Stop making each application parse its own key armor

PR #5707 adds PublicKey.fromPem and PrivateKey.fromPem for text or file bytes:

PublicKey publicKey = PublicKey.fromPem(
        Util.readInputStream(publicStream));
PrivateKey privateKey = PrivateKey.fromPem(
        Util.readInputStream(privateStream));

These use the Codename One security classes and the application's existing input streams. The parser strips the armor, decodes Base64, validates a complete DER element, and recognizes the key container. Supported PKCS#1 RSA and SEC1 EC inputs are rewrapped into the container expected downstream. Encrypted keys, certificates, wrong public/private direction, and truncated or trailing DER are rejected with an explanation.

That removes format handling from application glue code. It does not decide whether a public key is trusted or where a private key should be stored.

Removing a task is part of ending a session

PR #5746 adds CN.exitAndClearTask(). On Android it removes the task from recents before following the process-exit path. Killing the process alone could leave the task in the switcher.

For an application using continuity, the framework calls at logout are:

Continuity.clear();
Continuity.disable();
// Finish account cleanup and any asynchronous sign-out work before this call.
CN.exitAndClearTask();

Clearing saved state without disabling continuity leaves a route for an arriving activity to restore it again. Removing the task without revoking credentials leaves a session alive. These calls handle restoration and task lifecycle; your application still owns credential revocation and account data. Other ports retain their existing exit behavior.

Less runtime work, fewer places to get security wrong

The collector and reference changes let us distinguish garbage from useful cached data. The map changes fix a pathological search and remove wrapper allocations from its contents. Style construction, layout, and JavaScript generation now do less work before the application can get on with its own job. There are still regressions to investigate and cache integrations to finish, which is why we are continuing the performance work next week.

Continuity and native drag and drop expand what the user can do with that application. The doclet puts the API contracts where site search can find them. Android preparation moves platform breakage into our checks before a mandatory migration moves it into a customer's release schedule.

An application can use ordinary Java references while Codename One's runtime handles the race between a cache read and collection. It can read a PEM key without maintaining its own DER conversion. It can ask for a location through the OS consent surface and explicitly shut down restoration when an account signs out.

Secure-by-default programming depends on those details. We maintain the API, translator, runtime, and builders together so app teams do not each have to rediscover them in native code. The application's authorization and data rules still belong to its developers. The shared implementation should leave them more time to get those rules right.

Pick One Contact Without Asking for the Address Book

Shai Almog — Wed, 16 Sep 2026 17:39:18 +0000

A share screen needs one phone number. A delivery form needs one address. Neither feature needs a database of everybody the user knows.

What is Codename One? Codename One is an open-source framework for building native iOS, Android, desktop, and web apps from a single Java or Kotlin codebase. Learn more at codenameone.com.

PR #5680 adds ContactPicker, a permission-free path that returns only the contacts and fields the user selects. It uses the Android 17 system Contact Picker, a narrow fallback on older Android versions, and Apple's CNContactPickerViewController on iOS.

For VoIP, VPN, native Mac and Windows work, OTP, billing, and the platform-watch process that found this gap, read the weekly overview.

Ask for the fields the screen needs

The basic flow declares a field mask and opens the system picker:

ContactPicker picker = new ContactPicker();
picker.setRequestedFields(
        ContactPicker.NAME |
        ContactPicker.PHONE);

picker.pick(event -> {
    Contact[] selected = ContactPicker.getPickedContacts(event);
    if (selected.length == 0) {
        return;
    }

    Contact contact = selected[0];
    recipientName.setText(contact.getDisplayName());
    recipientPhone.setText(contact.getPrimaryPhoneNumber());
});

Available fields include name, phone, email, address, photo, birthday, and website. Requesting a field describes the desired result. A platform may return less because the contact lacks it or because its picker does not support every combination.

The returned Contact is a snapshot. Copy the values the feature needs while handling the result. Its picker identifier is not a token for later unrestricted access through ContactsManager.

Platform differences remain visible

On Android 17, ACTION_PICK_CONTACTS supports the new privacy-focused system surface. Older Android releases use ACTION_PICK for one contact without requesting broad contacts permission. The fallback cannot promise every requested field or multiple selection.

iOS presents CNContactPickerViewController. This path does not need NSContactsUsageDescription because the user chooses the data in a system-owned interface. The simulator supplies a deterministic picker for UI and cancellation tests.

Other ports report the capability as unsupported. Application code should keep its manual-entry path:

if (ContactPicker.isSupported()) {
    chooseContactButton.setEnabled(true);
} else {
    chooseContactButton.setVisible(false);
    manualEntry.setVisible(true);
}

Multi-selection and “require all fields” are requests, not portable guarantees. A form should treat a missing phone number as a normal result and let the user enter it.

getDisplayName() may synthesize a useful label when the native contact has no display string. Use the given and family name fields when the distinction matters.

Permission detection had to become more precise

The builder previously treated references near the contacts API as a reason to add broad address-book access. That would defeat the point of the new picker.

Feature scanning now distinguishes ContactPicker, contact value objects, and direct broad-reader calls. Using Contact as the picker result does not add permission by association. Calling a Display method that reads the address book still does.

The builder is part of the API design. A permission-safe Java surface is incomplete if packaging adds a permission the application never asked for.

Privacy is also product design

Broad contact access asks users to trust the application with relationships unrelated to the task in front of them. A system picker changes that conversation. The user sees the operating system's interface, chooses a specific person, and returns only the relevant snapshot.

The security gain is concrete, but the product flow improves too. There is no pre-permission explanation, denial recovery, settings detour, or empty contact screen after a refusal. Manual entry remains available when selection is unsupported or the desired field is missing.

This week's OTP support follows the same rule by accepting one code without reading the inbox. Call and VPN packages activate only their own native services. Builders inspect what the application uses and keep everything else out.

Secure defaults grow through choices this ordinary. The easiest API asks for the smallest useful slice of data. A developer must make a deliberate choice to widen access.

We Stopped Waiting for Platform Changes to Find Us

Shai Almog — Tue, 15 Sep 2026 17:40:13 +0000

For years, our warning system for Apple and Google changes was a developer whose build failed first. The community gave us excellent reports, but the sequence was backwards. A platform owner announced a deadline, time passed, an application hit the change, and only then did we trace it into the builder.

What is Codename One? Codename One is an open-source framework for building native iOS, Android, desktop, and web apps from a single Java or Kotlin codebase. Learn more at codenameone.com.

This week we started a daily scheduled Codex task that reads official notices and checks them against Codename One. Its first useful results include Android 16 back handling in PR #5673 and the permission-safe Contact Picker in PR #5680.

For the rest of the release, read the weekly overview. The Contact Picker has a separate code-focused article.

A notice is the start of an investigation

Scheduled browsing alone would create noise. Platform pages change wording, policies overlap, and a requirement may already be handled in a builder branch that application code never sees. The task must connect the notice to an artifact we produce.

We require a primary source, an applicability test, and a concrete Codename One producer before filing work. A release-note headline is not enough. For native libraries, a Gradle setting is not enough either; the packaged binary may need inspection.

The scheduled task does not merge code or declare support from a search result. It narrows the distance between a platform announcement and an evidence-backed change.

Android 16 changed the Back contract

Applications targeting Android 16 no longer receive the old onBackPressed() path in the situations Codename One depended on. Without a registered predictive-back callback, Back could leave the application instead of navigating its form stack.

Google's target API requirements moved application updates to Android 16. The fix registers an OnBackInvokedCallback bridge and routes it into the existing Codename One back command. The Android builder still compiles against an older SDK surface in parts of the pipeline, so the bridge uses reflection and a proxy rather than linking the newer class directly.

System Back gesture
        |
OnBackInvokedCallback
        |
PredictiveBackBridge
        |
Codename One back command

Input methods can emit both a legacy key event and the new callback. The bridge suppresses the duplicate so one gesture does not navigate twice. Predictive progress animation is not part of this change; correctness came first.

This is exactly the kind of regression that can hide until a target-SDK deadline changes which platform path is active. The daily scan connected the policy date to the generated Android activity and its runtime behavior.

Contact policy became an API design task

Google's contacts permission policy is not solved by changing one manifest line. Many applications ask for an address-book permission only to let the user choose one person. The appropriate response is a narrower interaction, not a more elaborate permission dialog.

That led to ContactPicker, which uses the Android system picker on Android 17, a permission-free single-contact fallback on older Android versions, and CNContactPickerViewController on iOS. The picker returns the selected snapshot. It does not grant the application a standing right to query the address book.

The next article covers requested fields, multi-selection limits, snapshots, fallbacks, and builder permission detection.

What this changes for release work

The immediate changes matter. The larger gain is a repeatable process:

Read Apple and Google primary sources every day.
Extract a date, affected target, and technical condition.
Search issues and merged code before creating work.
Trace the actual producer, including build-server generators and packaged artifacts.
Reproduce the gap or prove the current output already satisfies it.
Patch and test the narrow affected path.

The developer guide overhaul in this release follows the same idea. Structure, cross-references, missing code listings, links, images, and prose now have CI gates. A problem found by automation becomes a specific repair instead of a vague promise to keep the docs current.

Ahead of the deadline, with evidence

Automation will miss notices, misread scope, and find changes that do not apply. That is why the result is a source trail rather than an autonomous verdict. We can inspect the notice, the relevant builder, the generated product, the tests, and the merged fix.

Calls, VPN, OTP, contacts, billing, and platform navigation all sit near permissions or operating-system policy. Finding changes earlier gives us time to choose the narrower API instead of making a deadline patch that widens access. It also moves security work into the normal release cycle, where it can be reviewed beside the code it protects.

The next article shows how to pick one contact without asking for the address book.

Fill an SMS Verification Code Without Reading the Inbox

Shai Almog — Mon, 14 Sep 2026 18:47:29 +0000

A six-digit text field should not need access to every message on a phone.

What is Codename One? Codename One is an open-source framework for building native iOS, Android, desktop, and web apps from a single Java or Kotlin codebase. Learn more at codenameone.com.

PR #5642 adds one-time-code autofill, a country-aware phone-number field, and a complete verification component. iOS, Android, and the browser can offer the code through their protected autofill path. The application never receives the rest of the inbox.

For the rest of this release, including native call management, VPN, AppKit, windows, and contacts, read the weekly overview.

The complete verification flow

PhoneVerification combines phone entry, code entry, resend timing, and the two server calls:

PhoneVerification verification = new PhoneVerification();

verification.setCodeSender((number, response) ->
        api.requestCode(number, response));

verification.setCodeVerifier((number, code, response) ->
        api.verifyCode(number, code, response));

verification.addVerifiedListener(evt ->
        showAccountHome());

form.add(verification);

The callbacks are asynchronous. The component owns the screen state while the application owns the network and account policy. That split is important: Codename One cannot decide how long a code lives or whether a verified phone number should create a session.

The server should rate-limit requests by account, number, device, and network; expire codes; cap attempts; and issue a session only after successful verification. The endpoint must never return the code in its response. Autofill improves entry. It does not provide the security policy.

Add autofill to an existing form

Applications with their own flow can use the new input constraint directly:

TextField code = new TextField(
        "",
        "Verification code",
        6,
        TextArea.NUMERIC | TextArea.ONE_TIME_CODE);

On iOS this maps to the one-time-code content type. Android exposes the appropriate autofill hint. The JavaScript port emits the browser's one-time-code autocomplete value. Desktop ignores the constraint.

There is no SMS permission, entitlement, native library, or build hint. An application that uses the field gets metadata on the editor it already has.

Six boxes, one editor

The visual OTP component still presents separate boxes, but they no longer contain six independent native editors. One editor owns the entire value while the boxes draw its characters.

The old design set a maximum size of one on each box. When the operating system supplied all six digits to the focused editor, the native peer truncated the value after the first digit. Paste had the same basic problem.

This changes one obscure customization path. Code should read and write the OtpField value through the field API. Calling getBox(i).setText() no longer changes the code because the boxes are presentation, not storage.

That trade makes typing, deletion, selection, paste, accessibility, and autofill behave as one input instead of a relay race between six editors.

Less access is the better integration

Some older Android OTP examples ask for SMS access and scan the inbox. That makes a small convenience feature responsible for one of the most sensitive data sets on the device. Protected autofill gives the application the value the user intends to enter and nothing else.

The same rule appears throughout this release. The Contact Picker returns chosen fields without exposing the address book. Call and VPN packages trigger only the native services they use. The builders turn an API reference into exact platform metadata rather than accumulating permissions in a generic application template.

Secure-by-default development often looks like subtraction: no inbox reader, no copied SMS parser, no permission explanation screen, and no background component holding more data than the feature needs.

Next, read how the daily platform watch found framework gaps before users reported them.

A Mac App, Not an iOS App on a Mac

Shai Almog — Sun, 13 Sep 2026 16:57:43 +0000

Mac Catalyst runs an iPad application on macOS. That was a useful bridge for Codename One, but it remained a bridge. Once we added multiple desktop windows, the missing desktop operations and rendering compromises stopped being edge cases.

What is Codename One? Codename One is an open-source framework for building native iOS, Android, desktop, and web apps from a single Java or Kotlin codebase. Learn more at codenameone.com.

PR #5601 changes the default native Mac build to AppKit. The result is an NSApplication with NSWindow, NSMenu, NSTextInputClient, NSScreen, and a CAMetalLayer for each rendered window. It is a Mac application rather than an iOS application asking macOS to translate the experience.

For the complete release, including calls, VPN, OTP, contacts, and Android billing, read the weekly overview.

Catalyst was doing expensive work

The Catalyst port rendered a secondary Codename One window into a mutable image and then copied that image into the scene. A 4K BGRA surface is roughly 33 MB before another buffer or copy enters the picture. Moving or repainting several windows multiplies that cost.

AppKit gives each Window its own Metal-backed drawable:

Dirty regions stay attached to one native window. A repaint in an inspector does not need an intermediate image the size of the editor window. Monitor scale comes from the NSScreen that owns the window, not from an iOS scene approximation.

A Codename One component tree rendered into an AppKit window at 900 by 700.

Desktop operations are desktop operations again

The AppKit port implements always-on-top, utility windows, minimize, restore, maximize, modality, undecorated windows, and native dirty clipping. Menus use NSMenu. Text editing implements NSTextInputClient, including composition and input-method interaction. Multiple monitors come through NSScreen with their independent work areas and scale factors.

Those details matter to applications such as editors, trading terminals, control rooms, and internal tools. A utility palette that cannot remain above its owner is not a utility palette. A text editor that bypasses the input method works only for the developer who tested it.

The dialog work builds on this port. A dialog may stay in its owner's layered pane or become a native modal window. Both paths now have a real Mac window model underneath them.

Existing build targets, different native foundation

The normal targets keep their names:

mvn -B \
  -Dcodename1.platform=ios \
  -Dcodename1.buildTarget=mac-source \
  package

mvn -B \
  -Dcodename1.platform=ios \
  -Dcodename1.buildTarget=mac-os-x-native \
  package

mac-source produces an Xcode project under the build target directory. mac-os-x-native produces the signed native result through the build service. Existing projects do not need a new application API.

Catalyst has no separate build target. An application that depends on it can preserve the previous behavior by setting the existing hint and building an ordinary iOS target:

codename1.arg.macNative.enabled=true

Use ios-source for a local Xcode project or ios-device for a build-server build. Catalyst is no longer the default definition of “native Mac.”

A port is a contract, not a screenshot

The pull request ran the full native screenshot suite plus platform and input tests. The same window layouts are captured at several aspect ratios. Text input, mouse routing, focus, resizing, modality, and screen scale have dedicated coverage.

Accessibility follows the window model too. IOSNative.updateAccessibilityTree() sends the framework semantics tree to CN1MacAccessibilityUpdateTree(), which installs a hierarchy of NSAccessibilityElement children on the relevant window. Roles, labels, values, states, standard and custom actions, and live-region announcements reach VoiceOver through AppKit instead of stopping at the portable tree.

Platform services with a UIKit-only implementation still need individual AppKit work. Switching the default port does not make those integrations native to macOS automatically.

Another Tuesday

A new Codename One platform port once deserved an entire release cycle and its own launch. This week the AppKit port arrived beside VoIP, VPN, phone verification, private contact selection, native dialogs, billing, browser density, and a documentation overhaul. A new native platform has become another Tuesday.

The common component model and builder contract carry most of the application unchanged. The Mac port owns native windows, input, menus, text, and rendering. It does not require a second application UI or a Mac-specific navigation architecture.

The same division strengthens secure defaults. Native platform integration belongs in a reviewed port and build pipeline, not in copied project fragments that drift across application repositories. Applications keep their own interface and data model. The builder supplies the narrow native product needed to run them.

Next, the OTP article removes an inbox permission from a common verification flow.

A Dialog Can Now Be a Native Desktop Window

Shai Almog — Sat, 12 Sep 2026 16:17:44 +0000

Last week's native-window release could open an editor, inspector, and tool palette as separate operating-system windows. Then an ordinary Dialog.show() inside the inspector looked for the current Form and appeared on the wrong surface.

What is Codename One? Codename One is an open-source framework for building native iOS, Android, desktop, and web apps from a single Java or Kotlin codebase. Learn more at codenameone.com.

That bug exposed every component that treated “top level” and “form” as synonyms. PR #5624 fixes those assumptions and adds something more visible: a Dialog can now become a real modal desktop window.

For VoIP, VPN, the AppKit port, OTP, contacts, and the rest of this release, read the weekly overview.

Two useful kinds of dialog

The default remains a lightweight dialog painted inside its owner's layered pane. It matches Codename One styling and works on every port. A desktop application can make ordinary confirmation dialogs native windows while keeping the familiar static API:

Dialog.setDefaultNativeWindowMode(true);

boolean delete = Dialog.show(
        "Confirm deletion",
        "Delete Quarterly report.pdf?",
        "Delete",
        "Cancel");

if (delete) {
    deleteDocument();
}

An actual JavaSE desktop capture on macOS. The title bar belongs to a separate operating-system window; the body and actions use the application's Codename One theme.

The defaultNativeWindowModeBool theme constant provides the same application-wide setting without a startup call. For a single custom dialog, call setNativeWindowMode(true) on that instance. The instance setting wins over the static default, which wins over the theme. On a port without native windows, the dialog stays lightweight. There is no second code path to maintain.

Native-window mode is useful when the dialog must participate in desktop window ordering, focus, or task switching. Lightweight mode is usually better for a small prompt that should inherit the exact visual treatment of its owner.

Ownership was the real bug

Dialog, Sheet, ToastBar, ComboBox, FloatingActionButton, InfiniteProgress, tooltips, and HTMLComponent all had paths that asked Display for the current form. That question has one answer, even when the event came from another window.

The corrected path starts with the component that caused the action:

Code that creates a dialog without a source component can bind it explicitly:

Dialog details = new Dialog("Details");
details.setTopLevelHost(inspectorWindow);
details.add(new Label("Selection metadata"));
details.show();

The dimming layer, popup position, focus restoration, repaint region, and input routing now belong to that window. Accessibility state is also maintained per top level, so opening an inspector does not replace the main form's accessible root.

Popups should not become surprise windows

An anchored combo-box popup stays attached to its field. A floating-action submenu stays near its button. Turning either into an independent desktop window would break positioning and keyboard behavior, so the new native mode is limited to dialogs and interaction dialogs.

Picker inside a window still uses its lightweight popup. Toolbar remains a Form concept. A transition cannot animate one operating-system window into another because the two surfaces do not share a graphics context. Change content inside one window when an animated transition matters:

inspectorWindow.setContent(nextPanel, CommonTransitions.createFade(250));

Those limits are explicit because a fake cross-window animation would be less predictable than no animation.

The same contract on Windows and Mac

The test suite opens the same controls in 400 by 300, 900 by 700, and 1000 by 400 windows. The wide case catches code that still reads the main display width. Modal cases verify that the owner is blocked while other event-dispatch work can continue.

This also validates the new AppKit port against the existing Windows implementation. A platform port is much easier to trust when it must pass behavior captured by another native port instead of defining success for itself.

Desktop work without a desktop fork

The Window API is settling into the same pattern as this week's call, VPN, and contact work. The common API owns the behavior application code can rely on. Each port handles the native surface it actually has. Unsupported behavior stays visible instead of becoming a silent approximation.

That consistency matters for security as well as polish. A confirmation must block the window that contains the sensitive operation. A popup must not leak input to another surface. Accessibility focus must remain attached to the content the user is operating. These details are small until the wrong window accepts a command.

Next, read how Catalyst gave way to a real AppKit application.

VoIP, VPN, and the Build System Behind Them

Shai Almog — Fri, 11 Sep 2026 17:01:39 +0000

In 2019, a reader asked whether our WhatsApp clone included VoIP. I said no. It would require native integration, and the setup was too much for that project. For years, that was the line.

What is Codename One? Codename One is an open-source framework for building native iOS, Android, desktop, and web apps from a single Java or Kotlin codebase. Learn more at codenameone.com.

VPN sat behind the same line. These features do not live neatly inside the application process. On iOS, a VoIP push can arrive before the application installs a Java listener, yet CallKit expects the incoming call to reach the lock screen on its deadline. A Call Directory integration is a separate extension executable with its own lifecycle and signing identity. Managed VPN adds Network Extension entitlements and profile rules. Android solves the same jobs through ConnectionService, VpnManager, VpnService, manifest declarations, and foreground-service rules.

Wrapping those APIs in Java is the small part. A cross-platform runtime cannot add a service before installation, answer a native callback before the application is ready, or create and sign another executable inside the application bundle. Once every team must maintain those pieces in Xcode and Android Studio, the shared abstraction has stopped at the hardest part.

Codename One has a secret weapon for that problem: builders.

Builders already assemble the native product, so they can change its shape based on the Java packages the application actually uses. They link frameworks, inject permissions and background modes, generate native delegates and services, and create extension targets when needed. Leave a package out and its native machinery stays out too.

PR #5604 is where we crossed that old line. It introduced first-class call management, VoIP push handling, managed VPN, and the packet-tunnel API and Android host. PR #5693 completes the iOS path by generating a separately translated and signed Network Extension. The Java API is the visible result. The bigger change is that builders assemble the system integration around it without turning every application team into the maintainer of two native build projects.

TL;DR

Calls connects application call state to CallKit on iOS and self-managed ConnectionService on Android. Your media and signaling stack remain yours.
Vpn installs and controls managed IKEv2 profiles on iOS and Android. iOS also supports managed IPsec profiles.
VpnTunnel exposes raw packets for an application-implemented tunnel on Android and iOS. The iOS builder work generates and signs a separate Network Extension containing the translated Java tunnel.
Dialogs and secondary windows now work together, including an opt-in native modal window.
The new AppKit port builds a real Mac application instead of presenting an iOS application through Catalyst.
SMS one-time-code autofill fills a verification code without asking to read the inbox.
A daily platform watch now turns Apple and Google notices into source-level checks before deadlines become fires.
The new Contact Picker returns selected contact data without broad address-book access.

A call is a system session before it is a media session

A VoIP application has two timelines. Its signaling server and media engine have one. The operating system has another. On iOS, an incoming VoIP push must be reported to CallKit immediately. The Java application may not be running yet. On Android, a self-managed connection participates in system call routing and audio focus even when the application's own screen is elsewhere.

The new API keeps those responsibilities separate:

if (!Calls.isSupported()) {
    return;
}

Calls.configure(new CallConfiguration()
        .displayName("Acme Talk"));

Calls.addActionListener(new CallActionAdapter() {
    public void answerRequested(String callId, CallAction action) {
        signalling.accept(callId);
    }

    public void audioSessionActivated(CallAudioSession session) {
        media.start(session.getCallId());
    }

    public void providerReset() {
        media.stopEverything();
    }
});

Calls does not choose a codec, move audio packets, or invent a signaling protocol. It owns the bridge to the system call UI and lifecycle. The application starts media only after the native audio session activates, not merely because the user tapped Answer.

The package boundary also carries meaning. com.codename1.call.session adds the core system call integration. com.codename1.call.voip adds PushKit and the iOS VoIP background mode. com.codename1.call.directory adds directory integration without silently pulling in the self-managed calling permission. Apple can reject an application that declares VoIP background execution without using it, so importing less code must build less native machinery.

The simulator supplies deterministic call and audio-session events. That makes the awkward orderings testable before a build reaches a phone.

Managed VPN with an important platform boundary

Many enterprise applications do not implement a VPN protocol. They install an operating-system profile and ask the platform to connect it. That path now has one Java API:

if (!Vpn.isSupported()) {
    return;
}

VpnProfile profile = new VpnProfile("vpn.example.com")
        .protocol(VpnProtocol.IKEV2)
        .remoteIdentifier("vpn.example.com")
        .localIdentifier("alice")
        .usernamePassword("alice", secret)
        .displayName("Acme Corporate");

Vpn.install(profile).onResult((ok, err) -> {
    if (err == null) {
        Vpn.start();
    }
});

iOS and Android 11 or newer support managed IKEv2. iOS also supports managed IPsec with a pre-shared key. The operating system owns user consent, credential storage, and the active configuration. The API exposes those boundaries rather than storing a VPN password in application preferences.

The packet tunnel boundary

For work that does not fit a managed VPN profile, VpnTunnel lets application code inspect raw IP packets and decide whether to forward or drop them:

public final class LocalTunnel extends VpnTunnel {
    public LocalTunnel() {
    }

    protected void onStart(TunnelConfiguration configuration) {
    }

    protected void onPacket(PacketBuffer packet) {
        if (packet.getFamily() == PacketBuffer.FAMILY_IPV4) {
            forward(packet);
        }
    }

    protected void onStop(TunnelStopReason reason) {
    }
}

The same Java packet loop runs on Android and iOS, but the process boundary is different. Android hosts it in a VpnService inside the application process. iOS requires a NEPacketTunnelProvider Network Extension: a separate executable with its own bundle identifier, provisioning profile, memory limit, and translated VM. The builder work in PR #5693 creates that target, translates from the selected VpnTunnel class instead of the UIKit application shell, adds the framework and entitlements, and embeds the signed extension in the application.

The iOS extension contains the translated tunnel and VM, but not the Codename One networking stack. It can inspect, rewrite, drop, and forward packets on the device. It cannot open a remote connection through com.codename1.io.Socket, ConnectionRequest, or ParparVM's java.net. Android can relay packets because its tunnel runs in the application process. A protocol that needs a remote relay should put that transport behind a platform-specific interface instead of assuming the two hosts are identical.

Apple grants the Network Extension entitlement case by case, so the target is deliberately opt-in. Once the App ID has that entitlement, name the tunnel class in codenameone_settings.properties:

codename1.arg.ios.vpn.tunnel=true
codename1.arg.ios.vpn.tunnel.class=com.acme.LocalTunnel
codename1.arg.ios.appext.CN1VpnTunnel.provisioningURL=https://example.com/CN1VpnTunnel.mobileprovision

Both the host application and <packageName>.vpntunnel App IDs need Apple's Network Extension entitlement. The extension also needs its own provisioning profile. It starts fresh, requires an accessible no-argument constructor, and cannot see application statics or Display. Pass local configuration through TunnelSetup.data and read it in VpnTunnel.onStart(). This is a real cross-platform API without pretending the two operating systems have the same lifecycle or networking facilities.

The builder is part of the runtime contract

A browser application cannot register CallKit, a self-managed Android connection service, or an Apple Network Extension. Flutter, React Native, and .NET MAUI can reach those APIs through native plugins and platform projects. The difficult work then lives in target membership, manifests, entitlements, background modes, native delegates, and signing.

Builders change where that difficult work lives. The build server already owns the native product graph. It can see which Java packages survive into the application and generate the platform pieces that match them:

Dependency injection cannot do this work. The builder can add a service that must exist before Java starts, compile a native callback that meets an operating-system deadline, and sign an extension as part of the same product. Application teams keep control of their UI, protocol, and business logic without maintaining a parallel native build system.

Dialog can become a native modal window

Last week's native-window release named several components that still assumed every top level was a Form. PR #5624 closes most of that list. Dialog, Sheet, ToastBar, combo-box popups, floating-action submenus, progress overlays, tooltips, and HTMLComponent now resolve the window that contains them. Accessibility state is tracked per window as well.

A dialog can remain a lightweight overlay inside its owner, or opt into a real operating-system window:

Dialog.setDefaultNativeWindowMode(true);
boolean delete = Dialog.show(
        "Confirm deletion",
        "Delete Quarterly report.pdf?",
        "Delete",
        "Cancel");

The window follow-up covers precedence, fallback behavior, anchored popups, and the remaining limits.

A Mac application built on AppKit

Mac Catalyst helped us get an iOS application onto macOS, but its desktop behavior remained bounded by UIKit. It could not supply several ordinary window operations, and a secondary 4K surface could require roughly 33 MB for each intermediate frame before the image was copied into place.

PR #5601 replaces the default Mac native path with AppKit. The generated application now owns NSApplication, NSWindow, NSMenu, NSScreen, and a CAMetalLayer per window. Always-on-top, utility windows, minimize, restore, maximize, native modality, and independent dirty-region painting are real desktop operations.

The AppKit article explains the rendering change, build targets, test evidence, and the native accessibility bridge to VoiceOver.

OTP without inbox permission

PR #5642 adds a one-time-code constraint plus reusable phone-number and verification components. On iOS, Android, and the web, the operating system can offer the code from an SMS without giving the application permission to read messages.

PhoneVerification verification = new PhoneVerification();
verification.setCodeSender((number, response) ->
        server.sendCode(number, response));
verification.setCodeVerifier((number, code, response) ->
        server.verifyCode(number, code, response));
verification.addVerifiedListener(evt -> showAccount());

Codename One does not send or verify the SMS. Your server still owns expiry, attempt limits, rate limits, and session issuance. The OTP article includes both the complete component and the lower-level text-field option.

Stop learning about platform changes from failed builds

Until this week, an Apple or Google change usually reached us through a community report. That is useful, but it starts the clock after somebody is already exposed.

We now run a daily scheduled Codex task that reads official platform notices, extracts the requirement and date, traces the affected Codename One producer, and checks for an existing issue or fix. It found the Android 16 back-navigation gap repaired in PR #5673, and the privacy direction that led to the Contact Picker in PR #5680.

The task does not make a notice true, and it does not replace platform tests. Its job is to connect a primary-source deadline to the exact builder, generated project, or API that must change. The platform-watch article shows that chain. Contact selection gets its own code-focused article because the permission model deserves more than a paragraph.

Four smaller changes with a large blast radius

Google Play Billing 8

PR #5651 moves the default Android billing dependency to 8.0.0 and completes the move from the retired SKU API to ProductDetails. Google's billing deprecation schedule now makes version 8 the minimum for updates. The builder absorbs a generated-project migration that most application teams should never have to chase themselves.

JavaScript density now means device pixels

PR #5634 fixes display width, height, and millimeter conversion when the browser device-pixel ratio is neither one nor two. A viewport that is 390 CSS pixels wide at a ratio of three now reports 1,170 device pixels.

This can change layout and screenshot results in existing JavaScript applications. Read CN.getProperty("browser.window.devicePixelRatio", "1") when a breakpoint genuinely needs CSS pixels.

The mouse wheel is no longer a fake drag

Desktop ports used to translate one wheel turn into a press, three drag events, and a release. That could trigger a click when nothing scrolled. PR #5660 routes native wheel events directly.

Built-in scrolling finds the nearest scrollable ancestor. A custom component that consumes wheel input should now override mouseWheel(WheelEvent) or register a listener:

chart.addMouseWheelListener(evt -> {
    WheelEvent wheel = (WheelEvent) evt;
    if (wheel.isControlDown()) {
        zoomBy(wheel.getDeltaY());
        evt.consume();
    }
});

The developer guide became a maintained product

We removed obsolete IDE and Ant-era guidance, folded the Maven workflow into the main book, restored missing samples, and reworked the order of several chapters. More important, CI now checks the guide's structure, cross-references, promised code blocks, served links, images, prose, and generated output.

Documentation drift is now a failing build instead of a cleanup project for some future week. The restored call, VPN, desktop, security, identity, event-thread, graphics, and performance material is part of the release contract.

Native reach with narrower defaults

This week stretches Codename One in both directions. Calls, VPN profiles, AppKit windows, contact selection, and OTP reach deeper into each operating system. Package-triggered builders keep that reach narrow. An application does not receive VoIP background execution because another product needed it. It does not receive broad contacts access to pick one person. It does not gain a message-reading permission to fill six digits.

Secure-by-default programming depends on small public APIs, generated native integration, explicit platform limits, and fewer opportunities to turn a convenience feature into permanent access. You still own the application UI and the protocol choices. The builders absorb the native product plumbing needed to ship them.

Start with the Call Management or VPN chapter, then test the failure path in the simulator before sending a native build.

Build Hints That Fail Before the Build Server

Shai Almog — Thu, 10 Sep 2026 17:03:01 +0000

A bad configuration line can be worse than a failed build. If the build stays green while ignoring the setting, you usually discover the mistake in a generated native project or on a device.

What is Codename One? Codename One is an open-source framework for building native iOS, Android, desktop, and web apps from a single Java or Kotlin codebase. Learn more at codenameone.com.

PR #5586 moves 87 common Codename One build hints into Java's type system. A misspelled hint is now an unknown annotation attribute. A wrong value type or unsupported option stops at compilation instead of traveling to the build server as an inert string.

This change is part of the native windows weekly release. It is available through the Codename One Maven repository, so existing projects need the repository and plugin repository entries shown at the top of that post.

Why build hints existed in the first place

The original Codename One build server changed frequently. We needed to expose a new Android, iOS, or packaging switch without waiting for every IDE plugin to ship an updated settings screen.

Build hints separated those two release clocks. The plugin could send an open-ended map of strings. A builder could start reading a new key immediately:

codename1.arg.<name>=<value>

That escape hatch still does useful work more than a decade later. It lets a CN1Lib contribute native dependencies and lets a project tune low-level output without a new plugin protocol for every option.

The cost is that neither Java nor the plugin knew what most of those strings meant. The prefix confused people. Names and capitalization had to be exact. Values with commas, semicolons, or XML had their own merge rules. A name that no builder read was accepted, uploaded, and discarded.

This line looks plausible:

# Accepted by the old path, but ignored by the Android builder
codename1.arg.android.minSdkVersion=24

The builder reads android.min_sdk_version, not android.minSdkVersion. The project asked for API 24, the build succeeded, and the request used the builder's default.

The compiler now checks the common path

The same setting can live on the application's main class:

import com.codename1.annotations.buildhints.Android;
import com.codename1.annotations.buildhints.AndroidMinSdk;
import com.codename1.annotations.buildhints.Build;
import com.codename1.annotations.buildhints.DesktopBuild;
import com.codename1.annotations.buildhints.DesktopTitleBar;
import com.codename1.annotations.buildhints.Ios;
import com.codename1.annotations.buildhints.ThemeMode;
import com.codename1.annotations.buildhints.Toggle;
import com.codename1.system.Lifecycle;

@Android(
        themeMode = ThemeMode.MODERN,
        minSdkVersion = AndroidMinSdk.API_24)
@Build(nativeTheme = ThemeMode.MODERN)
@DesktopBuild(
        titleBar = DesktopTitleBar.NATIVE,
        width = 1280,
        height = 800)
@Ios(
        themeMode = ThemeMode.MODERN,
        newStorageLocation = Toggle.ON,
        pods = {"Intercom", "AFNetworking"})
public class MyApplication extends Lifecycle {
}

minSdkVersion takes AndroidMinSdk, so an integer does not compile. titleBar takes DesktopTitleBar, so autocomplete shows the accepted values and a made-up constant fails at the same line.

Seven annotations cover the common groups: @Ios, @Android, @DesktopBuild, @Build, @Hardening, @IosPrivacy, and @OnDeviceDebug. Ten enums describe closed value sets. Open-ended values remain strings.

The builders did not need a replacement protocol. BuildHintAnnotationProcessor converts the checked declaration into the same key and string value they already consume. Old projects, older framework versions, and the build service keep speaking the existing wire format.

An unset annotation does not freeze a server default

The build service still needs room to change. An Android packaging default that made sense ten years ago might be wrong for the current Play Store.

That is why no annotation attribute has a meaningful default. An empty string, an empty array, zero, Toggle.DEFAULT, or an enum's unset marker all mean that the application said nothing. The processor emits no hint, leaving the current builder default in control.

There are no boolean attributes. Consider an appBundle attribute with a Java default of false. The Android builder currently defaults that hint to true. Compiling false into every application would silently override the server even when the developer never selected it. Toggle.ON, Toggle.OFF, and Toggle.DEFAULT preserve all three states.

This keeps the reason build hints existed. The server can evolve without requiring a client release for every default change. The difference is that an explicit value can now be checked.

Arrays carry the merge rule

Complex values exposed another weak point in the string form. Some lists use commas, some use semicolons, and a CN1Lib may append its own entry to the application's value.

An annotation expresses a hint that accepts library additions as an array:

@Ios(pods = {"Intercom", "AFNetworking"})

The hint metadata records the wire key, separator, and whether a CN1Lib may append. The processor and library merger use that metadata instead of maintaining separate hand-written separator lists.

A command-line -Dcodename1.arg.<name>=... override still wins. A CN1Lib can still append to a hint whose metadata permits library additions. Declaring the same hint in an annotation and codenameone_settings.properties is different: the build stops and names the duplicate rather than guessing which source you intended.

One catalog replaces five drifting descriptions

The old hint set was partially restated in the developer guide, the Settings tool, the simulator, the Maven plugin's separator map, and an agent reference. Only 147 of roughly 520 names appeared in more than one of those places.

The annotations are now the source of truth for the 87 hints they expose. The remaining hints live in maven/build-hint-catalog, including dynamic families and build-service-only settings. Together they describe all 497 hints read by the builders. The generated developer guide table now contains 577 rows with type, default, and annotation columns.

The Settings tool reads the catalog instead of scraping an AsciiDoc table and guessing types from prose. It validates closed value sets and identifies hints owned by an annotation, so it cannot add a duplicate property behind your back.

The properties editor remains available for the long tail. Its schema now comes from the same catalog as the guide and compiler tooling.

Two CI gates protect the catalog. One fails when framework code reads a hint the catalog does not describe, or when our documentation names a hint no builder reads. The second renders the annotation-backed editor and guide data to prove generation still produces the complete set.

Migrating an existing project

After updating the project POM and Codename One version, run:

mvn cn1:migrate-build-hints

The goal moves every property backed by an annotation when it can reproduce the value faithfully. That includes open-ended strings such as facebook.appId, gcm.sender_id, and ios.teamId. Hints without annotations, including dynamic families, stay in codenameone_settings.properties; values that cannot be translated without changing their meaning stay there too. The goal then runs the annotation processing path and verifies that every moved setting reached the generated manifest. If verification fails, it restores both files.

Older projects might not bind process-annotations to the module that compiles the main class. The build refuses to ignore the annotations and reports the missing execution. Add this to the Codename One Maven plugin configuration when needed:

<execution>
    <id>cn1-process-classes</id>
    <phase>process-classes</phase>
    <goals>
        <goal>process-annotations</goal>
    </goals>
</execution>

Some settings must remain properties. codename1.arg.java.version chooses the compiler that must compile the annotated class, so reading it from that class would be too late. Dynamic families such as android.permission.<NAME> also stay in the file because an annotation cannot expose an arbitrary map key.

Compile failures are the compatibility policy

The annotation form intentionally does not promise source compatibility for build hints. If a weekly release renames an attribute, changes its type, or removes an accepted value, the project stops compiling at the declaration. That is the desired failure mode.

The build service still accepts the old string protocol. An already-built project keeps building. If an annotation disappears and you need the previous spelling, the properties form remains available.

This matters most for settings that affect more than appearance. @Hardening and @IosPrivacy now make common security and privacy configuration visible to the compiler. A security setting that is misspelled is no security setting at all.

Start with mvn cn1:migrate-build-hints, review the generated annotations, and keep the properties that the goal leaves behind. The split is deliberate: checked declarations for the stable, common path and strings where the build still needs an open-ended escape hatch.

Rootless Jailbreak Detection: Updating the Signals, Not the Claim

Shai Almog — Wed, 09 Sep 2026 17:09:25 +0000

ios.detectJailbreak=true did not fire on a device jailbroken with palera1n 2.1.1 in rootless mode. The build hint was wired correctly. The detector was asking questions that described the previous generation of jailbreaks.

What is Codename One? Codename One is an open-source framework for building native iOS, Android, desktop, and web apps from a single Java or Kotlin codebase. Learn more at codenameone.com.

PR #5584 replaces that signal set. It recognizes rootless bootstraps, checks whether detection APIs disagree, inspects mounts and loaded images, and reruns the gate when the application returns from the background.

For native desktop windows, nearby devices, wearable follow-through, and the rest of this release, see the weekly release overview.

Rootless means the old signals can be correctly absent

A rootful jailbreak modifies or replaces files on the system volume. The traditional detector looked for Cydia and apt paths, Substrate-era injected libraries, a writable root filesystem, and a successful write outside the application sandbox.

Current jailbreaks such as palera1n, Dopamine, and XinaA15 keep the signed system volume sealed. They place the Procursus bootstrap under /var/jb, inject through frameworks such as ElleKit, and commonly use Sileo. Writing to the root filesystem still fails because that is the design.

The old detector could therefore receive the correct answer to every old probe and make the wrong integrity decision.

`lstat` sees the symlink after its target is gone

/var/jb is commonly a symlink. On a rebooted semi-tethered device, the target can be absent while the link remains. stat, access, and NSFileManager.fileExistsAtPath follow the link and report that the target is missing.

The new check uses lstat, which reports the link itself. It checks rootless bootstrap paths separately from the rootful file list and emits a rootlessPath signal.

It also distinguishes three results: present, absent, and denied. Collapsing EPERM into ENOENT loses information and can manufacture a false disagreement between two probes that were both refused.

The mount scan does not depend on guessing one path. It detects a writable root file system and additional bootstrap file systems associated with a rootless jailbreak.

A detector should notice when its own answers are filtered

Jailbreak-bypass tweaks hook common filesystem and image APIs so they return clean answers. Checking more paths through the same hooked method adds length without adding an independent signal.

The detector now asks equivalent questions through different entry points. It compares libc lstat with a raw system trap where the platform permits it. It compares the image name returned by _dyld_get_image_name with the path resolved by dladdr.

The two answers should agree on an untouched process. When one path sees an artifact and the other denies it, DeviceIntegrity reports the instrumentation as frida, which is the public reason category for hooking and dynamic instrumentation.

The raw trap is not compiled on watchOS or tvOS because those SDKs mark syscall unavailable. Rootless filesystem and image checks still compile there; only the second opinion is omitted on platforms where a jailbreak is not the target threat.

Loaded-image matching now includes current rootless injectors such as ElleKit alongside Frida and older Substrate names. The implementation avoids walking dyld's live internal table, which can move under another thread. dladdr gives the independent answer without dereferencing a structure intended to be read while a process is suspended.

The package-manager check now starts with Sileo

canOpenURL returns false for a scheme the application did not declare, even if the app handling it is installed. The build now adds jailbreak-related schemes to LSApplicationQueriesSchemes when detection is enabled.

The order is deliberate:

sileo
filza
zbra
cydia

iOS limits how many query schemes an application can declare. The jailbreak probe is lower priority than the schemes requested by application features. The builder appends as many detector schemes as fit after every other feature has claimed its slots. Sileo comes first so a one-slot remainder checks the package manager used by current rootless devices rather than Cydia.

canOpenURL is only one signal and is deprecated as of iOS 27. The filesystem, mount, and image checks carry the main weight.

Hard gate or runtime policy

The zero-code launch gate remains one build hint:

codename1.arg.ios.detectJailbreak=true

It now runs at launch and whenever the application returns from the background. That closes a simple attach-after-launch gap. A detected gate exits with a failure status instead of telling the operating system that the process ended normally.

An application that needs a narrower response can inspect the same signal family at runtime:

if (DeviceIntegrity.isDeviceCompromised()) {
    String[] reasons = DeviceIntegrity.getCompromiseReasons();
    requireStepUpAuthentication(reasons);
}

The runtime API does not cache its result, so a check before a sensitive operation can see instrumentation attached after startup. It does not terminate the process. The application can warn, degrade one feature, or request additional authentication.

This raises bypass cost; it does not establish trust

The PR compiled the detector across device, simulator, Mac Catalyst, watchOS, and tvOS configurations. The symlink behavior and independent-probe logic ran in a native harness. Builder tests pin scheme merging and ordering.

The change was not verified on a jailbroken device during the PR. The original report names real hardware, but the revised detector still needs an on-device confirmation before we call that case closed.

More importantly, every probe runs inside a process controlled by the attacker. A sufficiently capable bypass can patch the final boolean, skip the exit, or modify the application around the check.

High-value authorization belongs on the backend. Bind an Apple App Attest or Google Play Integrity token to a fresh server nonce, verify the token with the platform provider, and let the backend decide whether to permit the action. App Shield packages that server-side verification and policy when an application team does not want to build it directly.

Security work that states its boundary

This week adds multiple native desktop windows, selected document publication, nearby-device APIs, complete watch complications, and current rootless jailbreak signals. The features are broad. Their access paths are narrow.

A window owns one paint and input surface. A document provider publishes one read-only tree. Nearby features bring only the frameworks their package uses. A watch face receives a bounded timeline, not a live application process. Jailbreak detection supplies a local risk signal, while backend attestation remains the trust decision.

Codename One keeps strengthening its security lead by putting these boundaries in the ordinary API. Secure-by-default programming is not a claim that every device is safe. Restricted access, capability checks, explicit failure, and server verification should be the shortest supported path.

If you enable ios.detectJailbreak, test the generated build on the device classes your policy covers. Keep the runtime response proportionate, and gate money movement, credential changes, or sensitive exports on a verdict your backend verified.

Watch Follow-Through: Complications, Tiles, and a Companion Wear APK

Shai Almog — Tue, 08 Sep 2026 17:15:35 +0000

Last week's wearable post ended with two conspicuous limits. Declaring a WATCH_* surface did not generate the native extension or service that puts it on a watch face. An Android companion build did not return a Wear APK beside the phone APK.

What is Codename One? Codename One is an open-source framework for building native iOS, Android, desktop, and web apps from a single Java or Kotlin codebase. Learn more at codenameone.com.

PR #5583 closes both gaps. PR #5594 fixes two watchOS failures that appeared once the complete watch path ran. This is follow-through on the model we shipped last week, not a second wearable announcement.

For native desktop windows and the rest of this release, see the weekly release overview.

One surface declaration now reaches the watch face

A complication remains a watch family in the existing surfaces API:

WidgetKind steps = new WidgetKind("steps")
        .setDisplayName("Steps")
        .addSupportedSize(WidgetSize.WATCH_CIRCULAR)
        .addSupportedSize(WidgetSize.WATCH_RECTANGULAR);

Surfaces.registerWidgetKind(steps);
Surfaces.publish("steps", timeline);

The four portable families lower to the platform surfaces below:

Codename One family	Apple Watch	Wear OS
`WATCH_CIRCULAR`	`accessoryCircular`	Ranged value or monochrome image complication
`WATCH_RECTANGULAR`	`accessoryRectangular`	Long-text complication and a Tile
`WATCH_INLINE`	`accessoryInline`	Short-text complication
`WATCH_CORNER`	`accessoryCorner`	Circular complication because Wear has no corner slot

The build now produces the missing platform pieces. Apple Watch receives a CN1WatchWidgets WidgetKit extension embedded inside the watch application. Wear OS receives one complication data source per kind and a ProtoLayout Tile for the rectangular family.

No watch family means no watch extension, complication service, Tile service, or related dependency. A kind that declares only watch families also stops producing an accidental Android home-screen widget. Add a phone family when the product needs both.

A watch face does not render a small widget

Wear OS asks a complication data source for a typed value. It does not accept a component hierarchy. The generated adapter mines the surface tree for at most two text nodes and one image, then maps them to short text, long text, ranged value, or monochrome image data.

Containers, padding, backgrounds, corner radii, alignment, weight, per-node color, and child actions do not survive that lowering. The renderer logs dropped details once through CN1Surfaces, so adb logcat -s CN1Surfaces shows what the watch face received.

Apple's WidgetKit accessory families render more of the SwiftUI tree, but the slots remain small and often monochrome. A single number or gauge is safer than a layout that depends on several labels.

A Wear Tile is different. It renders the node tree and supports per-node actions. Circular progress can remain circular there. A SurfaceDynamicText countdown does not tick continuously on the Tile; it advances when the published timeline refreshes.

The simulator previews all four watch families at their real point sizes and clips circular shapes. It cannot show the lossy Wear OS conversion. Check a final complication on the device and watch face you plan to support.

Phone-published data has to cross to the watch

The phone and watch use separate storage. Even Apple's App Group identifier resolves to a watch-local container on the watch. Publishing a timeline on the phone cannot change a file in that container.

When a kind contains a watch family, a successful phone-side Surfaces.publish() now mirrors the descriptor after the local publish completes:

Apple uses transferCurrentComplicationUserInfo when the watch reports that a complication is active and the daily transfer budget has room. Otherwise it queues ordinary user info for the next watch wake. The payload is capped at 48 KB. Imagery is dropped before the whole update so the number can still refresh.

Wear OS sends the descriptor through the Data Layer and moves imagery as a file. The watch process can apply the framework-reserved update without launching the Codename One UI.

This mirror is best effort. A product that requires a guaranteed current value should let the watch fetch from the network or publish from its own application lifecycle.

Android companion builds now return two artifacts

codename1.watchMain still names the watch application entry point on both platforms:

codename1.watchMain=com.example.MyWatchApp

Without codename1.watchStandalone, Android now returns:

myapp.apk
myapp-wear.apk

The Wear artifact declares the watch hardware feature and receives a higher version code. Google Play uses supported-device filters and version codes to select the phone or watch product from one listing. android.watchVersionCodeOffset changes the default gap, and android.watchVersionCode sets the watch code directly.

Setting codename1.watchStandalone=true still makes the single Android artifact the standalone watch application. Set android.watchModule=false when the application wants the phone-to-watch Data Layer but does not ship its own watch UI.

On Apple, a companion remains embedded inside the phone application. A standalone watch target is generated, but the returned archive still targets the phone scheme. App Store submission of that standalone product needs a manual archive of the watch scheme in Xcode.

Running the complete path found two watchOS failures

The new complication work exercised a watch application from build through launch. That exposed two issues fixed by PR #5594.

Six native functions in IOSNative.m call translated IOSWearableCallbacks entry points. Their generated header was never included. The watch compiler rejected the undeclared calls. A phone compiler that accepted the implicit declarations could pass the Java objects through the wrong native calling convention.

After that compile failure was fixed, the watch app crashed at launch. Objective-C called [session activate], which is the Swift spelling of the API. The Objective-C selector is activateSession. iOS happened to answer the wrong selector in the existing path; watchOS did not.

The generated callback header is now included only when WatchConnectivity is translated, and both activation call sites use activateSession. The watch screenshot run reaches the full suite instead of stopping before the first capture.

Closing the gap we wrote down

The useful part of publishing explicit limits is that they become work items instead of folklore. Last week's post said complications were a portable model without generated platform adapters and that Android companion packaging was missing. This release replaces both sentences with working build outputs, tests, and device-facing documentation.

The rest of this week's work applies the same discipline. Desktop windows isolate paint and input state per native surface. Document Provider publishes a narrow file tree to another process. Nearby Devices separates ranging, association, and transport so an application takes only the platform access it uses. Rootless jailbreak detection updates the signal set without promoting a local heuristic into a server trust decision.

Codename One's security lead depends on these boundaries remaining visible. A watch update can be delayed. A face may discard most of a layout. A companion APK has its own lifecycle and storage. Code that handles those states explicitly is safer than code built on a cross-platform promise that the operating systems do not keep.

The next post upgrades iOS jailbreak detection for current rootless layouts.

UWB and Nearby Devices: Distance, Direction, Association, and Transport

Shai Almog — Sun, 06 Sep 2026 16:14:40 +0000

Bluetooth can tell you that a device is probably nearby. Ultra-wideband can tell you that it is 42 centimeters away and 18 degrees to the right, until the person holding it turns and the direction disappears.

What is Codename One? Codename One is an open-source framework for building native iOS, Android, desktop, and web apps from a single Java or Kotlin codebase. Learn more at codenameone.com.

That last clause is part of the API contract. Nearby hardware gives partial answers, permissions change by operating-system version, and Apple's local transport cannot discover Google's. PR #5589 exposes those boundaries through three packages under com.codename1.nearby.

For multiple native windows, Document Provider, and the rest of this release, see the weekly release overview.

Three packages answer three different questions

The API is split by capability:

Package	Question
`com.codename1.nearby.ranging`	How far away is the peer, and in which direction?
`com.codename1.nearby.companion`	Which accessory did the user associate with this app?
`com.codename1.nearby.transport`	How do two nearby instances exchange a payload?

Referencing a package is the opt-in. An application that imports only ranging does not receive Nearby Connections, MultipeerConnectivity, local-network prompts, or companion-profile permissions. The build scans the bytecode and includes the frameworks needed by the packages it finds.

Use capability queries instead of platform checks:

if (Ranging.isSupported()) {
    // Offer precision finding.
}
if (CompanionDevices.isSupported()) {
    // Offer association.
}
if (NearbyTransport.isSupported()) {
    // Offer local peer transfer.
}

UWB hardware is absent on many current phones. The application still needs a useful state when ranging is unavailable.

Ranging starts after the peers exchange tokens

Ultra-wideband measures radio time of flight. The practical target is roughly ten-centimeter ranging, while a Bluetooth signal-strength estimate can swing by meters when a hand covers the phone. UWB still does not discover or identify the peer by itself.

Both devices first exchange a ranging token over a channel they already share. A Bluetooth LE GATT characteristic is the common choice. Once the other token arrives, the session can start:

Ranging.prepareSession(RangingRole.CONTROLLER).onResult((session, err) -> {
    if (err != null) {
        showBluetoothFallback();
        return;
    }

    bluetoothCharacteristic.write(
            session.getLocalToken().toByteArray());

    session.addRangingListener(new RangingAdapter() {
        public void updated(RangingUpdate update) {
            if (update.hasDistance()) {
                distance.setText(Math.round(update.getDistance(
                        RangingUnit.CENTIMETERS)) + " cm");
            }
            if (update.hasDirection()) {
                arrow.setAngle(update.getAzimuth());
            }
        }
    });

    session.start(RangingToken.fromByteArray(theirToken));
});

Every RangingUpdate field except its timestamp is optional. A peer behind the phone can report distance without direction. At the edge of radio range, both can disappear temporarily. Check hasDistance() and hasDirection() independently.

Azimuth is platform-dependent, with zero straight ahead and positive values to the right. Android reports -90 to 90 degrees, so azimuth alone cannot distinguish a peer in front from one behind. iOS reports a direction vector, and the port derives a -180 to 180 degree azimuth while retaining the original vector. Elevation runs from -90 to 90 on both platforms when it is available.

One session tracks one peer. This reflects Apple's NINearbyPeerConfiguration limit. Track several peers with several sessions.

Accessory ranging has different handshakes. iOS uses the Nearby Interaction Accessory Protocol and returns bytes that must be forwarded to the accessory. Android joins the UWB address, channel, preamble, session id, and key named by the accessory. A token serialized on one platform is rejected on the other instead of being handed to an incompatible native API.

Association asks the user which device belongs to the app

Companion association is not Bluetooth pairing. The operating system draws a chooser, the user selects one accessory, and the app receives a durable association id.

AssociationRequest request = new AssociationRequest.Builder()
        .addFilter(DeviceFilter.bleService("180D"))
        .build();

CompanionDevices.associate(request).onResult((device, err) -> {
    if (err == null) {
        Preferences.set("sensor", device.getId());
        CompanionDevices.startObservingPresence(device.getId());
    }
});

The association survives restarts and reboots. CompanionDevice.getAddress() is also the identifier accepted by BluetoothLE.getPeripheral(String), so the result connects directly to the existing BLE API.

Android can report companion presence from API 31. Register the listener during init() because the operating system can record a sighting while no form exists. Codename One replays the stored event when the app next initializes. It does not silently turn presence into unrestricted background execution.

iOS 18 uses AccessorySetupKit for association. It does not provide the same live presence event. An application that needs proximity on iOS should scan with the Bluetooth API. The service UUIDs iOS may show must be declared through ios.nearby.accessoryServices before the app is built.

Nearby transport is local, but not cross-ecosystem

NearbyTransport maps to Google Nearby Connections on Android and MultipeerConnectivity on Apple platforms:

When the application uses a service id such as chat, declare it for the iOS build:

codename1.arg.ios.nearby.serviceType=chat

The hint accepts a comma-separated list when the application uses more than one service id. Without it, the iOS builder declares only the package-derived id, and the runtime rejects advertising or discovery for chat before starting the native service.

NearbyTransport.addTransportListener(new TransportAdapter() {
    public void endpointFound(Endpoint endpoint) {
        NearbyTransport.requestConnection(endpoint, "Shai's phone");
    }

    public void connectionRequested(IncomingConnection request) {
        showCodeOnScreen(request.getAuthenticationToken());
        request.accept();
    }

    public void connected(Endpoint endpoint) {
        NearbyTransport.send(endpoint, Payload.fromBytes(data));
    }

    public void payloadReceived(Endpoint endpoint, Payload payload) {
        process(payload.getBytes());
    }
});

NearbyTransport.startAdvertising(
        "chat", "Shai's phone", TransportStrategy.CLUSTER);
NearbyTransport.startDiscovery("chat", TransportStrategy.CLUSTER);

Android derives a short authentication token from the connection's key exchange. Show it on both screens before accepting a sensitive connection. iOS supplies no equivalent token. The API returns an empty value there instead of constructing a decorative code a relay could reproduce.

An Android phone discovers another Android endpoint. An iPhone discovers another Apple endpoint. The two native stacks do not share a wire protocol. Use BLE L2CAP or Bonjour and sockets when the product needs iPhone-to-Android communication.

Byte payloads are intentionally small. Larger data uses a file payload and reports progress. A resolved send means the platform accepted the payload; PayloadStatus.SUCCESS means the peer received it.

Develop the failure states without UWB hardware

The simulator, desktop ports, and JavaScript port implement local simulated sessions rather than returning a stub. They report NearbyAvailability.LOCAL_ONLY, which lets the app label the peer as simulated.

This covers the application logic that usually consumes the time: an arrow that loses direction, a distance label that becomes unavailable, an association chooser that is canceled, a connection that is rejected, and a payload that fails after it was accepted for sending.

The simulator cannot prove antenna behavior, radio coexistence, entitlement signing, or real-device permission prompts. Run those on the target hardware before treating the feature as complete.

Reach without pretending the platforms agree

Nearby Devices expands the physical reach of a shared application without flattening three different system contracts into one unreliable call. Ranging admits that direction can disappear. Companion association names the versions and profiles that exist. Transport says that the Apple and Google protocols cannot find each other.

The rest of this week's release keeps those boundaries visible. Desktop windows exist only where the port has a window manager. Document Provider publishes a named read-only tree. Watch complications lower the shared surface model into the constrained data a watch face actually accepts. Rootless jailbreak detection adds current signals, then leaves high-value authorization on the backend.

Secure-by-default programming often starts with an API that can say no. Capability queries, optional ranging fields, a user-approved association, and a visible authentication boundary make failure part of the normal path instead of a surprise native exception.

The next post closes the watch gaps we documented last week.

Put App Documents in the System File Browser

Shai Almog — Sat, 05 Sep 2026 16:02:40 +0000

An invoice, drawing, report, or project file can live inside an application for years without becoming a document the operating system understands. The user has to open the app before another app can preview or share it.

What is Codename One? Codename One is an open-source framework for building native iOS, Android, desktop, and web apps from a single Java or Kotlin codebase. Learn more at codenameone.com.

PR #5607 adds com.codename1.documents. It publishes a selected, read-only document tree as a location in the iOS Files app and Android storage picker. The application decides which nodes exist, what they are called, and whether their bytes are local or fetched from a server.

For native desktop windows and the rest of this release, see the weekly release overview.

Publish a tree, not a directory permission

The root is a DocumentNode. Folder and file nodes underneath it describe the view exposed to the system browser:

String shared = DocumentProvider.getSharedDirectory();
writePdf(shared + "/august-1042.pdf", invoiceBytes);

DocumentNode root = DocumentNode.folder("root", "My Invoices");
DocumentNode august = DocumentNode.folder("2026-08", "August 2026");
august.add(DocumentNode.file("inv-1042", "Invoice 1042.pdf")
        .setContentType("application/pdf")
        .setPath("august-1042.pdf")
        .setSize(invoiceBytes.length)
        .setLastModified(invoiceModified));
root.add(august);

DocumentProvider.publish(root);

The published tree does not have to mirror the application's internal storage. An internal object id can become a stable document id. A database title can become the visible filename. A nested folder can be a projection of records that are not folders on disk at all.

The location is read-only. The file browser does not offer rename, delete, or save operations that the application cannot honor. Updating the view means publishing another tree.

Publishing one selected tree is narrower than exposing the whole documents directory. The file browser sees only the nodes in the most recent index. Logging out can withdraw the whole location:

DocumentProvider.clear();

If the requirement is simply to show the application's entire iOS documents directory, the existing UIFileSharingEnabled and LSSupportsOpeningDocumentsInPlace plist keys remain the smaller option. Document Provider is for a curated tree, a virtual layout, or content that does not live on the device yet.

The iOS extension cannot call the application

Apple runs a File Provider extension in a separate process. The Files app can start it while the Codename One application is not running. The extension cannot call into the Java application to ask what a folder contains.

Codename One therefore uses a publication model. DocumentProvider.publish() serializes the tree into an App Group container shared by the application and the generated extension. The extension reads that index and serves the browser independently.

On Android, the generated DocumentsProvider runs inside the application process. It still consumes the same published model. Keeping one model avoids application code that works only because Android happens to have a different process boundary.

Local files must be written under DocumentProvider.getSharedDirectory(). The iOS extension cannot see a path under the application's ordinary home directory, even if Java code can.

Do not overwrite bytes in a file that is already published. Another app may be reading it. Write the new version under another name, publish a tree that points to it, and remove the old bytes after existing readers have had time to finish.

Remote nodes can appear before their bytes arrive

A file node can carry a remoteId instead of a local path:

DocumentProvider.setRemoteEndpoint(
        "https://api.example.com/drive", sessionToken);

DocumentNode root = DocumentNode.folder("root", "Example Drive");
root.add(DocumentNode.file("report-52", "Quarterly Report.pdf")
        .setContentType("application/pdf")
        .setRemoteId("server-object-52")
        .setSize(487120)
        .setLastModified(reportModified));
DocumentProvider.publish(root);

When the user opens that node, the extension sends:

GET /drive/fetch?id=server-object-52
Authorization: Bearer <published token>

The token is the extension's only application state. It cannot borrow an in-memory login session from a process that may not exist. Publish a new endpoint token when the session renews, and clear the provider on logout.

A node can have both a local path and a remote id. The local copy wins, so a cached document opens without a round trip while the same index still describes how to fetch a file not cached on the device.

iOS signing is part of the feature

Referencing com.codename1.documents generates the platform machinery. On iOS, set the explicit hint so the Certificate Wizard and preflight know to prepare extension signing before bytecode scanning occurs:

codename1.arg.ios.documentProvider.enabled=true
codename1.arg.ios.documentProvider.appGroup=group.com.example.myapp
codename1.arg.ios.documentProvider.displayName=Example Drive

The extension has its own bundle id, <your.package>.CN1Documents, and needs its own explicit App ID and provisioning profiles. Both the application and extension App IDs must carry the same App Group. The Certificate Wizard creates and installs these assets. A wildcard App ID cannot carry the App Group entitlement.

Android needs no configuration beyond referencing the API. The build declares an authority at <your package>.documents.

Mac Catalyst cannot host Apple's FileProvider framework. DocumentProvider.isSupported() returns false there and in the simulator. Simulator publication still writes the generated index under the application home directory so you can inspect what a device extension would receive.

A week of narrower capabilities

Document Provider gives the operating system access to a named tree, not to the application sandbox. The rest of this week's work keeps similarly narrow boundaries. Native desktop windows get independent render and input surfaces without changing the phone model. Nearby device features opt in by package. Watch complications publish a timeline to a small system surface rather than starting the whole app.

Making the narrow path the ordinary API reduces security mistakes. A read-only provider, an explicit App Group, and a tree that disappears on logout reduce the amount of platform code an application team has to get right. Rootless jailbreak detection and backend attestation cover different parts of the threat model, but they follow the same rule: expose the signal, define its limit, and avoid pretending that local code grants trust.

The next post measures the distance and direction to nearby devices.

DEV Community: Shai Almog

Lies, Damn Lies and Benchmarks

Coming up: less waiting, more room, and work that travels

Less garbage, more room for your app

The live-set estimate was missing live objects

A useful image should survive longer than a cold one

Chasing Swiss speed without changing your Java maps

Preserve the first probe and change what follows

A compact table can still be full of little allocations

Faster starts begin with work your app never needed

Layout was doing work that belonged to painting

JavaScript was preparing to suspend methods that could not block

Cross-device continuity: pick up where you left off

Native drag and drop: take it outside your app

Give your Javadoc the website it deserves

Android 17 without the last-minute scramble

Ask for location at the moment the user needs it

Stop making each application parse its own key armor

Removing a task is part of ending a session

Less runtime work, fewer places to get security wrong

Pick One Contact Without Asking for the Address Book

Ask for the fields the screen needs

Platform differences remain visible

Permission detection had to become more precise

Privacy is also product design

We Stopped Waiting for Platform Changes to Find Us

A notice is the start of an investigation

Android 16 changed the Back contract

Contact policy became an API design task

What this changes for release work

Ahead of the deadline, with evidence

Fill an SMS Verification Code Without Reading the Inbox

The complete verification flow

Add autofill to an existing form

Six boxes, one editor

Less access is the better integration

A Mac App, Not an iOS App on a Mac

Catalyst was doing expensive work

Desktop operations are desktop operations again

Existing build targets, different native foundation

A port is a contract, not a screenshot

Another Tuesday

A Dialog Can Now Be a Native Desktop Window

Two useful kinds of dialog

Ownership was the real bug

Popups should not become surprise windows

The same contract on Windows and Mac

Desktop work without a desktop fork

VoIP, VPN, and the Build System Behind Them

TL;DR

A call is a system session before it is a media session

Managed VPN with an important platform boundary

The packet tunnel boundary

The builder is part of the runtime contract

Dialog can become a native modal window

A Mac application built on AppKit

OTP without inbox permission

Stop learning about platform changes from failed builds

Four smaller changes with a large blast radius

Google Play Billing 8

JavaScript density now means device pixels

The mouse wheel is no longer a fake drag

The developer guide became a maintained product

Native reach with narrower defaults

Build Hints That Fail Before the Build Server

Why build hints existed in the first place

The compiler now checks the common path

An unset annotation does not freeze a server default

Arrays carry the merge rule

One catalog replaces five drifting descriptions

Migrating an existing project

Compile failures are the compatibility policy

Rootless Jailbreak Detection: Updating the Signals, Not the Claim

Rootless means the old signals can be correctly absent

lstat sees the symlink after its target is gone

A detector should notice when its own answers are filtered

The package-manager check now starts with Sileo

Hard gate or runtime policy

This raises bypass cost; it does not establish trust

Security work that states its boundary

`lstat` sees the symlink after its target is gone