This is an automated email from the ASF dual-hosted git repository. szetszwo pushed a commit to branch asf-site in repository https://gitbox.apache.org/repos/asf/ratis-hadoop-projects.git
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>
