Servizi aggiuntivi GraphQL

Modello di riferimento #

Tutti gli esempi in questa pagina fanno riferimento al modello in figura:

La classe Employee ha il system versioning abilitato.

Servizi lock e unlock #

In supporto a scenari di modifiche concorrenti, lo schema GraphQL offre due servizi che consentono di acquisire o rilasciare lock sul database relativamente a uno o più oggetti: Mutation.lock e Mutation.unlock.

type Mutation {
  lock(locks: [EntityID!], minutes: Int = 10): LockStatusResult
  unlock(locks: [EntityID!]): LockStatusResult
}

A differenza di altri servizi, questi sono indipendenti dal modello in quanto non vincolati a una specifica classe. Entrambi richiedono in input una lista di input type di tipo EntityID, e restituiscono in output la struttura LockStatusResult. Esaminiamole in ordine:

input EntityID {
  entityName: EntityName!
  _id: ID!
}

L’input EntityID rappresenta un oggetto del database identificato dal suo ID e dal nome della sua classe, riportato nel campo entityName. Questo è di tipo EntityName, un enum contenente un valore per ciascuna classe presente nello schema GraphQL. Ad esempio, per il modello di riferimento, EntityName contiene i seguenti valori:

enum EntityName {
  Address
  Employee
  Project
  Project_assignment
  Qualification
  Team
}

Ciascun EntityID serve quindi a identificare univocamente una risorsa su cui richiedere il lock, oppure di cui si vuole rilasciare il lock. Esaminiamo ora l’output LockStatusResult:

type LockStatusResult {
  locked: Boolean!
  minutes: Int!
}

Questa struttura indica se le entity richieste sono bloccate (locked=true) o sbloccate (locked=false) e per quanti minuti sono bloccate (minutes). Di default, il servizio lock richiede un lock di 10 minuti sulle entity scelte, ma è possibile aumentare (o diminuire) questa durata valorizzando l’argomento opzionale minutes.

Recuperare versioni storiche di un oggetto #

A partire dalla versione di Livebase 5.8.3, per le classi per cui è abilitata la storicizzazione (o system versioning), la struttura <ClassName> viene estesa con i seguenti campi:

type ClassName {
  _id: ID
  _clientId: ID
  _versionStart: Datetime(format: String = "default")
  _versionEnd: Datetime(format: String = "default")

  # attributi, ruoli uscenti, associabili ...
  # ...
}

_versionStart è un timestamp che indica l’inizio dell’intervallo di validità di quella versione (analogo a row_start), mentre _versionEnd indica la fine dell’intervallo di validità di quella versione (analogo a row_end). È possibile richiedere _versionStart e _versionEnd in qualunque servizio che restituisce la struttura <ClassName> (che rappresenta la versione più recente dell’oggetto).

Oltre questa modifica, lo schema genera i seguenti servizi di lettura aggiuntivi per le classi storicizzate:

Servizio getVersion #

Il servizio Query.<ClassName>___getVersion consente di ottenere una versione storica di un grafo di oggetti a partire da un oggetto di una certa classe.

type Query {
  ClassName___getVersion(_id: ID!, atVersion: Datetime!): ClassName
}

Il servizio richiede in input l’ID dell’oggetto da recuperare e il timestamp della versione, e restituisce la corrispondente struttura <ClassName>. La versione di <ClassName> ritornata è quella il cui intervallo (row_start, row_end) include il timestamp atVersion passato come parametro.

Ad esempio, il servizio per recuperare la versione storica di un oggetto Employee è il seguente:

type Query {
  Employee___getVersion(_id: ID!, atVersion: Datetime!): Employee
}

Servizio getVersionPage #

Il servizio Query.<ClassName>___getVersionPage consente di ottenere un elenco di versioni storiche di un grafo di oggetti a partire da un oggetto di una certa classe.

type Query {
  ClassName___getVersionPage(_id: ID!, ClassNamePageOptions options): ClassNamePage
}

Il servizio richiede in input l’ID dell’oggetto da recuperare e restituisce in output la struttura <ClassName>Page, che contiene una lista delle versioni storiche
dell’oggetto. È possibile controllare il sottoinsieme di oggetti restituito dalla pagina valorizzando l’argomento facoltativo options, di tipo <ClassName>PageOptions.

Il risultato può essere filtrato e/o ordinato utilizzando tutte le <ClassName>PageOptions pre-esistenti, alle quali è aggiunta la possibilità di ordinare in base ai campi _versionStart e _versionEnd.

input ClassNamePageOptions {
  orderBy: [ClassNameSort!] = [_id___ASC]
  # ...
}

enum ClassNameSort {
  _id___ASC
  _id___DESC
  _versionStart___ASC
  _versionStart___DESC
  _versionEnd___ASC
  _versionEnd___DESC
  # ...
}

Ad esempio, il servizio per recuperare l’elenco delle versioni storiche di un oggetto Employee è il seguente:

type Query {
  Employee___getVersionPage(_id: ID!, options: EmployeePageOptions): EmployeePage
}