Skip to content
Snippets Groups Projects
Commit c896dbc9 authored by Liam Tirpitz's avatar Liam Tirpitz
Browse files

Add explanation of PLM to extended documentation, reference in Readme.

parent d57c2722
No related branches found
No related tags found
No related merge requests found
# factlib.js
## factlib.js
A library for node.js written in Typescript that enables clients and processes to interact with Linked Data Platforms
according to the FactDAG model while preserving and creating correct provenance information.
......@@ -16,6 +16,7 @@ npm install @i5/factlib.js
A list of the available versions can be found in the [Packages](https://git.rwth-aachen.de/i5/factdag/factlibjs/-/packages)
section in Gitlab.
<!--
To authenticate, a `.npmrc` file must be present containing:
```
@i5:registry=https://git.rwth-aachen.de/api/v4/packages/npm/
......@@ -23,15 +24,14 @@ To authenticate, a `.npmrc` file must be present containing:
```
The `<TOKEN>` can be a personal access token that can be created in the user settings in Gitlab.
The [Gitlab-Documentation](https://git.rwth-aachen.de/help/user/packages/npm_registry/index.md) contains further details.
-->
The library can then be imported like this:
```
import {Fact} from "@i5/factlib.js";
```
#### Modify RDF resources
Factlib.js uses [rdflib.js](https://github.com/linkeddata/rdflib.js) to store LDP resources locally.
For each resource, a local Rdflib.js store is created.
The [Resource](src/datamodels/resource.ts)-class exposes the `queryStore` method that can be used to retrieve data from this local store.
How the local store works and how it can be used is [documented](https://github.com/solid/solid-tutorial-rdflib.js) by the rdflib.js project.
#### Understand factlib.js
[This document](documentation/factlib.md) explains the terminology used in the library as well as its basic capabilities.
Additionally, there are multiple example provided in this repository, illustrating how Factlib.js may be used.
### Examples
There are multiple examples that show how the library can be used.
......
##Getting Started
This documents explains the fundamental concepts behind the factlib.js library as well as core concepts of the library implementation itself.
## Theoretical Foundations and Technologies
......@@ -73,7 +75,7 @@ Additionally, the PROV relation `prov:wasRevisionOf` is added to candidates that
A derived candidate initially contains the same RDF data as the resource, but the triples in its store can be manipulated.
In general, arbitrary manipulations to the RDF data are possible, but the different candidate classes provide predefined methods for the most common operations on their instances to simplify their usage.
<img src="candidate_cycles.PNG" width="300" alt="Candidate Cycles"/>
<img src="candidate_cycles.PNG" width="400" alt="Candidate Cycles"/>
For creation and modification operations on resources, the library takes candidate objects and returns resource objects if the associated REST operation was successful.
The library transforms candidates to resources by sending them to the server.
......@@ -98,10 +100,9 @@ The provided class model can be used to implement core features of the library l
### Reading and Writing Facts
#TODO INIT
To read or write Facts to an LDP server, the LDPMementoClient can be used.
~~~
const service = new LdpMementoClient();
const idFactory = service.getIDFactory();
~~~
At its core, Factlib.js can be used to read and write facts.
Full code examples on how to use the library are [part of this repository](../examples).
......@@ -112,6 +113,7 @@ LDP-based FactIDs consist of a domain name, a path to a resource and a timestamp
A resource is identified by its __ResourceID__, which only consists of the authorityID and the internal resourceID.
A resourceID is an object that can be created by the IDFactory:
~~~
const idFactory = service.getIDFactory();
const resourceID = idFactory.createResourceID("http://authority.com", "/path/to/resource");`
~~~
......@@ -131,7 +133,7 @@ However, this method **does not** automatically create the associated provenance
The user must add the necessary Process- and Activity-Facts manually and connect them correctly to the created facts, as illustrated in the [Binary Example](../examples/binaryExample/binaryExample.ts)
As an alternative, the ProcessLifecycleManager offers less control, but increased automation, as discussed later on.
#### Upadting an existing Resource
#### Updating an existing Resource
A resourceID can be used to retrieve the latest revision of the corresponding resource:
~~~
const fact = await service.getLastFactRevision(resourceID);
......@@ -177,12 +179,12 @@ Factlib.js also handles these _binaries_, as illustrated in the [Binary Example]
#### Reading Binaries
Known binaries can be requested from a server via the library.
~~~
const stream = await service.getLastBinaryFactRevision(resourceID, "image/png");
const binaryFact = await service.getLastBinaryFactRevision(resourceID, "image/png");
~~~
The user can handle the resulting stream as she wishes.
For example, the binary can be written to the local filesystem
~~~
stream.binaryContent.pipe(fs.createWriteStream("./output/logo.png"));
binaryFact.binaryContent.pipe(fs.createWriteStream("./output/logo.png"));
~~~
#### Creating Binaries
......@@ -196,10 +198,46 @@ const fact = await service.createBinaryFactResource(candidate);
~~~
### Process Lifecycle Manager
The ProcessLifecycleManager automatically creates the provenance triples, and resources that are required to maintain a full and compliant FactDAG.
The ProcessLifecycleManager(PLM) automatically creates the provenance triples, and resources that are required to maintain a full and compliant FactDAG.
However, its use is currently limited to specific, statically defined scenarios.
The PLM has to be initialized with a [configuration file](../examples/books/publisher/auth1/config.json).
This configuration file defines the resource locations for all resources associated with a process and its execution.
Specifically, the authority responsible for the process, the activity resource and the process resource.
Additionally, it defines the resources that are used by the process.
These used resources are later automatically referenced in the activity resource revision using PROV.
~~~
{
"authority": {
"uri": "http://localhost:8081/"
},
"process": {
"checkLatest": false,
"location": "/processes/handleBinariesExample",
"uses": []
},
"activity": {
"location": "/activities/handleBinariesExample"
}
}
~~~
The PLM can be initialized with the configuration and started.
~~~
import * as config from "./config.json";
const pManager = new ProcessLifecycleManager(config);
await pManager.start();
~~~
Now, one or multiple candidates (such as `c1` and `c2`) can be passed to the PLM instead of writing them directly to the server.
~~~
await pManager.execProcess([c1,c2]);
~~~
The PLM persists the candidates to one or multiple servers and uses the provided configuration to integrate the resulting facts in a compliant FactDAG.
Specifically, this entails that the PLM creates a process resource, linked with PROV to its responsible authority.
For each execution using the `execProcess` method, the PLM also creates revisions of the configured activity resource.
This activity is linked to the current revision of the process resource, and references the resources that are configured as used.
Subsequently, the candidates are linked to this activity (by referencing it using PROV) before they are persisted.
This guarantees a complete and compliant FactDAG.
### Subscriptions
<img src="subscriptions-Page-1.png" alt="Subscriptions" width="900"/>
### Process Revisions
\ No newline at end of file
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment