Shuttle

Prevent TransactionTooLargeException crashes. For good. A modern Android framework for safely transporting large Serializable objects between components, without the crashes.

---

Get To It Quick

• API Documentation
• Why Shuttle?
• How It Works
• Requirements
• Quick Start
• Usage
• Transport with Intents
• Transport with the Navigation Component
• Pick Up Cargo at the Destination
• Cargo States (LCE Pattern)
• Using @ShuttleCargo
• Cleaning Up
• Architecture
• Context Diagram
• Module Overview
• Module Dependency Diagram
• Demo Apps
• Heads Up: Know the Tradeoffs
• AI
• Model Context Protocol (MCP)
• Contributing
• License

---

🚨 Why Shuttle?

🗞️ Featured in [Android Weekly #594](https://androidweekly.net/issues/issue-594) and [Android Weekly #455](https://androidweekly.net/issues/issue-455), validated by the Android community twice.

You've seen this before. Maybe last week:

android.os.TransactionTooLargeException: data parcel size X bytes

It didn't show up in dev. It didn't show up in QA. It showed up at 2am, in production, for real users. Your Play Store rating took the hit before anyone on the team even knew.

So you triaged it. Filed the ticket. Wrote the fix. Reviewed the PR. Ran QA again. Cut the hotfix. And then you added it to the code review checklist, hoping the next engineer would catch it before it happened again.

They won't. Not reliably. You can't review your way out of a structural problem.

Shuttle provides a modern, guarded way to pass large Serializable objects with Intent objects or save them in Bundle objects to avoid app crashes. The crash class is structurally prevented, not governed against.

Why keep spending more time and money on governance through code reviews? Why not embrace the problem by providing a solution for it?

Shuttle reduces the high level of governance needed to catch `TransactionTooLargeException` inducing code by:

1. storing the Serializable and passing an identifier for the Serializable
2. using a small-sized Bundle for binder transactions
3. avoiding app crashes from TransactionTooLargeExceptions
4. enabling retrieval of the stored Serializable at the destination

Shuttle also excels by:

1. providing a solution with maven artifacts
2. providing Solution Building Blocks (SBBs) for building on
3. saving time by avoiding DB and table setup, especially when creating many tables for the content of different types of objects

When envisioning, designing, and creating the architecture, quality attributes and best practices were kept in mind. These attributes include usability, readability, recognizability, reusability, maintainability, and more.

---

⚙️ How It Works

The Shuttle framework takes its name from cargo transportation in the freight industry. Moving and storage companies experience scenarios where large moving trucks cannot transport cargo the entire way to the destination (warehouses, houses, et cetera). These scenarios might occur from road restrictions, trucks being overweight from large cargo, and more. As a result, companies use small Shuttle vans to transport smaller cargo groups on multiple trips to deliver the entire shipment.

After the delivery is complete, employees remove the cargo remnants from the shuttle vans and trucks. This clean-up task is one of the last steps for the job.

The Shuttle framework takes its roots in these scenarios:

• creating a smaller cargo bundle object to use in successfully delivering the data to the destination
• shuttling the corresponding large cargo to a warehouse and storing it for pickup
• linking the smaller cargo with the larger cargo by an identifier
• providing a single source of truth (Shuttle interface) to use for transporting cargo
• providing convenience functions to remove cargo (automatically or on-demand)

Shuttle applies this same logic to Android's binder transaction limit:

┌─────────────────────────────────────────────────────────────┐

│ Source Component │ │ 1. Large Serializable -> stored in Warehouse (Room/DB) │ │ 2. Small cargo ID -> passed in Intent/Bundle │ └──────────────────────────────┬──────────────────────────────┘ │ (tiny binder transaction) ┌──────────────────────────────▼──────────────────────────────┐ │ Destination Component │ │ 3. Cargo ID received -> retrieved from Warehouse │ │ 4. Large Serializable -> delivered via Kotlin Channel │ │ 5. Cleanup -> cargo removed from Warehouse automatically │ └─────────────────────────────────────────────────────────────┘

---

Requirements

---

🚀 Quick Start

1. Add Dependencies

`settings.gradle.kts` — apply the Shuttle Gradle plugin so the @ShuttleCargo annotation processor is wired into your build:

@ShuttleCargo annotates the cargo class you want to transport between screens. At build time, the annotation processor generates the serialization code Shuttle needs to store and retrieve cargo, without any manual Serializable boilerplate.

pluginManagement {

plugins { id("com.grarcht.shuttle.cargo") version "4.0.0" } }

The Shuttle Cargo Gradle plugin configures KSP and registers the Shuttle compiler plugin automatically. Without it, @ShuttleCargo-annotated classes will not generate the required serialization glue code.

`build.gradle.kts`:

plugins {

id("com.grarcht.shuttle.cargo") }

dependencies { implementation(platform("com.grarcht.shuttle:shuttle-bom:4.0.0")) implementation("com.grarcht.shuttle:framework") implementation("com.grarcht.shuttle:framework-integrations-persistence") implementation("com.grarcht.shuttle:framework-integrations-extensions-room") implementation("com.grarcht.shuttle:framework-addons-navigation-component") // Optional

// Annotation-based API — use @ShuttleCargo to own the serialization contract implementation("com.grarcht.shuttle:framework-annotations") ksp("com.grarcht.shuttle:framework-annotations-processor") }

Version Catalog (`libs.versions.toml`):

[versions]

shuttle = "4.0.0"

[plugins] shuttle-cargo = { id = "com.grarcht.shuttle.cargo", version.ref = "shuttle" }

[libraries] shuttle-bom = { group = "com.grarcht.shuttle", name = "shuttle-bom", version.ref = "shuttle" } shuttle-framework = { group = "com.grarcht.shuttle", name = "framework" } shuttle-persistence = { group = "com.grarcht.shuttle", name = "framework-integrations-persistence" } shuttle-room = { group = "com.grarcht.shuttle", name = "framework-integrations-extensions-room" } shuttle-navigation = { group = "com.grarcht.shuttle", name = "framework-addons-navigation-component" } shuttle-annotations = { group = "com.grarcht.shuttle", name = "framework-annotations" } shuttle-annotations-processor = { group = "com.grarcht.shuttle", name = "framework-annotations-processor" }

2. Initialize Shuttle

Wire CargoShuttle once as a singleton. With Hilt:

@Provides @Singleton

fun provideShuttle(facade: ShuttleFacade, warehouse: ShuttleWarehouse): Shuttle = CargoShuttle(facade, warehouse)

@Provides @Singleton fun provideShuttleFacade( @ApplicationContext context: Context, warehouse: ShuttleWarehouse ): ShuttleFacade = ShuttleCargoFacade(context as Application, warehouse)

@Provides @Singleton fun provideShuttleWarehouse( dao: ShuttleDataAccessObject, factory: ShuttleDataModelFactory, @ApplicationContext context: Context, gateway: ShuttleFileSystemGateway ): ShuttleWarehouse = ShuttleRepository(dao, factory, context.filesDir.absolutePath, gateway)

The ShuttleDataAccessObject comes from ShuttleRoomDataDb.getInstance(ShuttleRoomDbConfig(context)).shuttleDataAccessObject. Inject Shuttle wherever you need to transport data.

3. Ship Your First Cargo

// Source: transport a large Serializable via Intent

shuttle.intentCargoWith(context, DestinationActivity::class.java) .transport(cargoId, myLargeSerializable) .cleanShuttleOnReturnTo(SourceFragment::class.java, DestinationActivity::class.java, cargoId) .deliver(context)

// Destination: pick up the cargo

lifecycleScope.launch { getShuttleChannel() .consumeAsFlow() .collectLatest { result -> when (result) { is ShuttlePickupCargoResult.Success<*> -> render(result.data as MyModel) is ShuttlePickupCargoResult.Error<*