From 792915b76318cecc45781c9b93bcc43cc7d40bd3 Mon Sep 17 00:00:00 2001
From: Michael Wallner <mike@php.net>
Date: Fri, 26 Sep 2014 12:22:35 +0200
Subject: [PATCH] pq\Transaction docs

---
 pq/Transaction.md                     | 27 ++++++++++++++++
 pq/Transaction/__construct.md         | 34 ++++++++++++++++++++
 pq/Transaction/commit.md              | 15 +++++++++
 pq/Transaction/commitAsync.md         | 14 ++++++++
 pq/Transaction/createLOB.md           | 38 ++++++++++++++++++++++
 pq/Transaction/exportLOB.md           | 17 ++++++++++
 pq/Transaction/exportSnapshot.md      | 19 +++++++++++
 pq/Transaction/exportSnapshotAsync.md | 14 ++++++++
 pq/Transaction/importLOB.md           | 46 +++++++++++++++++++++++++++
 pq/Transaction/importSnapshot.md      | 19 +++++++++++
 pq/Transaction/importSnapshotAsync.md | 18 +++++++++++
 pq/Transaction/openLOB.md             | 21 ++++++++++++
 pq/Transaction/rollback.md            | 16 ++++++++++
 pq/Transaction/rollbackAsync.md       | 15 +++++++++
 pq/Transaction/savepoint.md           | 38 ++++++++++++++++++++++
 pq/Transaction/savepointAsync.md      | 14 ++++++++
 16 files changed, 365 insertions(+)
 create mode 100644 pq/Transaction.md
 create mode 100644 pq/Transaction/__construct.md
 create mode 100644 pq/Transaction/commit.md
 create mode 100644 pq/Transaction/commitAsync.md
 create mode 100644 pq/Transaction/createLOB.md
 create mode 100644 pq/Transaction/exportLOB.md
 create mode 100644 pq/Transaction/exportSnapshot.md
 create mode 100644 pq/Transaction/exportSnapshotAsync.md
 create mode 100644 pq/Transaction/importLOB.md
 create mode 100644 pq/Transaction/importSnapshot.md
 create mode 100644 pq/Transaction/importSnapshotAsync.md
 create mode 100644 pq/Transaction/openLOB.md
 create mode 100644 pq/Transaction/rollback.md
 create mode 100644 pq/Transaction/rollbackAsync.md
 create mode 100644 pq/Transaction/savepoint.md
 create mode 100644 pq/Transaction/savepointAsync.md

diff --git a/pq/Transaction.md b/pq/Transaction.md
new file mode 100644
index 0000000..e585deb
--- /dev/null
+++ b/pq/Transaction.md
@@ -0,0 +1,27 @@
+# class pq\Transaction
+
+A database transaction.
+
+> ***NOTE:***  
+  Transactional properties like pq\Transaction::$isolation, pq\Transaction::$readonly and pq\Transaction::$deferrable can be changed after the transaction begun and the first query has been executed. Doing this will lead to appropriate `SET TRANSACTION` queries.
+
+## Constants:
+
+* READ_COMMITTED  
+  Transaction isolation level where only rows committed before the transaction began can be seen.
+* REPEATABLE_READ  
+  Transaction isolation level where only rows committed before the first query was executed in this transaction.
+* SERIALIZABLE  
+  Transaction isolation level that guarantees serializable repeatability which might lead to serialization_failure on high concurrency.
+
+## Properties:
+
+* public (readonly) pq\Connection $connection  
+  The connection the transaction was started on.
+* public int $isolation = pq\Transaction::READ_COMMITTED  
+  The transaction isolation level.
+* public bool $readonly = FALSE  
+  Whether this transaction performs read only queries.
+* public bool $deferrable = FALSE  
+  Whether the transaction is deferrable. See pq\Connection::startTransaction().
+
diff --git a/pq/Transaction/__construct.md b/pq/Transaction/__construct.md
new file mode 100644
index 0000000..8a2dfcd
--- /dev/null
+++ b/pq/Transaction/__construct.md
@@ -0,0 +1,34 @@
+# void pq\Transaction::__construct(pq\Connection $conn[, bool $async = FALSE[, int $isolation = pq\Transaction::READ_COMMITTED[, bool $readonly = FALSE[, bool $deferrable = FALSE]]]])
+
+Start a transaction.
+See pq\Connection::startTransaction().
+
+## Params:
+
+* pq\Connection $conn  
+  The connection to start the transaction on.
+* Optional bool $async = FALSE  
+  Whether to start the transaction [asynchronously](pq/Connection/: Asynchronous Usage).
+* Optional int $isolation = pq\Transaction::READ_COMMITTED  
+  The transaction isolation level (defaults to pq\Connection::$defaultTransactionIsolation).
+* Optional bool $readonly = FALSE  
+  Whether the transaction is readonly (defaults to pq\Connection::$defaultTransactionReadonly).
+* Optional bool $deferrable = FALSE  
+  Whether the transaction is deferrable (defaults to pq\Connection::$defaultTransactionDeferrable).
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pq\Exception\RuntimeException
+
+
+## Example:
+
+	<?php
+	
+	$connection = new pq\Connection;
+	$transaction = new pq\Transaction(
+		$connection, FALSE, pq\Transaction::REPEATABLE_READ);
+	
+	?>
diff --git a/pq/Transaction/commit.md b/pq/Transaction/commit.md
new file mode 100644
index 0000000..2e354f6
--- /dev/null
+++ b/pq/Transaction/commit.md
@@ -0,0 +1,15 @@
+# void pq\Transaction::commit()
+
+Commit the transaction or release the previous savepoint.
+See pq\Transaction::savepoint().
+
+## Params:
+
+None.
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pq\Exception\RuntimeException
+* pq\Exception\DomainException
diff --git a/pq/Transaction/commitAsync.md b/pq/Transaction/commitAsync.md
new file mode 100644
index 0000000..75d8f69
--- /dev/null
+++ b/pq/Transaction/commitAsync.md
@@ -0,0 +1,14 @@
+# void pq\Transaction::commitAsync()
+
+[Asynchronously](pq/Connection/: Asynchronous Usage) commit the transaction or release the previous savepoint.
+See pq\Transaction::commit() and pq\Transaction::savepoint().
+
+## Params:
+
+None.
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pq\Exception\RuntimeException
diff --git a/pq/Transaction/createLOB.md b/pq/Transaction/createLOB.md
new file mode 100644
index 0000000..dbd48e9
--- /dev/null
+++ b/pq/Transaction/createLOB.md
@@ -0,0 +1,38 @@
+# pq\LOB pq\Transaction::createLOB([int $mode = pq\LOB::RW])
+
+Create a new *large object* and open it.
+See pq\Transaction::openLOB().
+
+## Params:
+
+* Optional int $mode = pq\LOB::RW  
+  How to open the *large object* (read, write or both; see pq\LOB constants).
+
+## Returns:
+
+* pq\LOB, instance of the new *large object*.
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pq\Exception\RuntimeException
+
+## Example:
+
+	<?php
+	
+	$connection = new pq\Connection;
+	$transaction = $connection->startTransaction();
+	
+	$lob = $transaction->createLOB();
+	$lob->write("Hello World!");
+	
+	// close the LOB before unlinking
+	$oid = $lob->oid;
+	$lob = null;
+	
+	$transaction->unlinkLOB($oid);
+	$transaction->commit();
+	
+	?>
diff --git a/pq/Transaction/exportLOB.md b/pq/Transaction/exportLOB.md
new file mode 100644
index 0000000..0f678e2
--- /dev/null
+++ b/pq/Transaction/exportLOB.md
@@ -0,0 +1,17 @@
+# void pq\Transaction::exportLOB(int $oid, string $path)
+
+Export a *large object* to a local file.
+See pq\Transaction::importLOB().
+
+## Params:
+
+* int $oid  
+  The OID of the *large object*.
+* string $path  
+  The path of a local file to export to.
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pq\Exception\RuntimeException
diff --git a/pq/Transaction/exportSnapshot.md b/pq/Transaction/exportSnapshot.md
new file mode 100644
index 0000000..5d4a7d5
--- /dev/null
+++ b/pq/Transaction/exportSnapshot.md
@@ -0,0 +1,19 @@
+# string pq\Transaction::exportSnapshot()
+
+Export a snapshot for transaction synchronization.
+See pq\Transaction::importSnapshot().
+
+## Params:
+
+None.
+
+## Returns:
+
+* string, the snapshot idfentifier usabel with pq\Transaction::importSnapshot().
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pq\Exception\RuntimeException
+* pq\Exception\DomainException
diff --git a/pq/Transaction/exportSnapshotAsync.md b/pq/Transaction/exportSnapshotAsync.md
new file mode 100644
index 0000000..3152d2c
--- /dev/null
+++ b/pq/Transaction/exportSnapshotAsync.md
@@ -0,0 +1,14 @@
+# void pq\Transaction::exportSnapshotAsync()
+
+[Asynchronously](pq/Connection/: Asynchronous Usage) export a snapshot for transaction synchronization.
+See pq\Transaction::exportSnapshot().
+
+## Params:
+
+None.
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pq\Exception\RuntimeException
diff --git a/pq/Transaction/importLOB.md b/pq/Transaction/importLOB.md
new file mode 100644
index 0000000..a0f747f
--- /dev/null
+++ b/pq/Transaction/importLOB.md
@@ -0,0 +1,46 @@
+# int pq\Transaction::importLOB(string $local_path[, int $oid = 0)
+
+Import a local file into a *large object*.
+
+## Params:
+
+* string $local_path  
+  A path to a local file to import.
+* Optional int $oid = 0  
+  The target OID. A new *large object* will be created if empty.
+
+## Returns:
+
+* int, the (new) OID of the *large object*.
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pq\Exception\RuntimeException
+
+## Example:
+
+	<?php
+	
+	$connection = new pq\Connection;
+	$transaction = $connection->startTransaction();
+	
+	$oid = $transaction->importLOB(__FILE__);
+	$lob = $transaction->openLOB($oid);
+	
+	var_dump($lob);
+	
+	?>
+
+Yields:
+
+	object(pq\LOB)#5 (3) {
+	  ["transaction"]=> {
+	  	...
+	  }
+	  ["oid"]=>
+	  int(74492)
+	  ["stream"]=>
+	  resource(6) of type (stream)
+	}
diff --git a/pq/Transaction/importSnapshot.md b/pq/Transaction/importSnapshot.md
new file mode 100644
index 0000000..46e4724
--- /dev/null
+++ b/pq/Transaction/importSnapshot.md
@@ -0,0 +1,19 @@
+# void pq\Transaction::importSnapshot(string $snapshot_id)
+
+Import a snapshot from another transaction to synchronize with.
+See pq\Transaction::exportSnapshot().
+
+> ***NOTE:***  
+  The transaction must have an isolation level of at least pq\Transaction::REPEATABLE_READ.
+
+## Params:
+
+* string $snapshot_id  
+  The snapshot identifier obtained by exporting a snapshot from a transaction.
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pq\Exception\RuntimeException
+* pq\Exception\DomainException
diff --git a/pq/Transaction/importSnapshotAsync.md b/pq/Transaction/importSnapshotAsync.md
new file mode 100644
index 0000000..c62e1b3
--- /dev/null
+++ b/pq/Transaction/importSnapshotAsync.md
@@ -0,0 +1,18 @@
+# void pq\Transaction::importSnapshotAsync(string $snapshot_id)
+
+[Asynchronously](pq/Connection/: Asynchronous Usage) import a snapshot from another transaction to synchronize with.
+See pq\Transaction::importSnapshot().
+
+> ***NOTE:***  
+  The transaction must have an isolation level of at least pq\Transaction::REPEATABLE_READ.
+
+## Params:
+
+* string $snapshot_id  
+  The snapshot identifier obtained by exporting a snapshot from a transaction.
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pq\Exception\RuntimeException
diff --git a/pq/Transaction/openLOB.md b/pq/Transaction/openLOB.md
new file mode 100644
index 0000000..cd6d54a
--- /dev/null
+++ b/pq/Transaction/openLOB.md
@@ -0,0 +1,21 @@
+# pq\LOB pq\Transaction::openLOB(int $oid[, int $mode = pq\LOB::RW])
+
+Open a *large object*.
+See pq\Transaction::createLOB().
+
+## Params:
+
+* int $oid  
+  The OID of the *large object*.
+* Optional int $mode = pq\LOB::RW  
+  Operational mode; read, write or both.
+
+## Returns:
+
+* pq\LOB, instance of the opened *large object*.
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pq\Exception\RuntimeException
diff --git a/pq/Transaction/rollback.md b/pq/Transaction/rollback.md
new file mode 100644
index 0000000..3e7aa94
--- /dev/null
+++ b/pq/Transaction/rollback.md
@@ -0,0 +1,16 @@
+# void pq\Transaction::rollback()
+
+Rollback the transaction or to the previous savepoit within this transction.
+See pq\Transaction::commit() and pq\Transaction::savepoint().
+
+## Params:
+
+None.
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pq\Exception\RuntimeException
+* pq\Exception\DomainException
+
diff --git a/pq/Transaction/rollbackAsync.md b/pq/Transaction/rollbackAsync.md
new file mode 100644
index 0000000..adf6bf2
--- /dev/null
+++ b/pq/Transaction/rollbackAsync.md
@@ -0,0 +1,15 @@
+# void pq\Transaction::rollbackAsync()
+
+[Asynchronously](pq/Connection/: Asynchronous Usage) rollback the transaction or to the previous savepoit within this transction.
+See pq\Transaction::rollback() and pq\Transaction::savepoint().
+
+## Params:
+
+None.
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pq\Exception\RuntimeException
+
diff --git a/pq/Transaction/savepoint.md b/pq/Transaction/savepoint.md
new file mode 100644
index 0000000..1e8922e
--- /dev/null
+++ b/pq/Transaction/savepoint.md
@@ -0,0 +1,38 @@
+# void pq\Transaction::savepoint()
+
+Create a `SAVEPOINT` within this transaction.
+
+> ***NOTE:***  
+  pq\Transaction tracks an internal counter as savepoint identifier.
+  
+## Params:
+
+None.
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pq\Exception\RuntimeException
+
+
+## Example:
+
+	<?php
+	
+	$connection = new pq\Connection;
+	$transaction = $connection->startTransaction();
+	
+	// create a savepoint
+	$transaction->savepoint();
+	// create another savepoint
+	$transaction->savepoint();
+	
+	// rollback to previous savepoint
+	$transaction->rollback();
+	// release first savepoint
+	$transaction->commit();
+	// commit transaction
+	$transaction->commit();
+	
+	?>
diff --git a/pq/Transaction/savepointAsync.md b/pq/Transaction/savepointAsync.md
new file mode 100644
index 0000000..8c45122
--- /dev/null
+++ b/pq/Transaction/savepointAsync.md
@@ -0,0 +1,14 @@
+# void pq\Transaction::savepointAsync()
+
+[Asynchronously](pq/Connection/: Asynchronous Usage) create a `SAVEPOINT` within this transaction.
+See pq\Transaction::savepoint().
+
+## Params:
+
+None.
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pq\Exception\RuntimeException
-- 
2.30.2