pq\Transaction docs

diff --git a/pq/Transaction.md b/pq/Transaction.md
new file mode 100644 (file)
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 (file)
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 (file)
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 (file)
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 (file)
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 (file)
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 (file)
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 (file)
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 (file)
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 (file)
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 (file)
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 (file)
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 (file)
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 (file)
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 (file)
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 (file)
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