You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@omid.apache.org by yo...@apache.org on 2018/09/26 09:03:49 UTC
[50/56] incubator-omid-site git commit: [wagon-git] commit to branch
asf-site 9/25/18 12:09 PM
[wagon-git] commit to branch asf-site 9/25/18 12:09 PM
Project: http://git-wip-us.apache.org/repos/asf/incubator-omid-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-omid-site/commit/077788dd
Tree: http://git-wip-us.apache.org/repos/asf/incubator-omid-site/tree/077788dd
Diff: http://git-wip-us.apache.org/repos/asf/incubator-omid-site/diff/077788dd
Branch: refs/heads/asf-site
Commit: 077788dd1e67fa0eaa93d07b2f6afed03ec03696
Parents: 8ffb3a8
Author: Yonatan Gottesman <yo...@gmail.com>
Authored: Tue Sep 25 12:09:07 2018 +0300
Committer: Yonatan Gottesman <yo...@gmail.com>
Committed: Tue Sep 25 12:09:07 2018 +0300
----------------------------------------------------------------------
basic-algorithm.html | 30 +-
basic-concepts.html | 45 +-
basic-examples.html | 102 +-
checkstyle-aggregate.html | 5786 ++++++++++++------
checkstyle.rss | 648 +-
client-failure-management.html | 36 +-
coding-guide-and-style.html | 99 +-
cpd.html | 28 +-
dependency-convergence.html | 1235 ++--
dependency-info.html | 32 +-
dependency-management.html | 24 +-
distribution-management.html | 16 +-
index.html | 49 +-
licenses.html | 443 ++
mailing-lists.html | 56 +-
modules.html | 50 +-
omid-components.html | 52 +-
plugin-management.html | 16 +-
plugins.html | 30 +-
pmd.html | 292 +-
project-info.html | 30 +-
project-reports.html | 16 +-
quickstart.html | 136 +-
scm.html | 251 +
summary.html | 280 +
team.html | 292 +
xref-test/allclasses-frame.html | 23 +-
xref-test/index.html | 2 +-
.../committable/hbase/TestHBaseCommitTable.html | 549 +-
.../omid/committable/hbase/package-frame.html | 2 +-
.../omid/committable/hbase/package-summary.html | 2 +-
.../apache/omid/committable/package-frame.html | 2 +-
.../omid/committable/package-summary.html | 2 +-
xref-test/org/apache/omid/package-frame.html | 8 +-
xref-test/org/apache/omid/package-summary.html | 12 +-
.../storage/TestHBaseTimestampStorage.html | 14 +-
.../omid/timestamp/storage/package-frame.html | 2 +-
.../omid/timestamp/storage/package-summary.html | 2 +-
.../omid/tools/hbase/TestOmidTableManager.html | 2 +-
.../apache/omid/tools/hbase/package-frame.html | 2 +-
.../omid/tools/hbase/package-summary.html | 2 +-
.../apache/omid/transaction/OmidTestBase.html | 472 +-
.../TSOForHBaseCompactorTestModule.html | 91 +-
.../TestAsynchronousPostCommitter.html | 98 +-
.../apache/omid/transaction/TestAutoFlush.html | 20 +-
.../TestBaillisAnomaliesWithTXs.html | 86 +-
.../omid/transaction/TestBasicTransaction.html | 113 +-
.../apache/omid/transaction/TestCellUtils.html | 393 +-
.../omid/transaction/TestColumnIterator.html | 8 +-
.../apache/omid/transaction/TestCompaction.html | 2355 +++----
.../omid/transaction/TestCompactorScanner.html | 161 +-
.../apache/omid/transaction/TestDeletion.html | 637 +-
.../TestEndToEndScenariosWithHA.html | 777 +--
.../apache/omid/transaction/TestFilters.html | 353 +-
.../transaction/TestHBaseTransactionClient.html | 780 ++-
.../TestHBaseTransactionManager.html | 44 +-
.../omid/transaction/TestMultiplePut.html | 217 +-
.../apache/omid/transaction/TestReadPath.html | 42 +-
.../omid/transaction/TestShadowCells.html | 975 +--
.../transaction/TestSingleColumnFamily.html | 30 +-
.../omid/transaction/TestTTableBehaviour.html | 269 +-
.../transaction/TestTransactionCleanup.html | 199 +-
.../transaction/TestTransactionConflict.html | 764 ++-
.../omid/transaction/TestTxMgrFailover.html | 165 +-
.../apache/omid/transaction/TestUpdateScan.html | 56 +-
.../apache/omid/transaction/package-frame.html | 14 +-
.../omid/transaction/package-summary.html | 22 +-
.../org/apache/omid/tso/TSOMockModule.html | 121 +-
.../org/apache/omid/tso/TestLeaseManager.html | 791 +--
.../tso/TestPersistenceProcessorHandler.html | 696 +--
.../apache/omid/tso/TestRequestProcessor.html | 334 +-
.../omid/tso/TestTSOChannelHandlerNetty.html | 158 +-
.../apache/omid/tso/TestTimestampOracle.html | 179 +-
...tionOfTSOClientServerBasicFunctionality.html | 430 +-
.../omid/tso/client/TestMockTSOClient.html | 100 +-
.../client/TestTSOClientConnectionToTSO.html | 498 +-
...stTSOClientRequestAndResponseBehaviours.html | 724 +--
.../apache/omid/tso/client/package-frame.html | 5 +-
.../apache/omid/tso/client/package-summary.html | 7 +-
.../org/apache/omid/tso/package-frame.html | 8 +-
.../org/apache/omid/tso/package-summary.html | 12 +-
.../org/apache/statemachine/package-frame.html | 2 +-
.../apache/statemachine/package-summary.html | 2 +-
xref-test/overview-frame.html | 2 +-
xref-test/overview-summary.html | 4 +-
xref/allclasses-frame.html | 64 +-
xref/index.html | 2 +-
.../hbase/regionserver/package-frame.html | 7 +-
.../hbase/regionserver/package-summary.html | 9 +-
xref/org/apache/omid/HBaseShims.html | 103 +-
xref/org/apache/omid/YAMLUtils.html | 105 +-
.../omid/benchmarks/hbase/package-frame.html | 2 +-
.../omid/benchmarks/hbase/package-summary.html | 2 +-
.../omid/benchmarks/tso/package-frame.html | 2 +-
.../omid/benchmarks/tso/package-summary.html | 2 +-
.../omid/benchmarks/utils/package-frame.html | 2 +-
.../omid/benchmarks/utils/package-summary.html | 2 +-
.../committable/hbase/HBaseCommitTable.html | 772 +--
.../omid/committable/hbase/package-frame.html | 2 +-
.../omid/committable/hbase/package-summary.html | 2 +-
.../apache/omid/committable/package-frame.html | 2 +-
.../omid/committable/package-summary.html | 2 +-
xref/org/apache/omid/examples/BasicExample.html | 181 +-
.../omid/examples/ConfigurationExample.html | 205 +-
.../omid/examples/SnapshotIsolationExample.html | 393 +-
.../org/apache/omid/examples/package-frame.html | 2 +-
.../apache/omid/examples/package-summary.html | 2 +-
xref/org/apache/omid/metrics/package-frame.html | 2 +-
.../apache/omid/metrics/package-summary.html | 2 +-
xref/org/apache/omid/package-frame.html | 7 +-
xref/org/apache/omid/package-summary.html | 9 +-
.../storage/HBaseTimestampStorage.html | 139 +-
.../omid/timestamp/storage/package-frame.html | 2 +-
.../omid/timestamp/storage/package-summary.html | 2 +-
.../org/apache/omid/tools/hbase/HBaseLogin.html | 47 +-
.../omid/tools/hbase/OmidTableManager.html | 358 +-
.../apache/omid/tools/hbase/package-frame.html | 2 +-
.../omid/tools/hbase/package-summary.html | 2 +-
.../omid/transaction/AbstractTransaction.html | 543 +-
.../transaction/AbstractTransactionManager.html | 901 ++-
xref/org/apache/omid/transaction/CellUtils.html | 782 +--
.../apache/omid/transaction/CompactorUtil.html | 149 +-
.../apache/omid/transaction/HBaseCellId.html | 140 +-
.../HBaseOmidClientConfiguration.html | 319 +-
.../transaction/HBaseSyncPostCommitter.html | 207 +-
.../omid/transaction/HBaseTransaction.html | 133 +-
.../transaction/HBaseTransactionClient.html | 6 +-
.../transaction/HBaseTransactionManager.html | 509 +-
.../apache/omid/transaction/OmidCompactor.html | 254 +-
xref/org/apache/omid/transaction/TTable.html | 1457 ++---
.../apache/omid/transaction/Transaction.html | 55 +-
.../omid/transaction/TransactionManager.html | 13 +-
.../apache/omid/transaction/package-frame.html | 39 +-
.../omid/transaction/package-summary.html | 61 +-
xref/org/apache/omid/tso/Batch.html | 88 +-
xref/org/apache/omid/tso/BatchPoolModule.html | 38 +-
xref/org/apache/omid/tso/CacheEvaluation.html | 2 +-
xref/org/apache/omid/tso/PersistEvent.html | 66 +-
.../apache/omid/tso/PersistenceProcessor.html | 8 +-
.../omid/tso/PersistenceProcessorHandler.html | 350 +-
.../omid/tso/PersistenceProcessorImpl.html | 154 +-
xref/org/apache/omid/tso/ReplyProcessor.html | 17 +-
.../org/apache/omid/tso/ReplyProcessorImpl.html | 393 +-
xref/org/apache/omid/tso/RequestProcessor.html | 5 +-
.../apache/omid/tso/RequestProcessorImpl.html | 711 ++-
xref/org/apache/omid/tso/TSOChannelHandler.html | 210 +-
xref/org/apache/omid/tso/TSOModule.html | 101 +-
xref/org/apache/omid/tso/TSOServer.html | 2 +-
xref/org/apache/omid/tso/TSOServerConfig.html | 275 +-
.../apache/omid/tso/TimestampOracleImpl.html | 280 +-
xref/org/apache/omid/tso/client/CellId.html | 5 +-
.../apache/omid/tso/client/MockTSOClient.html | 224 +-
.../tso/client/OmidClientConfiguration.html | 290 +-
xref/org/apache/omid/tso/client/TSOClient.html | 1873 +++---
.../org/apache/omid/tso/client/TSOProtocol.html | 111 +-
.../apache/omid/tso/client/package-frame.html | 8 +-
.../apache/omid/tso/client/package-summary.html | 12 +-
xref/org/apache/omid/tso/package-frame.html | 8 +-
xref/org/apache/omid/tso/package-summary.html | 12 +-
.../apache/omid/tso/util/DummyCellIdImpl.html | 37 +-
.../org/apache/omid/tso/util/package-frame.html | 2 +-
.../apache/omid/tso/util/package-summary.html | 2 +-
xref/org/apache/omid/zk/package-frame.html | 2 +-
xref/org/apache/omid/zk/package-summary.html | 2 +-
xref/org/apache/statemachine/package-frame.html | 2 +-
.../apache/statemachine/package-summary.html | 2 +-
xref/overview-frame.html | 5 +-
xref/overview-summary.html | 9 +-
168 files changed, 21123 insertions(+), 16102 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-omid-site/blob/077788dd/basic-algorithm.html
----------------------------------------------------------------------
diff --git a/basic-algorithm.html b/basic-algorithm.html
index 89fda4b..69429ab 100644
--- a/basic-algorithm.html
+++ b/basic-algorithm.html
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.7 at 2018-09-20
+ | Generated by Apache Maven Doxia Site Renderer 1.8.1 at 2018-09-25
| Rendered using Apache Maven Fluido Skin 1.5
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20180920" />
+ <meta name="Date-Revision-yyyymmdd" content="20180925" />
<meta http-equiv="Content-Language" content="en" />
<title>Apache Omid – Basic Transaction Algorithm</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.5.min.css" />
@@ -117,7 +117,7 @@
</li>
<li> <a href="index.html" title="About">About</a>
</li>
- <li> <a href="license.html" title="Licenses">Licenses</a>
+ <li> <a href="licenses.html" title="Licenses">Licenses</a>
</li>
<li> <a href="modules.html" title="Project Modules">Project Modules</a>
</li>
@@ -125,11 +125,11 @@
</li>
<li> <a href="plugins.html" title="Plugins">Plugins</a>
</li>
- <li> <a href="team-list.html" title="Team">Team</a>
+ <li> <a href="scm.html" title="Source Code Management">Source Code Management</a>
</li>
- <li> <a href="source-repository.html" title="Source Code Management">Source Code Management</a>
+ <li> <a href="summary.html" title="Summary">Summary</a>
</li>
- <li> <a href="project-summary.html" title="Summary">Summary</a>
+ <li> <a href="team.html" title="Team">Team</a>
</li>
</ul>
</li>
@@ -194,11 +194,11 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="projectVersion">Version: 0.9.0.0
+ <li id="projectVersion">Version: 0.8.2.11-SNAPSHOT
</li>
- <li id="publishDate" class="pull-right">Last Published: 2018-09-20</li>
+ <li id="publishDate" class="pull-right">Last Published: 2018-09-25</li>
</ul>
</div>
@@ -207,19 +207,7 @@
<div id="bodyColumn" >
- <!--
- 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.
---><h1>Basic Transaction Algorithm</h1>
+ <h1>Basic Transaction Algorithm</h1>
<p>A simplified version of the algorithm for performing transactional operations in a non-faulty scenario is depicted in the following figure:</p>
<p><img src="images/basic-alg.png" alt="Basic algorithm for managing transactions" /></p>
<p>Initially, a user application (not shown in the figure for the sake of simplicity) starts a new transaction using the Transactional Client API, which in turn acquires a start timestamp from the TSO.</p>
http://git-wip-us.apache.org/repos/asf/incubator-omid-site/blob/077788dd/basic-concepts.html
----------------------------------------------------------------------
diff --git a/basic-concepts.html b/basic-concepts.html
index f21dc92..2949ae8 100644
--- a/basic-concepts.html
+++ b/basic-concepts.html
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.7 at 2018-09-20
+ | Generated by Apache Maven Doxia Site Renderer 1.8.1 at 2018-09-25
| Rendered using Apache Maven Fluido Skin 1.5
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20180920" />
+ <meta name="Date-Revision-yyyymmdd" content="20180925" />
<meta http-equiv="Content-Language" content="en" />
<title>Apache Omid – Basic Concepts</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.5.min.css" />
@@ -117,7 +117,7 @@
</li>
<li> <a href="index.html" title="About">About</a>
</li>
- <li> <a href="license.html" title="Licenses">Licenses</a>
+ <li> <a href="licenses.html" title="Licenses">Licenses</a>
</li>
<li> <a href="modules.html" title="Project Modules">Project Modules</a>
</li>
@@ -125,11 +125,11 @@
</li>
<li> <a href="plugins.html" title="Plugins">Plugins</a>
</li>
- <li> <a href="team-list.html" title="Team">Team</a>
+ <li> <a href="scm.html" title="Source Code Management">Source Code Management</a>
</li>
- <li> <a href="source-repository.html" title="Source Code Management">Source Code Management</a>
+ <li> <a href="summary.html" title="Summary">Summary</a>
</li>
- <li> <a href="project-summary.html" title="Summary">Summary</a>
+ <li> <a href="team.html" title="Team">Team</a>
</li>
</ul>
</li>
@@ -194,11 +194,11 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="projectVersion">Version: 0.9.0.0
+ <li id="projectVersion">Version: 0.8.2.11-SNAPSHOT
</li>
- <li id="publishDate" class="pull-right">Last Published: 2018-09-20</li>
+ <li id="publishDate" class="pull-right">Last Published: 2018-09-25</li>
</ul>
</div>
@@ -207,25 +207,13 @@
<div id="bodyColumn" >
- <!--
- 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.
---><h1>Basic Concepts</h1>
+ <h1>Basic Concepts</h1>
<p>Omid started as a research project in 2011 at Yahoo Labs, with the aim of adding transactions to HBase. While Omid was designed with HBase in mind, we have been careful to not bind ourselves to a particular big datastore. As a consequence, Omid can be potentially adapted to be used with any other multiversioned key-value datastore with some additional extensions.</p>
<p>In the next sections, we introduce two basic concepts that have driven Omid’s design.</p>
<div class="section">
<h2><a name="Locking_vs_Lock-Free"></a>Locking vs Lock-Free</h2>
<p>When solving the <b>conflict detection</b> problem in transactional systems, there are two main approaches that transaction managers may implement: <i>locking</i> and <i>lock-free</i>.</p>
-<p>With a locking mechanism, the client managing the transaction attempts to acquire a lock on each cell in the writeset (the set of changes in data performed by the transaction) before committing. If it succeeds in acquiring the lock, and no other transaction has written to the cells since the start of the client’s transaction, it can commit, as it knows that no other transaction can write to the cell after the lock has been acquired. Once the commit has completed, the client can release the locks on the cells. If the client fails to acquire the lock on any cell or some other transaction has written to it since the start of the transaction, then the transaction is aborted. </p>
+<p>With a locking mechanism, the client managing the transaction attempts to acquire a lock on each cell in the writeset (the set of changes in data performed by the transaction) before committing. If it succeeds in acquiring the lock, and no other transaction has written to the cells since the start of the client’s transaction, it can commit, as it knows that no other transaction can write to the cell after the lock has been acquired. Once the commit has completed, the client can release the locks on the cells. If the client fails to acquire the lock on any cell or some other transaction has written to it since the start of the transaction, then the transaction is aborted.</p>
<p>For example, <a class="externalLink" href="http://research.google.com/pubs/pub36726.html">Google Percolator</a> uses a locking mechanism in its transactional system, and so do other subsequent academic and open source transaction managers for NoSQL datastores.</p>
<p>Locking systems can be problematic in a distributed setting and in the presence of process failures. If a client fails while holding a lock another process must clean up the locks held by that client. However, it is impossible to detect reliably if a client has failed or is just being slow. Normally this is dealt with using timeouts, after which the client is invalidated and its locks released. However, the timeout must be high enough to ensure that valid clients are not invalidated.</p>
<p>In lock-based systems, it is also possible for two transactions to repeatedly conflict with each other over multiple retries as there is no defined order in which locks must be acquired.</p>
@@ -236,30 +224,23 @@
<p><b><a class="externalLink" href="http://research.microsoft.com/pubs/69541/tr-95-51.pdf">Snapshot Isolation (SI)</a></b> provides the users of a database with a consistent view of the database and the ability to detect write-write conficts between transactions. When a client starts a transaction, it is given a <i>“snapshot view”</i> of the database. A value read from a cell within this snapshot will always be the same, unless the transaction itself updates the cell.</p>
<p>To successfully commit a transaction within snapshot isolation, the system must ensure that no other transaction has written to any of the transaction’s written cells (that is, its writeset) since the start of the transaction.</p>
<p>That is, transactions with SI guarantees should read from their own data snapshot, being a data snapshot:</p>
-
<ul>
-
+
<li>Immutable</li>
-
<li>Identified by creation time</li>
-
<li>Containing values committed before creation time</li>
</ul>
<p>In Omid, transactions conflict iff:</p>
-
<ul>
-
+
<li>Overlap in time, and…</li>
-
<li>… write to the same cell of a particular row</li>
</ul>
<p>The following figure describes SI with an example: <img src="images/snapshot-isolation.png" alt="Snapshot Isolation" /></p>
<p>As depicted in the figure, transaction T2 overlaps in time with T1 and T3, but spatially:</p>
-
<ul>
-
+
<li>T1 ∩ T2 = ∅</li>
-
<li>T2 ∩ T3 = { R4 }</li>
</ul>
<p>So, transactions T1 and T2, despite overlaping in time, they do not overlap in the elements they modify, so they do not conflict. However, transactions T2 and T3 have a conflict because they overlap both in space (both modify R4) and time. Finally, Transaction T4 does not has conflicts with other transactions.</p>
http://git-wip-us.apache.org/repos/asf/incubator-omid-site/blob/077788dd/basic-examples.html
----------------------------------------------------------------------
diff --git a/basic-examples.html b/basic-examples.html
index d081b49..1b4d3f0 100644
--- a/basic-examples.html
+++ b/basic-examples.html
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.7 at 2018-09-20
+ | Generated by Apache Maven Doxia Site Renderer 1.8.1 at 2018-09-25
| Rendered using Apache Maven Fluido Skin 1.5
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20180920" />
+ <meta name="Date-Revision-yyyymmdd" content="20180925" />
<meta http-equiv="Content-Language" content="en" />
<title>Apache Omid – Code Examples</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.5.min.css" />
@@ -117,7 +117,7 @@
</li>
<li> <a href="index.html" title="About">About</a>
</li>
- <li> <a href="license.html" title="Licenses">Licenses</a>
+ <li> <a href="licenses.html" title="Licenses">Licenses</a>
</li>
<li> <a href="modules.html" title="Project Modules">Project Modules</a>
</li>
@@ -125,11 +125,11 @@
</li>
<li> <a href="plugins.html" title="Plugins">Plugins</a>
</li>
- <li> <a href="team-list.html" title="Team">Team</a>
+ <li> <a href="scm.html" title="Source Code Management">Source Code Management</a>
</li>
- <li> <a href="source-repository.html" title="Source Code Management">Source Code Management</a>
+ <li> <a href="summary.html" title="Summary">Summary</a>
</li>
- <li> <a href="project-summary.html" title="Summary">Summary</a>
+ <li> <a href="team.html" title="Team">Team</a>
</li>
</ul>
</li>
@@ -194,11 +194,11 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="projectVersion">Version: 0.9.0.0
+ <li id="projectVersion">Version: 0.8.2.11-SNAPSHOT
</li>
- <li id="publishDate" class="pull-right">Last Published: 2018-09-20</li>
+ <li id="publishDate" class="pull-right">Last Published: 2018-09-25</li>
</ul>
</div>
@@ -207,45 +207,27 @@
<div id="bodyColumn" >
- <!--
- 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.
---><h1>Code Examples</h1>
+ <h1>Code Examples</h1>
<p>This section guides the developer of Omid-based transactional applications over the different steps required to execute multi-row transactions on HBase and the different APIs involved in the process.</p>
<div class="section">
<h2><a name="Transactional_Contexts_and_Operations_with_Omid"></a>Transactional Contexts and Operations with Omid</h2>
<p>Applications requiring transactions will use the interfaces provided by the Omid <i>Transactional Client</i>. These interfaces are provided by the <i>TransactionManager</i> and <i>TTable</i> classes described below.</p>
<p>When starting a transaction, the Omid <i>Transactional Client</i> requests a <i>start timestamp</i> from the <i>TSO</i>. This timestamp marks the beginning of a transactional context, that is, a transaction. From that point on, the client application can perform transactional read and write operations on the data source:</p>
-
<ul>
-
+
<li><b>Read Ops</b>. The client first checks if the cell has a <i>Shadow Cell (SC)</i>. If the cell has a <i>SC</i> and the <i>commit timestamp</i> is lower than the <i>start timestamp</i> of the reading transaction, then the client can “see” the cell, that is, it’s in its snapshot. If there is no <i>SC</i>, the <i>Commit Table (CT)</i> is consulted to find the <i>commit timestamp</i> of the cell. If the <i>commit timestamp</i> does not exist in the <i>CT</i>, then the cell is assumed to below to an aborted transaction.</li>
-
<li><b>Write Ops</b>. The client directly writes optimistically in the data source any data cells it wishes adding the <i>start timestamp</i> as the version of each data cell. The metadata of each cell written is added also to the so-called <i>write-set</i> of the transaction.</li>
</ul>
<p>To commit a transaction, the client sends the <i>write-set</i> of the transaction to the <i>TSO</i>, which will check for conflicts in the transaction <i>write-set</i> with other transactions executing concurrently:</p>
-
<ul>
-
+
<li><b>Conflicts</b>. The transaction is aborted and the <i>roll-back</i> outcome is returned to the client.</li>
-
<li><b>No conflicts</b>. The TSO assigns a <i>commit timestamp</i> to the transaction, writes the mapping <i>start timestamp -> commit timestamp</i> to the <i>CT</i> and returns <i>commit</i> as an outcome for the transaction to the client.</li>
</ul>
<p>On receiving the outcome for the transaction, the client:</p>
-
<ul>
-
+
<li><b>For roll-backs</b>, it clears the written cells.</li>
-
<li><b>For commits</b>, it updates the <i>shadow cells</i> for the cells in the <i>write-set</i> and clears the entry for that transaction in the <i>CT</i>.</li>
</ul>
<p>The following sections show step-by-step the process for creating transactions in client applications with the Omid APIs.</p></div>
@@ -254,17 +236,20 @@
<p>In order to use transactions, a client application needs to create an instance of the <tt>TransactionManager</tt> interface with is part of the Transactional Client described in the architecture. The current Omid version offers an implementation of a transaction manager for HBase. Please, make sure <tt>core-site.xml</tt> and <tt>hbase-site.xml</tt> HBase configuration files are present in the CLASSPATH of your client application.</p>
<p>To create a transaction manager just add the following code to your application:</p>
-<div class="source">
-<div class="source"><pre class="prettyprint"> ...
+<div>
+<div>
+<pre class="source"> ...
TransactionManager tm = HBaseTransactionManager.newInstance();
...
</pre></div></div>
+
<p>If nothing is specified, the HBase transaction manager instance is created with default configuration settings loaded from the <tt>default-hbase-omid-client-config.yml</tt> file included in the HBase Omid client jar. To change the client default settings, there are two possibilities:</p>
<p>1) Put the specific configuration settings in a file named <tt>hbase-omid-client-config.yml</tt> and include it in the CLASSPATH. The file has the following format:</p>
-<div class="source">
-<div class="source"><pre class="prettyprint"># HBase related
+<div>
+<div>
+<pre class="source"># HBase related
commitTableName: MY_OWN_OMID_COMMIT_TABLE_NAME
# TSO/ZK connection
@@ -276,10 +261,12 @@ omidClientConfiguration: !!com.yahoo.omid.tso.client.OmidClientConfiguration
metrics: !!com.yahoo.omid.metrics.NullMetricsProvider [ ]
</pre></div></div>
+
<p>2) Create an instance of the <tt>HBaseOmidClientConfiguration</tt> class in the application code and pass it in the creation of the transaction manager instance:</p>
-<div class="source">
-<div class="source"><pre class="prettyprint"> ...
+<div>
+<div>
+<pre class="source"> ...
HBaseOmidClientConfiguration omidClientConfiguration = new HBaseOmidClientConfiguration();
omidClientConfiguration.setConnectionType(DIRECT);
omidClientConfiguration.setConnectionString("my_tso_server_host:54758");
@@ -288,33 +275,39 @@ metrics: !!com.yahoo.omid.metrics.NullMetricsProvider [ ]
TransactionManager tm = HBaseTransactionManager.newInstance(omidClientConfiguration);
...
</pre></div></div>
+
<p>Please, refer to the <a class="externalLink" href="https://github.com/apache/incubator-omid/tree/master/examples/src/main/java/org/apache/omid/examples/ConfigurationExample.java">ConfigurationExample</a> in the source code to experiment with the configuration options.</p></div>
<div class="section">
<h2><a name="Creating_Transactions"></a>Creating Transactions</h2>
<p>Once the <tt>TransactionManager</tt> is created, client applications can use its interface to demarcate transactional boundaries.</p>
<p>In order to create a transaction the <tt>TransactionManager.begin()</tt> method is used:</p>
-<div class="source">
-<div class="source"><pre class="prettyprint"> ...
+<div>
+<div>
+<pre class="source"> ...
Transaction tx = tm.begin();
...
</pre></div></div>
+
<p>The transaction manager will return an instance of the <tt>Transaction</tt> interface representing the recently created transaction. This instance is necessary to instruct the operations on the data source, in which transactional context they should operate (See next section).</p></div>
<div class="section">
<h2><a name="Executing_Transactional_Operations"></a>Executing Transactional Operations</h2>
<p>In order to perform transaction operations on data, the client application requires to use a wrapper on the HBase’s <tt>HTableInterface</tt> abstraction. The wrapper is called <tt>TTable</tt> and is also part of what is described as Transactional Client in the Omid architecture (See section <a href="index.html#What_is_Omid">About Omid</a>). <tt>TTable</tt> basically offers the same interface as <tt>HTableInterface</tt> enhanced with a parameter representing the transactional context. As was previously described, a <tt>Transaction</tt> instance is obtained on return of <tt>TransactionManager.begin()</tt> method calls.</p>
-<div class="source">
-<div class="source"><pre class="prettyprint"> ...
+<div>
+<div>
+<pre class="source"> ...
TTable txTable = new TTable(conf, "EXAMPLE_TABLE");
...
</pre></div></div>
+
<p>Once the access point to the data has been created, applications can use it to trigger transactional operations:</p>
-<div class="source">
-<div class="source"><pre class="prettyprint"> private final byte[] family = Bytes.toBytes("EXAMPLE_CF");
+<div>
+<div>
+<pre class="source"> private final byte[] family = Bytes.toBytes("EXAMPLE_CF");
private final byte[] qualifier = Bytes.toBytes("foo");
...
@@ -330,14 +323,16 @@ metrics: !!com.yahoo.omid.metrics.NullMetricsProvider [ ]
txTable.put(tx, updatedRow);
...
-</pre></div></div></div>
+</pre></div></div>
+</div>
<div class="section">
<h2><a name="Committing_and_Aborting_Transactions"></a>Committing and Aborting Transactions</h2>
<p>Once the client application has finished reading/writting from/into the datasource, it must decide whether to make the changes visible or to discard them. In order to do this, it must instruct the Omid <tt>TransactionManager</tt> either to <tt>commit()</tt> or to <tt>rollback()</tt> the transactional context where the changes were produced. In case of commit, the TSO server will be notified to perform the SI validation phase. If the validation succeeds the changes will be visible to new transactions started from that point on. Otherwise, it will roll back the changes.</p>
<p>In order to commit the data, the client application should do something like this:</p>
-<div class="source">
-<div class="source"><pre class="prettyprint"> ...
+<div>
+<div>
+<pre class="source"> ...
try {
...
tm.commit(tx);
@@ -353,10 +348,12 @@ metrics: !!com.yahoo.omid.metrics.NullMetricsProvider [ ]
}
</pre></div></div>
+
<p>A transaction can also be specifically aborted, for example if something goes wrong when executing the business logic:</p>
-<div class="source">
-<div class="source"><pre class="prettyprint"> ...
+<div>
+<div>
+<pre class="source"> ...
try {
...
if( ! some_business_logic_condition ) {
@@ -368,13 +365,15 @@ metrics: !!com.yahoo.omid.metrics.NullMetricsProvider [ ]
...
}
-</pre></div></div></div>
+</pre></div></div>
+</div>
<div class="section">
<h2><a name="Complete_Example"></a>Complete Example</h2>
<p>The following example summarizes the steps described above.</p>
-<div class="source">
-<div class="source"><pre class="prettyprint">import org.apache.hadoop.hbase.client.Put;
+<div>
+<div>
+<pre class="source">import org.apache.hadoop.hbase.client.Put;
import org.apache.hadoop.hbase.util.Bytes;
import com.yahoo.omid.transaction.HBaseTransactionManager;
import com.yahoo.omid.transaction.TTable;
@@ -427,7 +426,8 @@ public class Example {
}
-</pre></div></div></div>
+</pre></div></div>
+</div>
<div class="section">
<h2><a name="Additional_Examples"></a>Additional Examples</h2>
<p>The <tt>examples</tt> module contains <a class="externalLink" href="https://github.com/apache/incubator-omid/tree/master/examples/src/main/java/org/apache/omid/examples">complete examples</a> showing the Omid functionality that can be executed in your Omid+HBase environment. Just clone the Omid project, go to the <tt>examples</tt> module and execute <tt>mvn clean package</tt> to create a tar.gz file that includes all the examples. In order to execute each example, just execute the <tt>run.sh</tt> script and follow the instructions.</p></div>