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)...
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);
mapper is provided by LinkRest. If something other than mapping by property is needed, a
ObjectMapperFactory can be coded by the user.
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