From e0b659aca200d81e0878a0e5d01328abf32f7939 Mon Sep 17 00:00:00 2001 From: Dave Eichmann Date: Tue, 10 Oct 2023 10:17:59 -0500 Subject: [PATCH 1/8] Update index.md Adding content to section 6. --- docs/0.1/index.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/docs/0.1/index.md b/docs/0.1/index.md index 458c83d..5885db1 100644 --- a/docs/0.1/index.md +++ b/docs/0.1/index.md @@ -753,6 +753,11 @@ For each change create a separate [Entity Change Activity](#entity-change-activi ## 6. Consuming Entity Change Sets {: #consuming-entity-change-sets} +Activity streams are inherently temporal constructs, and as such, the order of presentation in a stream may be _forward_ (i.e. the starting point +in the stream reflects its oldest elements and consuming the stream involves newer and newer elements) or it may be _reverse_ (i.e. the starting +point in the stream reflects its most recent elements and consuming the stream involves older and older elements). This specification espouses +no preference of either approach. Rather example approaches to each are presented below. + ### 6.1 Example consuming Library of Congress Activity Stream _CAUTION: This section is under construction. This section may or may not be removed from the final draft, in lieu of, a section that is a general example._ @@ -828,6 +833,40 @@ LOOP end ``` +### 6.2 Consuming a forward delta stream + +Characteristics: +* an entity will appear in the activity stream one or more times +* the date of the activity for an entity will be the date of the most recent change +* the first page of the stream has the oldest activities +* activities on a page are listed from oldest to newest +* the date of an activity is the time the ??? + +Assumptions: +* the consumer fully processes all activities appearing in a given page in the stream +* the consumer maintains a persistent reference to the last page published in the stream (last_page) + +Pseudocode: +``` +go to the activity stream +current = activity.last_page + +while (current.next != null) + for each activity in current + process activity by type + end +end +``` + +### 6.3 Discussion + +The Library of Congress reverse delta approach is inherently the most compact, as any given entity appears in the stream exactly once, at its most recent +point of modification. However, this is accomplished by completely regenerating the activity stream in its entirety whenever new content is +made available. The Getty forward delta approach yields pages that are immutable - once issued a page will never be altered - with new content +appearing incrementally on new pages attached to the end of the pages comprising the stream. Any given entity may appear multiple times in the +stream, reflecting the number of modifications it has undergone over its life, and each appearance need only update the entity rather than +provide a complete representation. + ## Acknowledgements We are grateful to all participants in the LD4 [Best Practices for Authoritative Data Working Group](https://wiki.lyrasis.org/x/pgFrD), within which this specification was created. [E. Lynette Rayle](https://orcid.org/0000-0001-7707-3572) (formerly at Cornell University) led the initial development of this specification. [Jim Hahn](https://orcid.org/0000-0001-7924-5294) (University of Pennsylvania Libraries), [Kirk Hess](https://orcid.org/0000-0002-9559-6649) (OCLC R&D), [Anna Lionetti](https://orcid.org/0000-0001-6157-8808) (Casalini Libri), [Tiziana Possemato](https://orcid.org/0000-0002-7184-4070) (Casalini Libri), and [Erik Radio](https://orcid.org/0000-0003-0734-1978) (University of Colorado Boulder) also contributed to this work. From aa0d83632c64fe53d1da3bf47f1bd7c4f9ef1878 Mon Sep 17 00:00:00 2001 From: Dave Eichmann Date: Tue, 10 Oct 2023 10:40:13 -0500 Subject: [PATCH 2/8] Update index.md --- docs/0.1/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/0.1/index.md b/docs/0.1/index.md index 5885db1..61b26d3 100644 --- a/docs/0.1/index.md +++ b/docs/0.1/index.md @@ -840,7 +840,7 @@ Characteristics: * the date of the activity for an entity will be the date of the most recent change * the first page of the stream has the oldest activities * activities on a page are listed from oldest to newest -* the date of an activity is the time the ??? +* the date of an activity is the time of that given modification Assumptions: * the consumer fully processes all activities appearing in a given page in the stream From 8917c9e91fbf409761d55a7277af788eeba5c027 Mon Sep 17 00:00:00 2001 From: Dave Eichmann Date: Sun, 19 Nov 2023 13:30:36 -0600 Subject: [PATCH 3/8] Update index.md --- docs/0.1/index.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/0.1/index.md b/docs/0.1/index.md index 61b26d3..9ba6c07 100644 --- a/docs/0.1/index.md +++ b/docs/0.1/index.md @@ -758,6 +758,9 @@ in the stream reflects its oldest elements and consuming the stream involves new point in the stream reflects its most recent elements and consuming the stream involves older and older elements). This specification espouses no preference of either approach. Rather example approaches to each are presented below. +| Mutable Forward | Mutable Reverse | +| Immutable Forward | Immutable Reverse | + ### 6.1 Example consuming Library of Congress Activity Stream _CAUTION: This section is under construction. This section may or may not be removed from the final draft, in lieu of, a section that is a general example._ From 1a2bb462f1a862c88f2658b881d33c96a6c4af3b Mon Sep 17 00:00:00 2001 From: Dave Eichmann Date: Sun, 19 Nov 2023 14:01:17 -0600 Subject: [PATCH 4/8] temporal mutation quadrant completed --- docs/0.1/index.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/0.1/index.md b/docs/0.1/index.md index 9ba6c07..6c95039 100644 --- a/docs/0.1/index.md +++ b/docs/0.1/index.md @@ -755,13 +755,17 @@ For each change create a separate [Entity Change Activity](#entity-change-activi Activity streams are inherently temporal constructs, and as such, the order of presentation in a stream may be _forward_ (i.e. the starting point in the stream reflects its oldest elements and consuming the stream involves newer and newer elements) or it may be _reverse_ (i.e. the starting -point in the stream reflects its most recent elements and consuming the stream involves older and older elements). This specification espouses +point in the stream reflects its most recent elements and consuming the stream involves older and older elements). Likewise, the content of a given page in the stream may be _immutable_ (i.e. once published the content of a given page never changes) or it may be _mutable_ (i.e. the content of a given page can be updated and can differ from release to release). This specification espouses no preference of either approach. Rather example approaches to each are presented below. -| Mutable Forward | Mutable Reverse | -| Immutable Forward | Immutable Reverse | +| x | y | +| --- | --- | +| **Mutable Forward** Pages can be updated, and the content of a given page can differ by release. Older pages appear earlier in the stream than newer pages. | **Mutable Reverse** Pages can be updated, and the content of a given page can differ by release. Older pages appear later in the stream than newer pages. | +| **Immutable Forward** Once published, pages never change. Older pages appear earlier in the stream than newer pages. | **Immutable Reverse** Once published, pages never change. Older pages appear later in the stream than newer pages. | -### 6.1 Example consuming Library of Congress Activity Stream +Of these four possibilities, we describe _mutable reverse_, of which the Library of Congress is an example, and _immutable forward_, of which Getty is an example. Regarding the remaining two possibilities, _mutable forward_, while feasible, requires the entire stream to be processed at each release, as there is no way of establishing where in the stream a change might occur. _Immutable reverse_ is inherently infeasible, as it requires that new content appear first, but on a page that cannot be changed. + +### 6.1 Consuming a _mutable reverse_ stream (e.g. Library of Congress) _CAUTION: This section is under construction. This section may or may not be removed from the final draft, in lieu of, a section that is a general example._ @@ -836,7 +840,7 @@ LOOP end ``` -### 6.2 Consuming a forward delta stream +### 6.2 Consuming an _immutable forward_ stream (e.g. Getty) Characteristics: * an entity will appear in the activity stream one or more times From ca347d629dfc1122163d26a3fcd34dc7454df117 Mon Sep 17 00:00:00 2001 From: Dave Eichmann Date: Mon, 20 Nov 2023 10:52:47 -0600 Subject: [PATCH 5/8] Update index.md --- docs/0.1/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/0.1/index.md b/docs/0.1/index.md index 6c95039..815e50b 100644 --- a/docs/0.1/index.md +++ b/docs/0.1/index.md @@ -758,10 +758,10 @@ in the stream reflects its oldest elements and consuming the stream involves new point in the stream reflects its most recent elements and consuming the stream involves older and older elements). Likewise, the content of a given page in the stream may be _immutable_ (i.e. once published the content of a given page never changes) or it may be _mutable_ (i.e. the content of a given page can be updated and can differ from release to release). This specification espouses no preference of either approach. Rather example approaches to each are presented below. -| x | y | -| --- | --- | -| **Mutable Forward** Pages can be updated, and the content of a given page can differ by release. Older pages appear earlier in the stream than newer pages. | **Mutable Reverse** Pages can be updated, and the content of a given page can differ by release. Older pages appear later in the stream than newer pages. | -| **Immutable Forward** Once published, pages never change. Older pages appear earlier in the stream than newer pages. | **Immutable Reverse** Once published, pages never change. Older pages appear later in the stream than newer pages. | +| | Forward | Reverse | +| --- | --- | --- | +| **Mutable** | **Mutable Forward** Pages can be updated, and the content of a given page can differ by release. Older pages appear earlier in the stream than newer pages. | **Mutable Reverse** Pages can be updated, and the content of a given page can differ by release. Older pages appear later in the stream than newer pages. | +| **Immutable** | **Immutable Forward** Once published, pages never change. Older pages appear earlier in the stream than newer pages. | **Immutable Reverse** Once published, pages never change. Older pages appear later in the stream than newer pages. | Of these four possibilities, we describe _mutable reverse_, of which the Library of Congress is an example, and _immutable forward_, of which Getty is an example. Regarding the remaining two possibilities, _mutable forward_, while feasible, requires the entire stream to be processed at each release, as there is no way of establishing where in the stream a change might occur. _Immutable reverse_ is inherently infeasible, as it requires that new content appear first, but on a page that cannot be changed. From c68da55b2ed1654d389553fb2c07dc6e927949fb Mon Sep 17 00:00:00 2001 From: Dave Eichmann Date: Mon, 20 Nov 2023 11:14:10 -0600 Subject: [PATCH 6/8] Update index.md --- docs/0.1/index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/0.1/index.md b/docs/0.1/index.md index 815e50b..967b761 100644 --- a/docs/0.1/index.md +++ b/docs/0.1/index.md @@ -844,7 +844,6 @@ end Characteristics: * an entity will appear in the activity stream one or more times -* the date of the activity for an entity will be the date of the most recent change * the first page of the stream has the oldest activities * activities on a page are listed from oldest to newest * the date of an activity is the time of that given modification From a68e5cb1fd26e51122ff6dfdba20329d0537ab73 Mon Sep 17 00:00:00 2001 From: Dave Eichmann Date: Mon, 20 Nov 2023 11:15:12 -0600 Subject: [PATCH 7/8] Update index.md --- docs/0.1/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/0.1/index.md b/docs/0.1/index.md index 967b761..e2a7a6a 100644 --- a/docs/0.1/index.md +++ b/docs/0.1/index.md @@ -850,7 +850,7 @@ Characteristics: Assumptions: * the consumer fully processes all activities appearing in a given page in the stream -* the consumer maintains a persistent reference to the last page published in the stream (last_page) +* the consumer maintains a persistent reference to the last page processed in the stream (last_page) Pseudocode: ``` From b934bc178c31f905aab56f6a27a5330c08255ba3 Mon Sep 17 00:00:00 2001 From: Dave Eichmann Date: Mon, 20 Nov 2023 11:21:13 -0600 Subject: [PATCH 8/8] Update index.md --- docs/0.1/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/0.1/index.md b/docs/0.1/index.md index e2a7a6a..68504a6 100644 --- a/docs/0.1/index.md +++ b/docs/0.1/index.md @@ -866,9 +866,9 @@ end ### 6.3 Discussion -The Library of Congress reverse delta approach is inherently the most compact, as any given entity appears in the stream exactly once, at its most recent +The Library of Congress mutable reverse approach is inherently the most compact, as any given entity appears in the stream exactly once, at its most recent point of modification. However, this is accomplished by completely regenerating the activity stream in its entirety whenever new content is -made available. The Getty forward delta approach yields pages that are immutable - once issued a page will never be altered - with new content +made available. The Getty immutable forward approach yields pages that are immutable - once issued a page will never be altered - with new content appearing incrementally on new pages attached to the end of the pages comprising the stream. Any given entity may appear multiple times in the stream, reflecting the number of modifications it has undergone over its life, and each appearance need only update the entity rather than provide a complete representation.