You are reading GraphMaquina 2.0.3. The latest version is 2.0.6.

Compose machines across modules and JARs

A machine can watch, or bind as its sub-machine, a machine that another module compiled and published: a jar the consumer receives, or the directory of classes of another module. The consumer declares the relation on its own side, with @GraphPeers, exactly as for a machine of its own compilation. The pair's vocabulary stays typed, and the build checks the relation against what the producer published, without the producer's sources. The machines still run in one application, under one GraphMaquina runtime: separate artifacts add no remote call and no distributed coordination.

This page follows two scenarios. A producer publishes a payment machine and an item machine and knows nothing of its consumers. A consumer binds a payment as the deposit of a booking, and has an order watch its items. The scenario sources are compiled apart, the consumer against the producer's jar alone, and run by CrossModuleCompositionTest; every Java block below is a verbatim copy of them.

Contents

What the producer publishes

Module Packages Declares
Producer pay, stock Payments over Payment, Items over Item
Consumer book, shop, app Bookings, Orders, their lookups, the set Store and the Scenario that runs it

The producer's machines are ordinary machines. This is Payments, which names no booking and declares no peer:

@GenerateGraphApi
@PaymentsGraph.Definition(
    initial = PENDING,
    terminals = {CAPTURED, DECLINED},
    state = PaymentRefs.Status.class,
    id = PaymentRefs.Id.class)
@PaymentsGraph.StatePolicy(state = PENDING, otherwise = "a payment is captured or declined")
public interface Payments extends Machine<Payment, PaymentStatus, PaymentTransition> {

    @PaymentsGraph.Transition(id = CAPTURE, from = PENDING, to = CAPTURED)
    Outcome<Payment, PaymentStatus, PaymentTransition> capture(Payment payment);

    @PaymentsGraph.Transition(id = DECLINE, from = PENDING, to = DECLINED)
    Outcome<Payment, PaymentStatus, PaymentTransition> decline(Payment payment);
}

Items has the same shape: an item is OPEN until PACK takes it to PACKED. For a consumer to use them, the build must meet four requirements, the first three on the producer's artifact and the last on the consumer's classpath:

Multiple modules and published JARs lists the steps of a build of several modules.

Bind a machine of a jar as a sub-machine

The consumer's booking holds a payment of the producer in DEPOSIT: booking it starts the payment, and the terminal state the payment reaches selects the booking's exit. The whole binding is declared on the consumer's Bookings, which names the producer's Payments as its peer:

@GenerateGraphApi
@GraphPeers(Payments.class)
@BookingsGraph.Definition(
    initial = REQUESTED,
    terminals = {CONFIRMED, CANCELLED},
    state = BookingRefs.Status.class,
    id = BookingRefs.Id.class)
@BookingsGraph.StatePolicy(state = REQUESTED, otherwise = "a booking is booked first")
@BookingsGraph.StatePolicy(state = DEPOSIT, otherwise = "the deposit payment decides")
@BookingsGraph.Transition(id = DEPOSIT_PAID, from = DEPOSIT, to = CONFIRMED)
@BookingsGraph.Transition(id = DEPOSIT_DECLINED, from = DEPOSIT, to = CANCELLED)
@BookingsPayments.Submachine(
    state = DEPOSIT,
    child = BookingRefs.Deposit.class,
    parentLookup = BookingLookupsRefs.BookingOf.class,
    exits = {
        @BookingsPayments.Exit(on = PaymentStatus.CAPTURED, transition = DEPOSIT_PAID),
        @BookingsPayments.Exit(on = PaymentStatus.DECLINED, transition = DEPOSIT_DECLINED)})
public interface Bookings extends Machine<Booking, BookingStatus, BookingTransition> {

    @BookingsGraph.Transition(id = BOOK, from = REQUESTED, to = DEPOSIT)
    Outcome<Booking, BookingStatus, BookingTransition> book(Booking booking);
}

The generator writes the pair's vocabulary, BookingsPayments, from what the producer's export index says of Payments, so on takes a PaymentStatus and transition a BookingTransition, as within one compilation. Compose machines explains each element. Across modules, the way to the child and the way back follow from the producer knowing no booking. child is a property of the consumer's entity that returns an Optional of the child's entity:

/** The payment of the deposit: the sub-machine that {@code DEPOSIT} holds. */
@GraphProperty
public Optional<Payment> deposit() {
    return Optional.of(deposit);
}

The way back from a payment to its booking cannot be parent, a property of the child's entity that returns the parent's, since the producer's Payment cannot name a Booking. It is parentLookup, a lookup the consumer exports, which finds the booking among those it was told about, where an application would ask its repository:

@GraphLookup
public Optional<Booking> bookingOf(Payment payment) {
    return Optional.ofNullable(bookings.get(payment.id()));
}

The exits are checked against the terminal states the child declares in its jar: one exit per terminal state, each naming an identifier with an edge from the bound state. An exit on PENDING in place of the one on DECLINED is refused with both problems it causes:

[SG801] Bookings.DEPOSIT: the terminal DECLINED of Payments has no exit
[SG801] Bookings.DEPOSIT: the exit on PENDING names no terminal of Payments

An exit whose identifier has no edge from the bound state, as when DEPOSIT_DECLINED leaves REQUESTED rather than DEPOSIT, is refused with the very message it gets when both machines are compiled together:

[SG802] Bookings.DEPOSIT: the exit on DECLINED names DEPOSIT_DECLINED, which has no edge from DEPOSIT

Watch the machines of a jar

The consumer's order watches its items, items of the producer, while it is PAID, and ships once all of them are PACKED. The watch is declared on the consumer's Orders, which names the producer's Items as its peer:

@OrdersItems.Watch(
    state = PAID,
    peers = OrderRefs.Items.class,
    ownerLookup = OrderLookupsRefs.OrderOf.class,
    rules = @OrdersItems.When(allIn = ItemStatus.PACKED, transition = SHIP))

peers is the consumer's Order.items(), a Collection<Item>. The way back from an item to its order cannot be a property of the producer's Item, which knows no order, so ownerLookup names a lookup the consumer exports, of signature Optional<Order> name(Item):

@GraphLookup
public Optional<Order> orderOf(Item item) {
    return Optional.ofNullable(orders.get(item.id()));
}

An empty Optional means the item has no order, and no reaction follows for it. The lookup is static or instance, on any class of the consumer, and returns only an Optional; find the owner with a lookup has the whole contract.

owner is enough when the peer's entity already has a property that returns the owner, as when the producer also publishes the owner's entity, a domain both modules share. With Item, Order and Items in the producer's jar and Orders in the consumer, owner = ItemRefs.Order.class names the item's Optional<Order> order(), as in watch other machines. A watch declares exactly one of owner and ownerLookup; neither or both is SG405.

When the last item commits PACKED, the order is reevaluated after that commit, in a new transaction, as for any watch: triggering and observing watches describes it.

Build the set

The consumer's @StateGraphs set holds its machines and the producer's machines they bind and watch. A set that holds a parent must hold its child (SG806), and a set that holds a watch must hold its peers (SG510):

@StateGraphs
public interface Store extends Machines {

    Bookings bookings();

    Payments payments();

    Orders orders();

    Items items();
}

The generated builder takes the instance hosts of the consumer's machines in the order of the set's accessors: the booking lookups of Bookings, then the order lookups of Orders. The scenario keeps both, to tell them which booking and which order each payment and item belongs to:

public static String run() {
    BookingLookups bookingLookups = new BookingLookups();
    OrderLookups orderLookups = new OrderLookups();
    try (Store store = StoreRuntime.builder(bookingLookups, orderLookups).build()) {
        return deposit(store, bookingLookups) + " / " + packing(store, orderLookups);
    }
}
/** Books a booking, captures its deposit, and reports the states of both. */
private static String deposit(Store store, BookingLookups bookingLookups) {
    Payment deposit = new Payment("deposit-1");
    Booking booking = new Booking("booking-1", deposit);
    bookingLookups.register(booking);
    store.bookings().book(booking);
    store.payments().capture(deposit);
    return booking.status() + " " + deposit.status();
}

/** Pays an order of two items, packs them one by one, and reports the order's state after each. */
private static String packing(Store store, OrderLookups orderLookups) {
    Item first = new Item("item-1");
    Item last = new Item("item-2");
    Order order = new Order("order-1", List.of(first, last));
    orderLookups.register(order);
    store.orders().pay(order);
    store.items().pack(first);
    OrderStatus afterFirst = order.status();
    store.items().pack(last);
    return afterFirst + " " + order.status();
}

run() returns CONFIRMED CAPTURED / PAID SHIPPED: capturing the deposit exits the booking through DEPOSIT_PAID to CONFIRMED; the order stays PAID while one item is still OPEN, and ships once the last one is packed. The same holds when the producer reaches the consumer as a directory of classes that carries the index rather than as a jar.

The set can also live in a third module. With the payments in pay.jar and the bookings in book.jar, compiled against pay.jar, a third module's set Desk that holds Bookings and Payments builds and runs the deposit scenario. Holding Bookings alone, it is refused as a set of one compilation is:

[SG806] the sub-machine of Bookings.DEPOSIT is Payments, which is not in Desk

What is checked, and when

The build checks the relation against the producer's artifact it compiles against:

Step Check Code
Generation, before anything is published An index on the classpath was written by this version, and no two describe one machine SG602
Generation, before anything is published A peer of a dependency comes from an artifact whose index lists it as its classes describe it, over enums, and through supertypes, the consumer's classpath declares SG602
Generation A peer is a machine of this compilation or of a dependency's index, whose types the owner's package can name SG608
Generation No type of the owner's package obscures a package the pair vocabulary writes, such as the peer's SG603
Processor Each exit matches a terminal state of the child and has an edge from the bound state SG801, SG802
Processor The bound state is no terminal state of the parent SG803
Processor No operation of the parent takes, from the bound state, a transition that is an exit of the binding SG804
Processor Each rule of a watch executes a transition that leaves the watched state SG401
Processor A watch declares exactly one of owner and ownerLookup SG405
Processor A parentLookup or an ownerLookup has the signature its binding needs SG505
Processor The set holds each child and each watched peer SG806, SG510

At run time, the classpath can carry another build of the producer than the one the consumer compiled against. Each companion checks its bindings again against the definition of the child it receives, when the set's generated builder builds the graphs, before any call. The consumer above, run with a Payments rebuilt with a third terminal state, VOIDED, fails as StoreRuntime.builder(...) builds the graphs, with an InvalidGraphException that carries one problem:

[SG801] Booking/BookingStatus.DEPOSIT: the terminal VOIDED of Payment/PaymentStatus has no exit

Run with the producer's artifact the consumer was compiled against, or rebuild the consumer against the new one and give its binding an exit for the new terminal state: until it declares one, that build refuses the binding with SG801, which names the terminal state that has no exit.

Diagnostics

Code Across modules it means Remedy
SG602 The producer's artifact carries no export index, one the generator cannot read, one another version wrote, or one that does not list the peer or describes it otherwise than its classes; the peer passes Machine an enum the consumer's classpath does not declare, or has a supertype that classpath does not declare and reaches Machine through none it declares; another machine of the producer passes Machine an enum that classpath does not declare; or two artifacts on the classpath describe the same machine. The generator's message names the jar or directory whenever it can tell it; the processor's, for an enum another machine of the producer passes, names the annotation manifest instead Package the index the producer's build publishes with its classes, rebuild the producer through the complete lifecycle with the consumer's version, add the dependency that declares a missing enum or supertype to the consumer's classpath, or keep one artifact of the producer on the classpath. Build troubleshooting lists the messages and their remedies
SG608 The peer is no machine of this compilation or of a dependency's export index, or the owner's package cannot name its types, as when its state enum is not public Name a @GenerateGraphApi machine whose types the owner's package can reach
SG405 A watch declares neither or both of owner and ownerLookup Declare ownerLookup when the peer's entity cannot name the owner, owner when it can

Next: Commit, hooks, observers and persistence. Back to the documentation index.