diff --git a/doc/JCR_TO_PHPCR.txt b/doc/JCR_TO_PHPCR.txt index c108eb8b..3fc291be 100644 --- a/doc/JCR_TO_PHPCR.txt +++ b/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 **************** diff --git a/src/PHPCR/SessionInterface.php b/src/PHPCR/SessionInterface.php index cd2eea83..31c90cf5 100644 --- a/src/PHPCR/SessionInterface.php +++ b/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. * diff --git a/src/PHPCR/Transaction/RollbackException.php b/src/PHPCR/Transaction/RollbackException.php new file mode 100644 index 00000000..0dbfc7fe --- /dev/null +++ b/src/PHPCR/Transaction/RollbackException.php @@ -0,0 +1,42 @@ + + * + * 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 + * @package phpcr + * @subpackage interfaces + * @api + */ +class RollbackException extends \PHPCR\RepositoryException +{ +} diff --git a/src/PHPCR/Transaction/UserTransactionInterface.php b/src/PHPCR/Transaction/UserTransactionInterface.php new file mode 100644 index 00000000..97e3c57c --- /dev/null +++ b/src/PHPCR/Transaction/UserTransactionInterface.php @@ -0,0 +1,124 @@ + + * + * 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 + * @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); + +}