Wayline: Building on the sample

Wayline: A ride-hailing app from three sides shows Wayline from the outside. This chapter is for the developer who wants to build on it. It covers how to run the project, how it’s put together, what to change for two common kinds of service, and the parts a sample leaves for you to finish: taking real money, map data at production volume, native maps, sign-in through another identity provider, real text messages, push notifications, analytics, and the database it’s deployed on.

The Initializr’s ride-hailing template generates the project under your own name and package. Paths in this chapter are relative to the project’s root.

The project needs JDK 17 or newer and Maven, and nothing else installed. Start the server on the development profile:

On that profile the database is in memory, verification codes are written to the log and shown in the app in place of a text message, cards are simulated, and the server creates the demo accounts listed in Wayline: A ride-hailing app from three sides. It listens on port 8080.

Then run the app in the simulator, from another terminal in the same directory:

Sign in as [email protected] with the password wayline-demo. Start a second simulator and sign in as [email protected] to follow a ride from both ends. A phone on the same network reaches the server through Server address on the welcome screen.

To use the app in a browser, have the server host it. The first command builds the browser version, which takes about a minute and is needed again only when the app changes:

Then open http://localhost:8080/. Hosting the app in the browser describes what the server does with the staged files and how to deploy them.

backend/server.sh runs the server on the JVM for development. For a deployment it builds a native binary with one command:

There are no platform modules: common builds the app for the simulator, the desktop, Android, iOS and the browser.

Every call the app makes is a method of an interface in shared. This is part of RiderApi:

The data that travels is a record marked @Mapped. This is RideRequestDto:

Two builds read these files. The app’s build writes a client, RiderApiImpl, which the app reaches through Api.rider() in common. The server’s build writes an interface, RiderApiServer, whose methods take the same parameters without the callback and return the value, and a controller that routes each path to it. The server then implements that interface. This is the start of the class that does:

A method added to the contract and not implemented on the server is a compile error, and so is a component the app reads that the record no longer has. Backend controllers, contracts and WebSockets covers the mechanism.

The caller is never a parameter. Caller.name() reads the signed-in user from the request’s security context, so an endpoint acts on the rides of whoever holds the token and can’t be asked to act on someone else’s.

The interfaces are AccountApi, RiderApi, DrivingApi for the application to drive, DriverApi, PaymentApi, GeoApi and AdminApi. Each has one endpoint class on the server that does nothing but call a service: Rides, Payments, Applications, Accounts and the rest. The services hold the rules.

Under the endpoints the server has three layers, and a change usually touches one class in each.

An entity gets no generated key: every id is text the server makes in Ids. It names neither its table nor its columns. They’re the names of the class and its fields in snake case, so Ride is stored in ride and pickupLat in pickup_lat, and a field whose type is an enum, such as state, holds the constant’s name. This is the start of Ride:

The annotations are the ones Backend data access and transactions describes. The entities don’t create the tables. The migrations do, as The schema explains, so a field and its column are two edits that go together.

A repository is an interface marked @Repository that extends CrudRepository, which brings findById, insert and the other operations on one entity:

A query that its method’s name can say is derived from the name, as these two are. The rest carry a @Query over the entities, which names Java fields and not columns, as DriverStateRepository.freeInBox does to find the free drivers inside a bounding box. A query that changes rows is also marked @Modifying and answers how many it changed. Generated repositories covers both kinds.

A service method that’s marked @Transactional runs in one transaction, and every repository it calls works inside it, as The transaction’s session describes. A change made to an entity the transaction read is written when the method returns, with no call to save it: PhoneVerification.store sets the fields of the PhoneCode it read and returns. Methods that only read are marked @Transactional(readOnly = true), which PostgreSQL and MySQL enforce:

Two rules shape the services, and both are about what a transaction must not contain:

A rider cancelling a ride is one such pair:

A private method can carry @Transactional here and be called through this. The build writes the transaction into the method itself, so there’s no proxy for the call to bypass. Backend data access and transactions covers the rules.

The public method runs the transaction through attempt. Two transactions that change the same ride are meant to be settled by the update itself, as Two answers at the same moment describes: the one that comes second changes no rows. MariaDB, as it’s configured out of the box, refuses that second update instead, because the ride it read has changed since, and ends its transaction. attempt runs the transaction again in that case, up to three times. The second run reads the ride as the first one left it, and its update changes no rows, which is the answer the other databases give.

The server is its own OAuth 2.0 authorization server. SecurityConfig registers one public client for the app, which signs in with the authorization-code flow and PKCE and holds no secret. Accounts, the registered client, tokens and signing keys are kept in the database by the tables the security layer creates. The authorization server documents the pieces.

SecurityConfig declares two filter chains. The first covers the sign-in paths: /login, /oauth2/, /.well-known/, /userinfo and /logout. It keeps a session for the few requests a sign-in takes, answers the sign-in form with a status and JSON, and limits attempts for each client address.

The second chain covers /api/**, has no session, and requires a bearer token on every request. After the rate limits it declares, its rules are the whole of the access policy:

Three things about that chain are worth knowing before changing it:

The same sign-in works from a browser with one difference. An installed app receives the authorization code on a loopback address. A page can’t, so the server registers a second redirect address on its own origin, /signin/code, which SignInCodePage answers with the code as JSON. Because a browser sends a session cookie on its own, the sign-in chain refuses a request that changes something and names another site in its Origin header. Hosting the app in the browser explains the reasoning.

A ride is a Ride entity, a row in ride, with a state. The states are the RideState enum in shared, so the app and the server name them the same way, and RideStateMachine on the server lists the moves that are allowed:

Two drivers can’t both accept a ride, a rider can’t cancel a ride in the instant a driver accepts it, and an offer can’t be accepted while the server is taking it back. None of it takes a lock. Every change of state is one conditional update in RideRepository, and the number of rows it changed is the whole answer.

Rides.tryMove asks RideStateMachine.sources which states the new one may be reached from, and passes them to the statement for that kind of move: the rider’s, the driver’s, a driver taking an offer, a driver giving one back, an offer being made, or a move the server makes itself:

Each kind is a fixed statement of its own in the repository. This is the one for a driver accepting an offer:

It names the states the move may start from, the driver the ride was offered to, and the time the offer lapses. It answers 1 for the request that made the move and 0 for every other, because by the time the database runs the second statement the row is no longer in a state the statement names. tryMove records a RideEvent only for the 1, in the same transaction, and Rides.move turns a 0 into a 409 that says where the ride is now.

The service never reads the state and then writes it. Reading first and writing second would let two transactions both read OFFERED and both write ACCEPTED. One statement can’t be interleaved that way on any of the three engines, and nothing is held in the server’s memory, so the rule holds with several server processes on one database.

RideRaceTest is the test that would notice the difference. It calls Rides.accept for one offer from eight threads released together, and requires that exactly one call returns the ride as ACCEPTED, that the other seven are answered 409, and that the ride’s history holds one ACCEPTED event. Two more tests run the acceptances against Rides.tick while it takes back an offer that has lapsed, and require that nobody gets the ride.

Three other places use the same pattern. RideRepository.rate gives a ride its stars only where it has none, so a ride rated twice is rated once. PhoneCodeRepository.takeGuess has the database add one to the count of wrong codes only while the count is under the limit, so of any number of guesses sent together only as many as are left are looked at. RideRepository.claimTip and claimRefund claim a tip and a refund the same way before the payment provider is asked for anything, so of two requests only one charges or refunds. Both claims update the ride’s row, so a refund that arrives while a tip is still being charged sees the tip and answers 409 until the charge has been recorded or given up. A server that stops after claiming a refund leaves the ride marked refunded with no refund recorded. The next request for that ride finds the payment row unchanged and asks the provider again. That’s safe because a refund carries a key made from the charge it returns, so the provider answers a repeat with the refund it made. The same rule lets a second refund through while the first is still at the provider. Whichever of the two fails gives its claim back only while the payment row is still unrefunded, and whichever succeeds writes the ride’s status along with the payment’s. Both write the ride’s row first, so they take turns, and the ride ends up agreeing with its payment in either order. A refunded fare can’t come back as earnings for the driver to cash out.

Accounts.setRoles and Accounts.suspend hold two rows: the profile of the admin who asks and the profile of the account being changed, in the order of their names. The admin’s own role is then read again inside the transaction. Without that, two admins could remove or block each other in the same moment and leave the service with nobody to administer it. Neither blocks an account in the middle of a ride, nor withdraws the driver role from one: every request a blocked account sends is refused, so nobody could end that ride. The admin cancels the ride first, or waits for it to end. A driver taking an offer holds the driver’s profile too and then checks that the account is still allowed, so a block and an accepted offer can’t both land. A live connection that was opening while the change committed reads the account again once it’s registered, so it can’t keep what it read before.

A conditional update settles a race over one row. Two races here are over a row that doesn’t exist yet: a rider asking for two rides at once, and two rides choosing the same free driver. Each transaction reads, finds nothing in its way, and inserts or updates a row of its own. Rides.open and Rides.offer therefore start by writing the rider’s profile row, or the driver’s state row, to the value it already has (ProfileRepository.hold, DriverStateRepository.hold). The database keeps a written row for its writer until the transaction commits, so the second transaction waits there and then reads what the first one left. That write must come first in the transaction: a transaction that reads first may go on seeing the database as it was at that read. That’s why choosing a driver and offering them the ride are two transactions.

The same hold serializes everything else that reads an account and then writes for it. Closing an account, removing a card and choosing the default card hold the profile, so each takes turns with a ride being asked for. Sending a phone code holds it too, so two requests can’t both pass the wait between codes. Changing a password holds it before the old password is checked, so of two changes made together the second is checked against the password the first one set. Approving a driving application holds the applicant’s profile, the row blocking the account holds as well: granting the role rewrites the whole sign-in row, and an approval that read the account before a block would otherwise write it back unblocked. A driver’s position report holds the driver’s state row, so two reports sent together don’t count the same online minutes twice. Cashing out holds the driver’s payout account, so two requests sent together pay the balance once and the second is told there’s nothing left. Saving the payout details holds the driver’s profile, because the first save has no payout row to hold yet. Saving a driving application or uploading one of its documents holds the application, so neither can land on one that was handed in a moment earlier.

Changing a password ends the account’s other sign-ins. A refresh token asks for no password, so account.Grants removes every grant in the authorization server’s table except the one the request came with, and closing an account removes them all. An access token already issued isn’t recalled: it’s checked by its signature and runs out on its own.

A ride’s two parties see each other’s display name, and each other’s phone number while they’re meeting. The e-mail address an account signs in with is its username, and Rides.toDto gives it only to its owner and to an admin. A fare counts toward a driver’s balance once the ride is paid for, in cash or by a card whose charge came back, and a tip paid by card once its charge is recorded. A charge that failed, was refunded or is still pending isn’t money the driver can cash out, and a refund takes the tip back with the fare. The earnings screen’s totals for the day, week and month count the same money as the balance, so a refunded or unpaid ride counts as a trip and earns nothing.

A statement that changes rows in bulk leaves the session unchanged, so an entity read before it keeps the values it had. Every move of a ride is marked @Modifying(clearAutomatically = true), which empties the session after the statement, so a Ride read before a move is read again after it. The services do that wherever they go on to describe the ride.

Rides.request fixes the fare when the ride is created, from the server’s own prices in Fares. The distance the app sends is believed only while it’s plausible for the two points. The driver’s share is fixed at the same moment.

Matcher picks the driver. It selects drivers who are online, reported a position in the last minute, are approved, aren’t blocked, have no ride in hand, drive the kind of car asked for and meet the ride’s options. It takes the nearest one who hasn’t already passed on this ride. The search covers 3 km for the first twenty seconds and 8 km after that.

Rides.tick runs every two seconds as a scheduled job. It takes back offers whose time ran out and searches again for every ride still waiting. Each ride is dealt with in a transaction of its own, so one ride that fails doesn’t cost the others their turn. The job carries a lock name, so with several server processes only one runs it at a time. Backend scheduling and background work covers scheduled jobs.

When a driver completes a ride, Payments.settle charges it.

LiveEndpoint is a WebSocket at /ws/live. The server pushes a short JSON frame when a ride changes state, when the driver of a ride moves, and, to admins, when any car online moves. LiveChannel in the app receives them.

A WebSocket request from a browser can’t carry a bearer token in a header. The app therefore first asks POST /api/live/ticket, which is a normal call that carries the bearer token, for a ticket: a random value that works once, for thirty seconds. It then opens the socket with the ticket in the address. The server stores only a hash of each ticket.

A phone whose app isn’t open hears of the same changes through push notifications, which Push notifications covers.

The screens don’t depend on the socket. Each also asks the server for the current state every few seconds, so a dropped connection delays an update and doesn’t lose it.

Wayline is the app’s main class. It applies the look and the language, starts the session and hands over to Nav.

The colors and the corner radius are CSS variables in the first block of theme.css, each with a dark twin, and every style in the file is written in terms of them. The style names all start with Wl.

The text on every screen is English in the source, and the English text is the key of the translation. src/main/l10n holds one Bundle_<code>.properties for each language.

Layouts.wide() is true in a window at least 165 mm wide. AdminForm shows the phone console below that width and Console above it, and switches when a window is resized across it. Screens that have no wide layout are kept to a column 150 mm wide. On the desktop the nativeTheme=native build hint gives the app the operating system’s own look.

Backend testing covers the server test support.

The Initializr generates the project under the name and package you choose:

This chapter uses the name Wayline. In your project read wayline as your own.

Most of a ride-sharing product is already here. What changes is the identity, the prices and the rules.

The name and the package are chosen in the Initializr. After that they’re in common/codenameone_settings.properties, as codename1.displayName and codename1.packageName, and the icon is common/icon.png. Text that names the service on screen, such as the title of the welcome screen, is ordinary translated text: search the bundles in src/main/l10n for it.

The colors are the variables at the top of theme.css. Changing the brand color and its dark twin recolors every button, link and selection:

The map’s pins, car and route take their colors from the WlMarkerPickup, WlMarkerDropoff, WlMarkerCar and WlRoute styles in the same file.

The prices start as settings and are the ones in force until an admin saves the pricing screen, which writes them to the database. To start a deployment with your own, set them in backend/application.properties. The amounts are in the currency’s smallest unit:

The currency is a setting only. Rides already taken are recorded in it, and changing it doesn’t convert them.

A fare is the base fare plus the distance and time charges, multiplied for the kind of ride and for surge, and never less than the minimum. The service fee is a percentage added on top for the rider. The commission is a percentage of the fare kept from the driver. Fares.price is the arithmetic, and it’s the place for a different pricing model, such as fixed prices between zones or a price for each stop.

Surge is one multiplier an admin sets by hand. Nothing raises it when demand is high.

The three kinds of ride are named in several places, and adding or removing one touches each:

How long a driver has to answer and how long the search goes on are settings:

The search distances and the minute after which a silent driver counts as gone are constants at the top of Matcher. The rule itself is in three places: the query in DriverStateRepository.freeInBox, which finds the free, approved drivers inside a box, Matcher.nearby, which keeps those within the radius who fit the ride and orders them by distance, and Matcher.pick, which takes the nearest who hasn’t passed on the ride. A different rule, such as the driver who has waited longest or the best rated within reach, replaces the ordering there. Nothing else in the server knows how a driver was chosen.

DriverStateRepository.freeInBox compares latitudes and longitudes in a bounding box. That’s right for one city on any of the three databases. A service with tens of thousands of drivers online would move that query to a spatial index.

The five documents are the KINDS array in Applications on the server and the list of cards in ApplicationForm in the app. Add a kind to both, such as a vehicle inspection or a background check, and the review screen shows it. The fields of the form are fields of the DriverApplication entity, columns of driver_application and components of DriverApplicationDto. Changing the schema later walks through adding one.

The server checks that an uploaded file is a JPEG or a PNG and under 1.5 MB. It doesn’t read the documents. Whether a license is real is the admin’s judgment, or a verification service you call from Applications.submit.

A development server prints verification codes on its console. Any other server sends them through Twilio, Vonage or MessageBird, and needs an account with one of them. The settings, the limits and how to add another provider are in Text messages.

To add a language, add Bundle_<code>.properties to src/main/l10n, add the code to Lang.CODES in the app, and add it to the LANGUAGES array in Preferences on the server, which refuses a language it doesn’t know. A language written right to left sets the @rtl key in its bundle, as the Hebrew one does.

These are things the sample doesn’t have, and a ride-sharing product needs:

A station with twelve cars and a dispatcher is a smaller service with different rules. The drivers are known, bookings arrive by phone as well as from the app, a person decides who takes which ride, and most rides are paid in cash or put on a company’s account. The sample covers the riders' app, the drivers' app, the fares, the receipts and the console. The rest is described here, with the class each change belongs in.

Nobody applies to drive. An admin makes an account a driver directly: the Driver switch on an account in People calls Accounts.setRoles, which gives the role and records an approved application for it. A driver made this way is of the standard kind and has no car details. To record each car, fill in the application’s vehicle fields from an admin screen of your own.

To close the open door:

A dispatcher needs more than a driver and less than an admin, which is a fourth role. Add it to Roles, to the role switches in Accounts.setRoles and UsersForm, and give its paths a rule of their own in the API chain that Who may do what shows. Above the rule for /api/driver/, add one that admits the dispatcher and the admin to the dispatcher’s paths: .requestMatchers("/api/dispatch/").hasAnyRole(Roles.DISPATCHER, Roles.ADMIN). If only staff create accounts, the rule for registration changes too, from permitAll() to hasRole(Roles.ADMIN).

Then declare the dispatcher’s calls in a new @RestClient interface in shared, such as DispatchApi, and implement the interface the server’s build generates from it.

Automatic matching is two calls to Rides.search: one at the end of Rides.request and one for each waiting ride in Rides.tick. Remove both and a requested ride waits in REQUESTED until somebody assigns it. Keep the part of tick that takes back unanswered offers.

Assigning is the same move the matcher makes, with the driver chosen by a person. This is the transaction in Rides that makes it for the matcher:

An assign method for the dispatcher is a pair, the way the other moves are. Its private @Transactional half does what offer does with the driver the dispatcher picked, holding the driver first and calling tryMove with RideState.OFFERED, the driver and the time the offer lapses. Where offer answers null, assign answers 409, so a dispatcher who picked a busy driver, or a ride that somebody else assigned first or that the rider cancelled, is told. The public half runs it through attempt and passes the Change it returns to tell, as cancelByRider does. tryMove records the event in the ride’s history, and tell has the driver’s screen show the offer at once. The driver’s app needs no change: an offer is an offer whoever made it.

Two settings matter once a person does the matching. wayline.search.seconds is how long a ride may wait before it becomes NO_DRIVERS, and ninety seconds is too short for a dispatcher on the phone. wayline.offer.seconds is how long the driver has to answer.

The dispatcher’s screen is a list of waiting rides beside the live map. Both exist: AdminRidesForm lists rides, FleetForm shows the cars, and Console shows how a list and a detail sit side by side in a wide window.

Rides.request takes the rider’s account name as its first parameter, and the rider’s endpoint passes the caller. A dispatcher’s endpoint passes the customer instead, so a booking entered by staff is the same ride with the same fare rules. Two checks in that method are written for riders booking for themselves and need a decision:

The pickup and the destination come from the same place search the rider’s app uses, GeoApi, so the booking form can reuse PlaceSearchForm.

Cash is already a payment method. It’s the default for an account with no saved card, the driver’s screen says how much to collect, and the ride is recorded as paid. A station that takes no cards removes Add a card from WalletForm and never configures a payment provider.

Riding on account, where a company is invoiced at the end of the month, is a method the sample doesn’t have. Cash shows the pattern: Payments.CASH is a method id that Payments.settle records as paid without asking the provider. An account method does the same and records which customer to invoice, which needs a table for the customers and a column on the ride. They go in a new migration, numbered after the last one the project has, with an entity for the table and a field on Ride for the column, as Changing the schema later describes:

Producing the invoice from those rows is yours to write.

Earnings needs a decision too. It credits a driver with the fare less commission for every completed ride, cash rides included, as if the service had collected the money. For drivers who keep the cash they collect, subtract cash fares from the balance, or the ledger says the station owes money it never held. For drivers on a wage, remove EarningsForm from the driver’s menu.

Every payment goes through one interface on the server, PaymentProvider:

The shape is the one card processors share. A rider is a customer of the processor. A card is saved to that customer once and comes back as a token. From then on the server charges the token with nobody present, which is what lets a ride be paid for as it ends. The server stores the token, the brand and the last four digits.

Payments is the service that uses the interface. It keeps the saved methods, charges the fare and the service fee when a ride completes, charges a tip once, refunds, and builds receipts. Every charge carries a key made from the ride’s id, so a request repeated after a timeout can’t charge twice.

A ride completes in one transaction and its payment is written in another, with the charge between them. A server that stops between the two leaves a completed ride whose payment is still pending. Rides.settleLeftBehind runs every minute, finds such rides once they’re two minutes old, and settles them. Because the charge is keyed by the ride, a card that was already charged isn’t charged again.

A charge can also fail without saying whether the card was charged: the provider wasn’t reached, or its answer was lost. Only a PaymentDeclinedException is recorded as a failed payment. Any other failure leaves the ride pending, and the same pass asks again every minute for 23 hours, which is inside the day a provider keeps a charge’s key. After that the ride stays pending for a person to look up. A tip works the same way: a declined card takes the tip off the ride, and any other failure leaves it there with no charge recorded, so the rider can send the same tip again under the same key. The ride can’t be refunded until then.

A refund can also be taken without being finished. Stripe answers some refunds pending and only later says whether the bank returned the money, and a pending refund can still end failed or canceled. PaymentProvider.refund reports such a refund as pending, and the payment and its ride are then REFUND_PENDING, not REFUNDED: the receipt says the refund is pending, and the ride can’t be refunded again. Payments.settleRefunds runs every minute and asks the provider about each one through PaymentProvider.refundStatus. Once the fare’s refund and the tip’s have both succeeded the ride is REFUNDED. If either fails, the ride is REFUND_FAILED and isn’t tried again: part of the money may have gone back, so it takes a person with the provider’s records to settle it. A ride in either state earns its driver nothing.

While a ride’s charge is being asked about, the card it was sent to can’t be removed and the account can’t be closed: Payments.remove and Payments.forget answer 409. The retry looks the card up by its token, so with the card gone it couldn’t ask.

Closing an account also deletes the rider’s record at the provider, through PaymentProvider.forgetCustomer, in the same transaction that deletes the rest. A provider that can’t be reached fails the closure and leaves the account as it was. A record that’s already gone counts as deleted, so closing again finishes a closure that was interrupted.

Removing a card works the same way for that one card. Payments.remove asks PaymentProvider.detachCard to take the card off the rider’s record before it deletes the row, in the same transaction. A provider that can’t be reached leaves the card saved, and a card that’s already detached counts as detached.

Each card setup is a session made at the provider. An account can have five open at once, and a sixth is refused with 429 until one is finished or an hour has passed. Payments.sweepSetups runs every ten minutes and deletes the finished setups and the ones abandoned more than two hours ago.

The limit of eight cards is checked again when a setup finishes, because several setups can start while there’s room for one. By then the provider has already attached the card, so when the limit refuses it, Payments detaches it with PaymentProvider.detachCard after the refused transaction has rolled back. If that detach fails, the server logs the card’s token and still answers 409.

Two implementations come with the sample, and the setting wayline.payments.provider chooses between them:

Without the setting, a development profile (dev, test or local) gets simulated and any other profile gets stripe. A provider that can’t be set up isn’t replaced with anything. With stripe chosen and its key missing, or with a name that’s neither, the server starts, logs a configuration error that names what to set, and logs it again on every payment call, each of which fails. The rider is told payments are unavailable, and no ride is charged to a card nobody can reach. A production server never falls back to simulated cards.

Choose Stripe, set the key in the server’s environment, not in a file in the repository, and tell the server the address it’s reached at:

The first line is what a production profile chooses anyway, and a development profile needs it to use Stripe at all. The second reads the key from the environment variable WAYLINE_PAYMENTS_STRIPE_SECRET. The server reads that variable for this setting without the line as well, since every setting is read from the environment under its name in upper case with an underscore for each dot. The third line is the address Stripe sends the browser back to. It’s needed only when that address differs from the issuer, which the server uses otherwise. With the key or both addresses missing, every payment call fails with the configuration error described above.

StripePayments calls Stripe’s REST API directly and uses no SDK:

The sample stops well short of a billing system. In rough order of need:

A second processor is a second class that implements PaymentProvider. StripePayments shows what a provider with a page of its own does where the simulated one takes a typed card. Its setup creates a session on the provider’s side and hands back the address of the provider’s page:

The app opens the provider’s page for any setup that says it’s hosted, so it needs no change. Services is where the server picks an implementation from wayline.payments.provider, and a new provider is one more name there:

The name a provider returns from name() is what the app is told, and is how it knows whether to show a card form or open a page.

A provider that takes the card inside the app through its own mobile SDK is a bigger change. The setup then happens in native code in the app, and the server is sent a token, not a typed card.

A phone number is verified with a six-digit code sent by text message. PhoneVerification makes the code and checks it, and hands the sending to an SmsSender, an interface of two methods: send(phone, text) and delivers().

The setting wayline.sms.provider chooses the implementation, and Services.smsSender builds it:

Without the setting, a development profile gets console and any other profile gets twilio. The development settings say so outright:

Name the provider and give it its settings, with the secrets read from the environment:

The server reads every setting from the environment as well, under its name in upper case with an underscore for each dot, so wayline.sms.vonage.secret is also WAYLINE_SMS_VONAGE_SECRET. Keep keys, tokens and secrets there and not in a committed file. Nothing in the app changes when the provider does.

A provider that can’t be set up isn’t replaced with the console. With a setting missing, with console asked for on a production profile, or with a name that’s none of the four, the server uses MisconfiguredSmsSender. It logs a [config] line naming what to set when the server starts and again on every message, and every message fails, which the verification answers with 503. A server whose provider was forgotten verifies nobody, rather than everybody.

On a development profile with the console sender, the server also returns the code to the app, which shows it on the verification screen so a demo needs no phone. With any other sender, or on any other profile, the code is never returned.

These are in PhoneVerification and SecurityConfig:

The ten-in-ten-minutes limit uses an InMemoryRateLimiter, so it’s counted in each server process. The other limits are in the database and hold across instances.

The interface is all a provider has to implement:

Another provider is another class, with delivers() answering true. The three that come with the sample have one shape: a form posted to the provider’s API. VonageSmsSender is the shortest:

send throws an IOException when the provider refuses the message, and PhoneVerification turns that into the 503. Services.smsSender then needs one more name for wayline.sms.provider, built the way the Vonage one is:

A message costs money and a number can be anyone’s, so before going live decide which countries you send to and add that check to Accounts.phone, which accepts any number of seven to fifteen digits.

The live channel tells an app that’s open. A push notification is for the phone in a pocket: the rider whose driver has arrived, the driver who has been offered a ride. The server sends them through the Codename One push service, which delivers to Firebase, APNs and Huawei, and the app receives them with PushClient. Codename One Push Notifications covers the push service and the Console, and Sending push notifications the server’s side of the API.

Each phone registers with its platform’s push service when the app comes to the foreground, and hands the token it gets to the server for whoever is signed in. Signing out takes it back first, so the next person to use the phone isn’t told about the last one’s rides. That’s Notifications in the notify package:

The two calls are part of AccountApi:

A token is the provider’s own, so the server stores it with the provider’s name. PushDevices keeps one row per phone: a phone that changes hands moves to the account that signed in on it last, and an account keeps its eight most recent phones. Closing an account removes them all.

A tapped notification opens the app on the screen that shows the ride, which then reads the ride from the server as it does when it’s opened any other way:

The app registers only on Android and iOS devices, and only with its push key set. The simulator has no push service to register with, and a page in a browser hears everything over the live channel while it’s open.

Rides tells RidePushes of every change to a ride once the change is committed, at the same moment it tells the live channel:

A notification is a courtesy on top of what the app reads from the server, so nothing that goes wrong sending one fails the change it’s about. RidePushes decides who hears what:

Every message carries the ride’s id, its state and whether it’s for the rider or the driver, so the app knows which screen to open. Each ride and role has its own collapse key, so a phone that was out of reach shows the latest step and not every one. An offer to a driver lives only as long as the offer, fifteen seconds by default: one delivered later would offer a ride that’s gone.

The switches under Notifications in the app’s settings decide what’s said. A switch that’s off silences the notification and nothing else, so the lock screen still follows the ride:

wayline.push.provider chooses how notifications leave the server, and Services.pushSender builds the sender:

Without the setting, the test profile gets recording, the other development profiles get console and any other profile gets cloud:

To turn it on, give the server the two values, with the key read from the environment:

Then put the push key the Console shows for the app in AppConfig.PUSH_APP_KEY, and configure each platform’s credentials in the Console as Codename One Push Notifications describes.

A server that’s missing a setting still starts and serves rides; the sender it gets instead, MisconfiguredPushSender, logs a [config] line naming the setting when the server starts and again for every notification it can’t send. CloudPushSender sends on a thread of its own, so a ride’s request never waits on the push service, and it logs a refusal rather than throwing it:

To send through another service, implement PushSender, one method, and return it from Services.pushSender:

While a driver is on the way, the rider’s ride shows outside the app: a Live Activity on the lock screen and on the Dynamic Island of an iPhone, an ongoing notification on Android, and a small window on the desktop and in the simulator. A browser shows none. External Surfaces: Widgets and Live Activities covers the API.

RideCard in the rider package starts it when a driver accepts, moves it on with every change the rider screen sees and ends it with the ride. A finished ride stays on the lock screen for a while with its last state; a canceled one goes at once. Starting one is a round trip to the system, so it runs off the event thread, and the activity’s id goes to the server:

The layout is data. The app sends it once when the activity starts, with ${key} placeholders the platform fills from the state, so an update is a few short strings and a number. The keys are constants in RideActivityKeys in shared, because the server writes the same state:

Once the app is in the background the server keeps the activity current. It records the activity’s id against the ride, but only the rider’s own ride and only while a driver is bringing or carrying them:

Each change of state then carries the activity’s new state in the same notification that announces it, and the end of the ride ends the activity. In between, the driver’s position reports move the minutes on in a silent message, no more often than wayline.push.activity.seconds, 45 by default. A conditional update of the ride’s row decides whether one is due, so two servers receiving reports at once send one update between them.

The app’s push client applies such a message when the Codename One runtime receives it, before the listener runs. Where the platform doesn’t start the app for a push in the background, the message waits and is applied when the app next starts or resumes. Apple’s own route for a server to update a Live Activity, the ActivityKit push token, isn’t used, so on an iPhone the activity of an app iOS has suspended is only as current as the last message the app received. While the app is open, the rider screen keeps it exact itself.

The app declares the Live Activity in surfaces.json, in src/main/resources of common:

ios.surfaces.frequentUpdates among the build hints below asks iOS for the frequent updates a moving car needs.

A driver who switches to a navigation app or locks the phone is still driving, and the server stops offering rides to a driver it hasn’t heard from for a minute. While a driver is online, Shift in the driver package keeps the position going to the server with the app in the background:

DriverForm begins the shift when the server says the driver is online and ends it when they go offline; signing out and switching to the rider’s side end it too. Reports go through the same call the driver screen makes in the foreground, so the server needs nothing new. They’re spaced by distance and time, 25 meters or twenty seconds, which is what keeps the battery cost down: the car’s position changes far more often than the server needs to hear of it.

Locator asks the platform for the precise, frequent fixes a driver needs only while a shift is on, and lets go of location altogether when the app is in the background without one:

These are the build hints the three features need. The project already has them in common/codenameone_settings.properties:

Both app stores review background location. Apple asks what the location is used for while the app is in the background, and Google Play asks for a declaration and a video of the feature in use. A driver app has a good answer, and the usage description should give it in the driver’s terms.

Out of the box the server is its own authorization server: accounts and passwords are in its database, and the tokens the API accepts are the ones it signs. A product often wants people to sign in with an account they already have, at Google, Microsoft Entra ID, Auth0 or a Keycloak of its own. There are two ways to do it, and they differ in who issues the token the API sees.

The first is the smaller change and keeps password accounts working. Choose the second when the organization already manages its people, and their roles, in the provider.

The server keeps issuing its own tokens and leaves it to the provider to identify the user. On the server that’s oauth2Login on the sign-in chain, with the provider’s client id and secret in the configuration:

A registration called google or microsoft needs only the id and the secret. Auth0 and Keycloak are described by a provider block with their issuer-uri, as the acme registration is. The secret belongs in the environment.

Wayline’s accounts are named by e-mail address, which is what LinkingOAuth2UserService matches on: a person whose provider vouches for the address of an existing account signs in as that account, with its roles.

In Wayline the oauth2Login call goes on the signIn chain in SecurityConfig, beside formLogin. Signing in through another provider covers the registration keys and the linking rules. Two things are particular to Wayline:

In the app, Session.authenticate posts the e-mail address and password to /login and then asks for the code itself, with no browser. A provider’s sign-in page has to be shown, so that path changes to the browser flow of OidcClient. Session already builds the client with OidcClient.create. The sign-in becomes a call to authorize():

The redirect address of that flow is the app’s, and it differs by platform:

Each address the app uses has to be on the registered client. Add the scheme address with another redirectUri call where SecurityConfig.clients builds the RegisteredClient, and return it from AppConfig.redirectUri() on a device. The client is saved only when the database has none with that id, so a database that already holds the registration keeps the old list until the stored client is updated.

With this approach the provider issues the tokens and the server only validates them.

The app. Build the client from the provider’s metadata instead of from Wayline’s endpoints, with the client id the provider issued:

OidcClient.discover works with any provider that publishes OpenID Connect metadata. Keep the OidcRequestAuthorizer that Session installs on the API’s address. It attaches the token and refreshes it whatever the issuer is. The redirect addresses are the ones in the table above, registered with the provider this time: the scheme address for the installed apps and the https address of the hosted app. Register the app as a public client, with no secret.

The server. The API chain stops building a decoder from its own keys and validates the provider’s tokens:

Set audiences to the identifier the provider puts in the access token’s aud for your API. In SecurityConfig.api, drop the DefaultJwtDecoder built from the signing keys and the decoder call, and the chain uses the one these properties describe. The signIn chain, the clients bean and SignInCodePage are no longer used. A JWT resource server covers the keys, what’s verified and a server that trusts several issuers.

The API needs an access token that’s a JWT the server can verify with the provider’s published keys. Check what your provider issues for an API of your own before choosing this approach. A provider whose access tokens are opaque, or meant only for its own APIs, fits the first approach.

What goes with it. Registration, the password change and the password check before deleting an account all work on Wayline’s own user store. With a provider in charge of the accounts, a person’s first request has to create their profile, and the password screens go.

The API rules ask for RIDER, DRIVER and ADMIN. Where those come from is the JwtAuthenticationConverter on the API chain, and there are two choices.

Keep the roles in Wayline’s database. The converter in SecurityConfig ignores the token’s claims and loads the account named by the token’s subject on every request. A provider’s subject is an opaque id and not an e-mail address, so tell the converter which claim names the account with setPrincipalClaimName, and use a claim the provider has verified. Driver approval, an admin’s grant and a block all keep working as they do now, and they take effect on the next request.

Read the roles from the token. Have the provider put the roles in a claim and map the claim:

With the ROLE_ prefix, a claim holding RIDER, DRIVER or ADMIN matches the rules unchanged. JwtGrantedAuthoritiesConverter reads a claim holding a flat list of names. Each provider has its own way to add such a claim to a token and its own name for it, so configure the provider to send one and check a token from your own tenant.

The cost of this choice is timing. A role withdrawn at the provider is still in every token already issued and holds until the token expires, and the same is true of a blocked account. Wayline’s flows also grant roles themselves: approving a driving application makes a driver, and the admin screens grant and withdraw admin. With roles in the provider, those two steps have to change the roles there, or the driver role has to stay in the database. A reasonable split is ADMIN from the provider and RIDER and DRIVER from the database, which a converter of your own can combine.

The app reports how it’s used through the framework’s analytics API, which Analytics documents. Everything it does is in one class, Telemetry, so that’s the file to read and the file to change.

Nothing is reported until the user agrees. After the first sign-in, ConsentForm asks once, with Share usage statistics and Not now. The answer is kept on the device, not with the account, and the Usage statistics switch under Privacy and safety in the settings changes it at any time. Telemetry passes the answer to Analytics.setConsent with analytics and crash reporting set to the answer and personalization and advertising storage always off. Consent and privacy describes what each of those gates.

Deleting the account calls Telemetry.forget, which resets the anonymous id the reports carry.

Every screen reports a screen view. Beyond that the app reports these events:

Two user properties go with them, the role and the language. An uncaught error is reported with Analytics.crash and carries the exception’s class name alone.

No event carries a name, an e-mail address, a phone number, a street address, a position, a card number or a ride’s id. Money and distance are reported as brackets and never as amounts. Keep to that when you add an event: add a method to Telemetry and call it from the screen, so the list of what leaves the device stays in one file.

Telemetry.start registers LoggingAnalyticsProvider in the simulator and CodenameOneAnalyticsProvider everywhere else. A run in the simulator writes its events to the console and sends nothing. The Codename One provider identifies the app from properties the build puts into it, which a local run doesn’t have. A built app reports to Codename One, and the reports are shown in the developer console.

To send the events somewhere else, register another provider in Telemetry.start. Analytics lists the ones the framework has and how to write one.

Place search goes through your server so that the app never sends what a user types to a third party directly, and so that you can change the service without shipping a new app.

When a route can’t be fetched, the app draws a straight line between the two points and estimates the time from the distance. The server prices from its own estimate whenever the app’s figures aren’t plausible, so a failed route changes what the rider sees and not what they pay.

All three are run by other people at no charge. They’re the right choice for development, a demo and a pilot, and they need a decision before a launch:

None of them knows about traffic. The time the app shows and the time part of the fare come from distances and typical speeds.

Tiles and routes are chosen in the app. Maps.create builds the map, and Routing.setService replaces the route service for the whole app:

A keyed tile provider takes its key with setApiKey, and a provider that isn’t OSRM-compatible is an implementation of RouteService. The Maps chapter covers both.

Place search is chosen on the server:

That points PhotonGeocoder at a Photon server you run. A different search service is another implementation of the Geocoder interface, chosen in Services.

A device that reports its position opens the map there. Until it does, and in a browser that won’t say, the map opens on AppConfig.DEFAULT_LAT and DEFAULT_LNG, which is San Francisco’s northern waterfront. Change them to your city.

Everything a development server shows on first start is made by two classes.

DemoAccounts creates the accounts when the server starts. On a development profile, which is dev, test or local, it creates the riders, the drivers, the applicant and the admin, gives the drivers approved applications with cars and placeholder documents, and saves a simulated card for some riders. On any other profile it creates one account and no more: the first admin, from wayline.admin.email and wayline.admin.password.

DemoRides stores two weeks of rides as entities, already finished: three to six a day between ten places in San Francisco, about three quarters of them completed, with their events, payments and ratings, and a payout of the first week’s earnings. The sequence is fixed, so every start produces the same fortnight ending today. That’s what the dashboard’s charts draw on a fresh server.

The cars a rider sees are real drivers who are online. Nothing on the server invents traffic. To see a car move, sign in as a driver in a second simulator and go online. In the simulator the app has no position, so it stands at the default one, and the driver’s screen drives the car along the route itself at 25 meters a second.

To use your own data:

The app’s tests use 24 vector tiles of the same waterfront, stored in common/src/test/resources. They aren’t part of the app. Maps.useTiles is the hook that swaps them in.

The sample draws its map with MapView, the vector map that Codename One renders itself. It looks the same on every platform, the app’s bottom sheet and buttons float over it, and its light and dark styles follow the app.

NativeMap shows the platform’s own map instead: Apple MapKit on iOS, and Google Maps or Huawei Map Kit on Android. It has the same MapSurface operations as MapView, and it falls back to a MapView where no provider is available, which includes the simulator, the desktop and the browser. Native maps and providers documents it.

Three changes move Wayline to it.

First, select a provider for each platform with build hints in common/codenameone_settings.properties:

Apple MapKit needs no key. Google Maps needs an API key for each platform, supplied through the build hints the Maps chapter lists.

Second, create the map as a NativeMap in Maps.create. The tile source and style passed to it are what the fallback uses:

MapStage.map, the CarMarker constructor and the helper methods of Maps are declared with the type MapView. Change them to MapSurface, which has the camera, marker and line methods they call. The few calls that treat the map as a component, such as repaint and getHeight, go through asComponent().

Third, change how the car moves. CarMarker glides a marker by setting its position twenty times a second. A native provider is told about a marker when it’s added and isn’t told when its position changes, so on a native map the marker has to be taken off and put back:

Do that a few times a second, not twenty: every move is a call into the platform’s map.

The sample hasn’t been built with a native provider, so treat this as the route to take and test it on devices. What you gain and give up:

The server runs on SQLite, PostgreSQL, MySQL and MariaDB with the same code. It reads one setting, cn1.datasource.url:

The setting is also read from the environment, as CN1_DATASOURCE_URL and as DATABASE_URL, which is the name a hosting platform usually sets for a database it attaches. backend/application.properties sets the key to ${DATABASE_URL}, so a deployment supplies the address in its environment and no address is committed.

To keep data between restarts while developing, give the dev profile a file:

To run against PostgreSQL or MySQL, give the server a URL. Nothing else changes, and there’s no driver to add:

The server holds a pool of connections. cn1.datasource.pool.size sets how many: eight for PostgreSQL and MySQL unless set, four for a SQLite file and one for an in-memory database. A request that finds no free connection waits cn1.datasource.pool.borrowTimeoutMillis, ten seconds unless set, and then fails. Every server process has a pool of its own, so the processes times the pool size has to stay under the number of connections the database allows. Backend data access and transactions covers the pool, and the table of settings in Configuration and profiles lists these keys with the rest.

The sample’s own tests run on the test profile, which is an in-memory SQLite database. Run the server tests against the engine you deploy on before you rely on it there.

The tables are created by the migration scripts in backend/src/main/resources/db/migration, which run in order when the server starts. Schema migrations describes the rules.

The sign-in tables are separate. The security layer creates them because cn1.security.schema.enabled is set, as Keeping it in the database describes.

Five of the six scripts are written once, in SQL that all three engines accept. They use no generated keys and no boolean or timestamp types: an id is text the server makes, a yes or no is a SMALLINT of 0 or 1, and a time is milliseconds in a BIGINT. That’s also how the ORM stores a boolean and a long field, so the entities and the columns agree on every engine.

V3__driver_documents.sql is the exception, and it shows what the per-engine directories are for. A document is stored as text, and it outgrows the 64 KB of MySQL’s TEXT. MySQL needs LONGTEXT, a type the other two don’t have. For that reason the script isn’t in db/migration itself. It exists three times under the same name, in db/migration/sqlite, db/migration/postgresql and db/migration/mysql, and the server runs the one for the engine it’s connected to. MariaDB reads the mysql directory. A version is either one common script or one script for each engine, never both.

A change to the schema is a new script with the next version number. The next one is V6, and the two underscores before the description are part of the name. A child seat a rider can ask for is V6__child_seat.sql:

A column added to a table that already has rows needs a default, as child_seat has here. ADD COLUMN with a NOT NULL default is accepted by all three engines, so a script that sticks to it stays a common script. When the SQL has to differ, put the script in the three engine directories under one name, as V3 does, and leave it out of db/migration itself.

Add the field to the entity in the same change. The migrations create the columns and the entities read them, and neither is derived from the other. The option to bring a pet is the column of ride the child seat would sit beside, and in Ride it’s one private field:

The child seat is a childSeat field written the same way, with an isChildSeat and a setChildSeat beside the getter and setter pets has. The field’s name in snake case is the column’s, so childSeat reads child_seat with nothing more said.

A new table gets an entity class of its own in domain as well, as the customers of Cash and accounts do. The server tests start from an empty database and run every migration, so RideFlowTest and the others fail on an entity and a script that disagree.

What happens when the new build starts:

Never edit a script that has been applied. The server checks the applied scripts against the ones in the build before it migrates, and refuses to start on a difference. A mistake in V6 that has reached a database is corrected in V7. Before a script has left your own machine, delete the development database and start again. An in-memory database starts from nothing every time.

A script that removes a column should ship one release after the build that stopped reading it. While a deployment replaces its instances one at a time, the old build runs against the new schema.

The script and the entity field above are the first two of the places a piece of data touches. The option to bring a pet is already in the sample and shows every one, so follow it for the child seat, a flight number or a cost center.

The schema. pets is a SMALLINT column of ride, in V4rides.sql, and of driver_application, in V2drivers.sql. For new data it’s a new script, as V6__child_seat.sql is.

The entities. Ride.pets and DriverApplication.pets are private boolean fields with a @Column, as childSeat is.

The services. Rides.open, the transaction of Rides.request, copies petFriendly from the request to Ride.pets, and Rides.toDto copies it into the ride the app is sent. Because the pet option also decides who is offered the ride, Matcher.pick passes Ride.isPets to Matcher.nearby, which drops every driver whose application doesn’t take pets.

The contract. The value is a component of the record in shared that carries it, petFriendly in RideRequestDto, and of RideDto so the driver sees it. A child seat is a boolean childSeat component beside it in each, with a line for it in the record’s comment. Every place that builds one of those records then passes the new value, and the compiler lists each place that doesn’t.

A component needs nothing else. Both builds regenerate the JSON code for the record.

The endpoint. A new field on an existing call changes no endpoint. A new call is a method on the @RestClient interface and its implementation on the server, and the server’s build fails until the two match.

The app. SettingsForm has the switch, Prefs keeps its value, RiderForm copies it into the request, and DriverForm shows it on the offer. The label is a key in each of the five bundles in src/main/l10n.

The tests. MatchingTest on the server checks that a ride with a pet is offered only to a driver who takes pets.

More data about a person follows the same path through Profile, profile and ProfileDto, about a driver’s car through DriverApplication, driver_application and DriverApplicationDto, and about the service’s prices through Pricing, pricing and PricingDto. A new kind of record gets a table, an entity, a repository, a class in shared, and a service.

A deployment that suits a new service is a managed PostgreSQL and the server’s native binary in a small container or virtual machine, behind the platform’s HTTPS proxy. The steps are the same on any platform that runs a container or a process and attaches a database to it.

Build. backend/server.sh build --native --web runs cn1:backend-package, which writes the binary to backend/target/wayline-server, and cn1:backend-webapp, which stages the browser app in backend/target/webapp. The binary is built for the machine the build runs on, so build on the architecture you deploy to, or use the cross-compiled targets Backend performance, deployment and limits describes.

Lay it out. The server reads its settings and looks for the browser app in its working directory. Put the binary, application.properties and the webapp directory side by side, as Hosting the app in the browser shows, and start the binary from that directory. Leave webapp out and the server is the API alone.

Create the database. Create an empty PostgreSQL database and a user that owns it. The server creates every table at its first start, which takes a user that may create tables. Don’t create anything by hand: a database that has tables and no migration history is refused.

Set the environment. Nothing secret belongs in application.properties, which is committed. A setting is read from the environment under its name in upper case with an underscore for each dot.

The same settings as properties, for a platform that mounts a file instead:

Leave TLS to the proxy. The platform’s proxy holds the certificate and forwards plain HTTP to the port. Two things follow. The issuer is the address users reach, which is the proxy’s https address and not the container’s. And the server sees every connection coming from the proxy, so the limit on sign-in attempts for each client address would count all users as one. Set cn1.server.forwardHeaders to true and list the proxy’s addresses in cn1.server.trustedProxies, as Client addresses behind a proxy describes. A server with no proxy in front terminates TLS itself with cn1.server.tls.certificate and cn1.server.tls.key.

Give the platform a health check. GET /manage/health answers without a token, with 503 while the server is starting or draining. The management endpoints are linked into a packaged server only when cn1.management.enabled is true in backend/application.properties at build time, and outside a development profile they also need cn1.management.token set. Backend tracing, metrics and management covers both.

Start it. The first start applies the five migrations, creates the sign-in tables, registers the app as a client and creates the first administrator. No demo accounts and no demo rides are written outside a development profile.

Point the apps at it. The hosted browser app uses the page’s own origin and needs nothing. An installed app takes the address from Server address on the welcome screen. To build an app that needs no such step, change the address AppConfig falls back to, and remove the Android clear-text attribute listed in Before it’s a product.

What’s rate limited. SecurityConfig limits registration, the phone codes, the password change, the document uploads, the card setups and the address search under /api/geo. Each search is a request the server makes of the geocoder you configured, so the limit protects that service’s allowance and not only this server.

Before a second instance. A change of ride state, the matching job and the migrations are each safe with several processes on one database. Two things are held in one process’s memory: the open sockets in LiveHub, and the counters of the InMemoryRateLimiter that SecurityConfig gives each rate limit, so every instance allows the full number of attempts.