Chapter 13. Request Chains

Table of Contents

Available Chains
Strategies for Object Matching
Idempotency of Updating Chains

Available Chains

As demonstrated by earlier examples, to process a given request you need to build an appropriate LinkRest "chain". Each chain starts with a call to a static method of LinkRest class, that determines chain type, parameters it can take, and the type of response it generates. Each chain type naturally maps to a single HTTP method. Although ultimately the mapping of chains to methods is not enforced by LinkRest and is left to the application developer. The following chains are available:

// use with @GET
LinkRest.select(SomeEntity.class, config)...

// use with @DELETE
LinkRest.delete(SomeEntity.class, config)...

// use with @POST
LinkRest.create(SomeEntity.class, config)...

// use with @POST
LinkRest.createOrUpdate(SomeEntity.class, config)...

// use with @PUT
LinkRest.idempotentCreateOrUpdate(SomeEntity.class, config)...

// use with @PUT
LinkRest.idempotentFullSync(SomeEntity.class, config)...

// use with @GET for metadata endpoints
LinkRest.metadata(SomeEntity.class, config)...

Strategies for Object Matching

Many of the updating chains need to match objects coming as Update Documents (see the section called “Request: Update Document”) against objects in the database. E.g. "createOrUpdate" needs to know whether a JSON object is new (and needs to be created) or it already exists (and needs to be updated). By default LinkRest would attempt to match each JSON "id" attribute with a DB record primary key. This is a reasonable and useful strategy. Its main limitation though - it can't be used for entities with ids generated on the server when combined with idempotent requests (see the next section on idempotency). To work around this limitation one may use a meaningful unique property that is known to the client at the object creation time. E.g. our Domain entity has a unique property "vhost".

To ensure the chain uses a property other than "id" for matching, a user may should set an explicit mapper on the chain:

LinkRest.idempotentCreateOrUpdate(Domain.class, config)
    .mapper(ByKeyObjectMapperFactory.byKey(Domain.VHOST))
    .sync(entityData);

ByKeyObjectMapperFactory mapper is provided by LinkRest. If something other than mapping by property is needed, a custom ObjectMapperFactory can be coded by the user.

Idempotency of Updating Chains

It is easy to distinguish updating chains that are idempotent from those that are not (chain factory method starts with "idempotent" for the former). Both work the same way, except that "idempotent" ones perform an extra check on the input to ensure that it is repeatable, i.e. it will be safe to run it multiple times with the same effect as running it once. At the minimum this means that all the "new" objects have their ids set in the request. This is where ByKeyObjectMapperFactory discussed above comes in handy. Pretty much all idempotent chains need to use ByKeyObjectMapperFactory or an equivalent mapper to match by some unique property of the entity, that is known to the client at the object creation time.