Merge pull request #6 from starkj/transaction

Transaction

doc/JCR_TO_PHPCR.txt

@@ -1,4 +1,4 @@
-Version: 2011-05-11
+Version: 2011-06-29
 http://phpcr.github.com
 
 
@@ -225,6 +225,53 @@ Note that clients of PHPCR can not control what UUID a new node gets. It is up
 to the implementation how to assign UUIDs.
 
 
+Transactions
+************
+
+As there is a standard for transactions in Java (Java Transaction API (JTA))
+the JCR spec does not define any own methods to perform transactions but refers
+to the Java standard.
+
+So transactions are not part of the JCR spec. To give the user the ability for
+transactions PHPCR specifies it's own interface which is derived from the Java
+interface javax.transaction.UserTransaction.
+
+The JTA comes with two general approaches to transactions, container managed
+transactions and user managed transactions. Container managed transactions are
+completely left out in PHPCR even though it's required by the JCR spec.
+
+The PHPCR UserTransaction interface shall provide a transaction mechanism in
+a way the original Java UserTransaction interface can be used for transactions
+while working with the JCR API. Have a look at the JCR spec for an example how
+you can work with transactions. You can obtain a UserTransaction object by
+calling Session::getTransactionManager().
+
+Main differences to the original Java UserTransaction:
+ * The Java method getStatus() is named inTransaction().
+ * The Java method setRollbackOnly() is dropped.
+ * Some exceptions specified by the Java spec are replaced by exceptions already
+   specified by PHPCR:
+   - NotSupportedException -> \PHPCR\UnsupportedRepositoryOperationException
+   - SystemException -> \PHPCR\RepositoryException
+   - java.lang.SecurityException -> \PHPCR\AccessDeniedException
+ * New PHPCR exception specified by the Java spec:
+   - RollbackException -> \PHPCR\Transaction\RollbackException
+ * Standrad Java exception exchanged by SPL PHP exception:
+   - java.lang.IllegalStateException -> LogicException
+ * Two Java exceptions were dropped:
+   - HeuristicMixedException
+   - HeuristicRollbackException
+
+An implementation of the UserTransaction interface has to take care of that if
+a transaction is startet every following request to the repository will be
+done in the transactions context.
+
+It shall also be possible to use the UserTransaction interface on a deeper
+level of a PHPCR implementation e.g. that a $session->save() automatically
+starts and ends a transaction before and after persisting all changes to the
+backend (if the session is not yet in a transaction).
+
+
 Drawing the line
 ****************
 

src/PHPCR/SessionInterface.php

@@ -93,6 +93,14 @@ interface SessionInterface
      */
     function getRepository();
 
+    /**
+     * Returns the UserTransaction object associated with this session
+     *
+     * @return \PHPCR\Transaction\UserTransactionInterface a UserTransaction object.
+     * @api
+     */
+    function getTransactionManager();
+
     /**
      * Gets the user ID associated with this Session.
      *

src/PHPCR/Transaction/RollbackException.php

@@ -0,0 +1,42 @@
+<?php
+
+/**
+ * This file is part of the PHPCR API and was originally ported from the Java
+ * JCR API to PHP by Karsten Dambekalns for the FLOW3 project.
+ *
+ * Copyright 2008-2011 Karsten Dambekalns <karsten@typo3.org>
+ *
+ * This file in particular is derived from the Java UserTransaction Interface 
+ * of the package javax.transaction. For more information about the Java 
+ * interface have a look at
+ * http://download.oracle.com/javaee/6/api/javax/transaction/package-summary.html
+ *
+ * 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.
+ *
+ * @license http://www.apache.org/licenses/LICENSE-2.0 Apache Software License 2.0
+ * @link http://phpcr.github.com/
+ */
+
+namespace PHPCR\Transaction;
+
+/**
+ * RollbackException exception is thrown when the transaction has been rolled back instead of committed.
+ *
+ * @author Johannes Stark <starkj@gmx.de>
+ * @package phpcr
+ * @subpackage interfaces
+ * @api
+ */
+class RollbackException extends \PHPCR\RepositoryException
+{
+}

src/PHPCR/Transaction/UserTransactionInterface.php

@@ -0,0 +1,124 @@
+<?php
+
+/**
+ * This file is part of the PHPCR API and was originally ported from the Java
+ * JCR API to PHP by Karsten Dambekalns for the FLOW3 project.
+ *
+ * Copyright 2008-2011 Karsten Dambekalns <karsten@typo3.org>
+ *
+ * This file in particular is derived from the Java UserTransaction Interface
+ * of the package javax.transaction. For more information about the Java
+ * interface have a look at
+ * http://download.oracle.com/javaee/6/api/javax/transaction/package-summary.html
+ *
+ * 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.
+ *
+ * @license http://www.apache.org/licenses/LICENSE-2.0 Apache Software License 2.0
+ * @link http://phpcr.github.com/
+ */
+
+namespace PHPCR\Transaction;
+
+/**
+ * As there is no transaction standard in PHP this interface should provide a
+ * transaction mechanism in a way the original Java UserTransaction interface
+ * can be used for transactions while working with the JCR API.
+ *
+ * Have a look at the JCR spec for an example how you can work with transactions.
+ * You can obtain a UserTransaction object by calling
+ * Session::getTransactionManager().
+ *
+ * @author Johannes Stark <starkj@gmx.de>
+ * @package phpcr
+ * @subpackage interfaces
+ * @api
+ */
+interface UserTransactionInterface
+{
+
+    /**
+     * Begin new transaction associated with current session.
+     *
+     * @return void
+     *
+     * @throws \PHPCR\UnsupportedRepositoryOperationException Thrown if a transaction
+     *      is already started and the transaction implementation or backend does not
+     *      support nested transactions.
+     *
+     * @throws \PHPCR\RepositoryException Thrown if the transaction implementation
+     *      encounters an unexpected error condition.
+     */
+    public function begin();
+
+    /**
+     *
+     * Complete the transaction associated with the current session.
+     *
+     * @return void
+     *
+     * @throws \PHPCR\Transaction\RollbackException Thrown to indicate that the
+     *      transaction has been rolled back rather than committed.
+     * @throws \PHPCR\AccessDeniedException Thrown to indicate that the
+     *      application is not allowed to commit the transaction.
+     * @throws LogicException Thrown if the current session is not associated 
+     *      with a transaction.
+     * @throws \PHPCR\RepositoryException Thrown if the transaction implementation
+     *      encounters an unexpected error condition.
+     */
+    public function commit();
+
+    /**
+     *
+     * Obtain the status if the current session is inside of a transaction or not.
+     *
+     * @return boolean
+     *
+     * @throws \PHPCR\RepositoryException Thrown if the transaction implementation
+     *      encounters an unexpected error condition.
+     */
+    public function inTransaction();
+
+    /**
+     *
+     * Roll back the transaction associated with the current session.
+     *
+     * @return void
+     *
+     * @throws \PHPCR\AccessDeniedException Thrown to indicate that the
+     *      application is not allowed to roll back the transaction.
+     * @throws LogicException Thrown if the current session is not associated with
+     *      a transaction.
+     * @throws \PHPCR\RepositoryException Thrown if the transaction implementation
+     *      encounters an unexpected error condition.
+     */
+    public function rollback();
+
+    /**
+     *
+     * Modify the timeout value that is associated with the transaction started by
+     * the current application with the begin method. If an application has not
+     * called this method, the transaction service uses some default value for the
+     * transaction timeout.
+     *
+     * @param int $seconds The value of the timeout in seconds. If the value is zero,
+     *      the transaction service restores the default value. If the value is
+     *      negative a RepositoryException is thrown.
+     *
+     * @return void
+     *
+     * @throws \PHPCR\RepositoryException Thrown if the transaction implementation
+     *      encounters an unexpected error condition.
+     */
+    public function setTransactionTimeout($seconds = 0);
+
+}