[LiskDAO] make objects ephemeral, aka read-only

Summary:
Make any Lisk object ephemeral, aka read-only, so that we can fiddle
around with their state safe in the knowledge that we'll never end up
writing that updated state back to the db.

Test Plan: Added a new test; ran test suite.

Reviewers: epriestley

Reviewed By: epriestley

CC: aran, epriestley

Differential Revision: https://secure.phabricator.com/D1836

src/__phutil_library_map__.php

@@ -401,6 +401,7 @@ phutil_register_library_map(array(
     'JavelinViewExample' => 'applications/uiexample/examples/client',
     'JavelinViewExampleServerView' => 'applications/uiexample/examples/client',
     'LiskDAO' => 'storage/lisk/dao',
+    'LiskEphemeralObjectException' => 'storage/lisk/dao',
     'LiskIsolationTestCase' => 'storage/lisk/dao/__tests__',
     'LiskIsolationTestDAO' => 'storage/lisk/dao/__tests__',
     'LiskIsolationTestDAOException' => 'storage/lisk/dao/__tests__',

src/storage/lisk/dao/LiskDAO.php

@@ -193,6 +193,8 @@ abstract class LiskDAO {
   private static $processIsolationLevel = 0;
   private static $__checkedClasses = array();
 
+  private $__ephemeral = false;
+
   /**
    *  Build an empty object.
    *
@@ -778,6 +780,24 @@ abstract class LiskDAO {
 /* -(  Writing Objects  )---------------------------------------------------- */
 
 
+  /**
+   * Make an object read-only.
+   *
+   * Making an object ephemeral indicates that you will be changing state in
+   * such a way that you would never ever want it to be written to back to the
+   * storage.
+   */
+  public function makeEphemeral() {
+    $this->__ephemeral = true;
+    return $this;
+  }
+
+  private function isEphemeralCheck() {
+    if ($this->__ephemeral) {
+      throw new LiskEphemeralObjectException();
+    }
+  }
+
   /**
    * Persist this object to the database. In most cases, this is the only
    * method you need to call to do writes. If the object has not yet been
@@ -805,6 +825,7 @@ abstract class LiskDAO {
    * @task   save
    */
   public function replace() {
+    $this->isEphemeralCheck();
     return $this->insertRecordIntoDatabase('REPLACE');
   }
 
@@ -818,6 +839,7 @@ abstract class LiskDAO {
    *  @task   save
    */
   public function insert() {
+    $this->isEphemeralCheck();
     return $this->insertRecordIntoDatabase('INSERT');
   }
 
@@ -831,6 +853,7 @@ abstract class LiskDAO {
    *  @task   save
    */
   public function update() {
+    $this->isEphemeralCheck();
     $use_locks = $this->getConfigOption(self::CONFIG_OPTIMISTIC_LOCKS);
 
     $this->willSaveObject();
@@ -899,6 +922,7 @@ abstract class LiskDAO {
    * @task   save
    */
   public function delete() {
+    $this->isEphemeralCheck();
     $this->willDelete();
 
     $conn = $this->establishConnection('w');

src/storage/lisk/dao/LiskEphemeralObjectException.php

@@ -0,0 +1,19 @@
+<?php
+
+/*
+ * Copyright 2012 Facebook, Inc.
+ *
+ * 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.
+ */
+
+final class LiskEphemeralObjectException extends Exception {}

src/storage/lisk/dao/__init__.php

@@ -16,3 +16,4 @@ phutil_require_module('phutil', 'utils');
 
 
 phutil_require_source('LiskDAO.php');
+phutil_require_source('LiskEphemeralObjectException.php');

src/storage/lisk/dao/__tests__/LiskIsolationTestCase.php

@@ -1,7 +1,7 @@
 <?php
 
 /*
- * Copyright 2011 Facebook, Inc.
+ * Copyright 2012 Facebook, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -38,6 +38,19 @@ class LiskIsolationTestCase extends PhabricatorTestCase {
     $this->assertEqual($phid, $dao->getPHID(), 'Expect PHID unchanged.');
   }
 
+  public function testEphemeral() {
+    $dao = new LiskIsolationTestDAO();
+    $dao->save();
+    $dao->makeEphemeral();
+
+    $this->assertException(
+      'LiskEphemeralObjectException',
+      function() use ($dao) {
+        $dao->save();
+      }
+    );
+  }
+
   public function testIsolationContainment() {
     $dao = new LiskIsolationTestDAO();