This is an automated email from the ASF dual-hosted git repository.
elserj pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/incubator-ratis.git
The following commit(s) were added to refs/heads/asf-site by this push:
new ccce7cd RATIS-637 Website content update
ccce7cd is described below
commit ccce7cd8917ac99a96d6f63ef7bbd749b67b2260
Author: Josh Elser <[email protected]>
AuthorDate: Mon Aug 19 17:38:35 2019 -0400
RATIS-637 Website content update
---
index.xml | 10 +++
logservice.html | 107 ++++++++++++++++++++++++++++++
logservice/index.html | 1 +
logservice/index.xml | 10 +++
logservice/{index.html => lifecycle.html} | 92 ++++++++++++++++++++++---
sitemap.xml | 4 ++
6 files changed, 215 insertions(+), 9 deletions(-)
diff --git a/index.xml b/index.xml
index b49287a..f03dec4 100644
--- a/index.xml
+++ b/index.xml
@@ -81,6 +81,16 @@ Examples To demonstrate how to use Ratis from the code,
Please look at the follo
</item>
<item>
+ <title>Lifecycle</title>
+ <link>https://ratis.incubator.apache.org/logservice/lifecycle.html</link>
+ <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
+
+ <guid>https://ratis.incubator.apache.org/logservice/lifecycle.html</guid>
+ <description>The LogService is a system which manages a collection of
logs. Each of these logs has a defined state which allows certain operations on
that log or corresponds to actions that the system is taking on that log.
+OPEN This is the first state for a Log which is created in the LogService. A
Log which is OPEN can be read from or written to. This Log has a corresponding
Raft Group (a quorum of servers) who are participating in the hosting of this
Log.</description>
+ </item>
+
+ <item>
<title>LogService</title>
<link>https://ratis.incubator.apache.org/logservice/</link>
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
diff --git a/logservice.html b/logservice.html
index 453715f..47b1fe6 100644
--- a/logservice.html
+++ b/logservice.html
@@ -98,6 +98,112 @@
<h1 id="title"> Archive</h1>
<ul id="list">
+ <h1><a href="/logservice/lifecycle.html">Lifecycle</a></h1>
+ <p><small>0001 Jan 1 </small></p>
+
+
+
+<!---
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License. See accompanying LICENSE file.
+-->
+
+<p>The LogService is a system which manages a collection of logs. Each
+of these logs has a defined state which allows certain operations on that
+log or corresponds to actions that the system is taking on that log.</p>
+
+<h3 id="open">OPEN</h3>
+
+<p>This is the first state for a Log which is created in the LogService. A
+Log which is OPEN can be read from or written to. This Log has a corresponding
+Raft Group (a quorum of servers) who are participating in the hosting of this
+Log.</p>
+
+<p>The only transition out from this state is to the CLOSED state.</p>
+
+<h3 id="closed">CLOSED</h3>
+
+<p>The CLOSED state indicates that a Log is no longer accepting writes. The
+Log is still available to be read from the Raft Group.</p>
+
+<p>A log can be transitioned from OPEN to CLOSED via the client API, but it
+can also be done automatically by the LogService. When a node which was
+participating in the Raft Group for this Log becomes unreachable, we consider
+this Group to be unhealthy and proactively close it to prevent any additional
+writes which may block due to too few nodes to accept a write.</p>
+
+<p>The transition from OPEN to CLOSED is one-way: a Log cannot transition back
+to the OPEN state from the CLOSED state. A CLOSED log may be deleted from the
+system.</p>
+
+<p>From the CLOSED state, a log can be transitioned to the ARCHIVING state or
the DELETED
+state.</p>
+
+<h3 id="deleted">DELETED</h3>
+
+<p>This is a simple state that is short lived. It tracks the clean up
+of any state from the hosting this Log. There are transitions out
+of this state.</p>
+
+<h3 id="archiving">ARCHIVING</h3>
+
+<p>The ARCHIVING state is reached by the archive API call from
+the LogService client. An archival of a log is equivalent to an export
+of that log from the beginning of the log file to a known location. See
+below for a tangent on exporting versus archiving.</p>
+
+<p>This state indicates that the LogService is in the process of copying all
+records in the Log from the starting offset of the archival request to the
+specified location (a user-provided location or a preconfigured location).
+We expect the location to be in some remote storage system such as HDFS or
S3.</p>
+
+<p>The only transition out from this state is to ARCHIVED.</p>
+
+<h3 id="archived">ARCHIVED</h3>
+
+<p>A Log can only reach the ARCHIVED state from the ARCHIVING state. This state
+is automatically transitioned into when the archival of a log is done in
+its entirety.</p>
+
+<p>The action of archiving a log is an asynchronous process, managed by the
leader
+of the Raft Group, thus watching for this state on a log indicates when the
+asynchronous archival is complete and the log can be safely read from the
+archived location.</p>
+
+<p>The only transition out from this state is to DELETED.</p>
+
+<h2 id="archive-and-export">Archive and Export</h2>
+
+<p>The archive and export API calls are very similar in nature but have
+important distinctions in their implementation. As mentioned above,
+an archival of a log is an export of the entire log to a specific location.</p>
+
+<p>An archival of a log is specification of export in that:</p>
+
+<ul>
+<li>An archival of a log requires it to be CLOSED.</li>
+<li>An archived log cannot receive new writes.</li>
+</ul>
+
+<p>An export of a log is more generic in that:</p>
+
+<ul>
+<li>A log does not need to be CLOSED to be exported.</li>
+<li>A log can be repeatedly exported (e.g. to multiple locations).</li>
+<li>More data can be appended to a log that was exported (but new data would
not be reflected in the exported version of the log).</li>
+</ul>
+
+
+
<h1><a href="/logservice/">LogService</a></h1>
<p><small>0001 Jan 1 </small></p>
@@ -126,6 +232,7 @@ daemons provided for the LogService, but these are solely
to be used for testing
<ul>
<li><a
href="https://ratis.incubator.apache.org/logservice/testing/";>Testing</a></li>
+<li><a href="https://ratis.incubator.apache.org/logservice/lifecycle.html";>Log
Lifecycle</a></li>
</ul>
diff --git a/logservice/index.html b/logservice/index.html
index 14c8841..cb9a68b 100644
--- a/logservice/index.html
+++ b/logservice/index.html
@@ -118,6 +118,7 @@ daemons provided for the LogService, but these are solely
to be used for testing
<ul>
<li><a
href="https://ratis.incubator.apache.org/logservice/testing/";>Testing</a></li>
+<li><a href="https://ratis.incubator.apache.org/logservice/lifecycle.html";>Log
Lifecycle</a></li>
</ul>
</div>
diff --git a/logservice/index.xml b/logservice/index.xml
index 33f2ba8..14447cf 100644
--- a/logservice/index.xml
+++ b/logservice/index.xml
@@ -11,6 +11,16 @@
<item>
+ <title>Lifecycle</title>
+ <link>https://ratis.incubator.apache.org/logservice/lifecycle.html</link>
+ <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
+
+ <guid>https://ratis.incubator.apache.org/logservice/lifecycle.html</guid>
+ <description>The LogService is a system which manages a collection of
logs. Each of these logs has a defined state which allows certain operations on
that log or corresponds to actions that the system is taking on that log.
+OPEN This is the first state for a Log which is created in the LogService. A
Log which is OPEN can be read from or written to. This Log has a corresponding
Raft Group (a quorum of servers) who are participating in the hosting of this
Log.</description>
+ </item>
+
+ <item>
<title>LogService</title>
<link>https://ratis.incubator.apache.org/logservice/</link>
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
diff --git a/logservice/index.html b/logservice/lifecycle.html
similarity index 57%
copy from logservice/index.html
copy to logservice/lifecycle.html
index 14c8841..4a6eaa5 100644
--- a/logservice/index.html
+++ b/logservice/lifecycle.html
@@ -92,7 +92,9 @@
</div>
<div class="container">
-<h1>LogService</h1>
+<h1>Lifecycle</h1>
+
+
<!---
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
@@ -107,17 +109,89 @@
limitations under the License. See accompanying LICENSE file.
-->
-<p>The Ratis LogService is an distributed, log implementation built on top of
Apache
-Ratis. The LogService is a “recipe” on top of Apache Ratis,
providing a higher-level
-API as compared to Ratis itself. The LogService provides the ability to create
named,
-durable, append-only data structures with the ability to perform linear
reads.</p>
+<p>The LogService is a system which manages a collection of logs. Each
+of these logs has a defined state which allows certain operations on that
+log or corresponds to actions that the system is taking on that log.</p>
+
+<h3 id="open">OPEN</h3>
+
+<p>This is the first state for a Log which is created in the LogService. A
+Log which is OPEN can be read from or written to. This Log has a corresponding
+Raft Group (a quorum of servers) who are participating in the hosting of this
+Log.</p>
+
+<p>The only transition out from this state is to the CLOSED state.</p>
+
+<h3 id="closed">CLOSED</h3>
+
+<p>The CLOSED state indicates that a Log is no longer accepting writes. The
+Log is still available to be read from the Raft Group.</p>
+
+<p>A log can be transitioned from OPEN to CLOSED via the client API, but it
+can also be done automatically by the LogService. When a node which was
+participating in the Raft Group for this Log becomes unreachable, we consider
+this Group to be unhealthy and proactively close it to prevent any additional
+writes which may block due to too few nodes to accept a write.</p>
+
+<p>The transition from OPEN to CLOSED is one-way: a Log cannot transition back
+to the OPEN state from the CLOSED state. A CLOSED log may be deleted from the
+system.</p>
+
+<p>From the CLOSED state, a log can be transitioned to the ARCHIVING state or
the DELETED
+state.</p>
+
+<h3 id="deleted">DELETED</h3>
+
+<p>This is a simple state that is short lived. It tracks the clean up
+of any state from the hosting this Log. There are transitions out
+of this state.</p>
+
+<h3 id="archiving">ARCHIVING</h3>
+
+<p>The ARCHIVING state is reached by the archive API call from
+the LogService client. An archival of a log is equivalent to an export
+of that log from the beginning of the log file to a known location. See
+below for a tangent on exporting versus archiving.</p>
+
+<p>This state indicates that the LogService is in the process of copying all
+records in the Log from the starting offset of the archival request to the
+specified location (a user-provided location or a preconfigured location).
+We expect the location to be in some remote storage system such as HDFS or
S3.</p>
+
+<p>The only transition out from this state is to ARCHIVED.</p>
+
+<h3 id="archived">ARCHIVED</h3>
+
+<p>A Log can only reach the ARCHIVED state from the ARCHIVING state. This state
+is automatically transitioned into when the archival of a log is done in
+its entirety.</p>
+
+<p>The action of archiving a log is an asynchronous process, managed by the
leader
+of the Raft Group, thus watching for this state on a log indicates when the
+asynchronous archival is complete and the log can be safely read from the
+archived location.</p>
+
+<p>The only transition out from this state is to DELETED.</p>
+
+<h2 id="archive-and-export">Archive and Export</h2>
+
+<p>The archive and export API calls are very similar in nature but have
+important distinctions in their implementation. As mentioned above,
+an archival of a log is an export of the entire log to a specific location.</p>
+
+<p>An archival of a log is specification of export in that:</p>
+
+<ul>
+<li>An archival of a log requires it to be CLOSED.</li>
+<li>An archived log cannot receive new writes.</li>
+</ul>
-<p>Like Ratis, the LogService is designed to be embedded into another
application as
-a library, as opposed to a standalone daemon. On a confusing note, there are
Java
-daemons provided for the LogService, but these are solely to be used for
testing.</p>
+<p>An export of a log is more generic in that:</p>
<ul>
-<li><a
href="https://ratis.incubator.apache.org/logservice/testing/";>Testing</a></li>
+<li>A log does not need to be CLOSED to be exported.</li>
+<li>A log can be repeatedly exported (e.g. to multiple locations).</li>
+<li>More data can be appended to a log that was exported (but new data would
not be reflected in the exported version of the log).</li>
</ul>
</div>
diff --git a/sitemap.xml b/sitemap.xml
index 84d3fd7..63ff498 100644
--- a/sitemap.xml
+++ b/sitemap.xml
@@ -49,6 +49,10 @@
</url>
<url>
+ <loc>https://ratis.incubator.apache.org/logservice/lifecycle.html</loc>
+ </url>
+
+ <url>
<loc>https://ratis.incubator.apache.org/logservice/</loc>
</url>
