jsr-333: Workspace::removeItem and RepositoryManagerInterface

src/PHPCR/RepositoryManagerInterface.php

@@ -0,0 +1,84 @@
+<?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>
+ *
+ * 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;
+
+/**
+ * A RepositoryManager represents a management view of the Session's Repository
+ * instance.
+ *
+ * This is useful for applications that embed a JCR repository and need a way
+ * to manage the lifecycle of that Repository instance. Each RepositoryManager
+ * object is associated one-to-one with a Session object and is defined by the
+ * authorization settings of that session object.
+ *
+ * The RepositoryManager object can be acquired using a {@link Session} by
+ * calling $session->getWorkspace()->getRepositoryManager()< on a session
+ * object. Likewise, the repository being managed can be found for a given
+ * RepositoryManager object by calling
+ * $mgr->getWorkspace()->getSession()->getRepository().
+ *
+ * @since JCR 2.1
+ */
+interface RepositoryManagerInterface
+{
+    /**
+    * Return the Workspace object through which this repository manager was
+    * created.
+    *
+    * @return WorkspaceInterface
+    */
+    public function getWorkspace();
+
+    /**
+     * Closes the repository by preventing the creation of new sessions and
+     * freeing all resources. The $closeSessionsImmediately parameter dictates
+     * whether existing sessions should be closed immediately or allowed to
+     * close naturally.
+     *
+     * Either way, this method always blocks until all sessions are closed and
+     * the repository has completely terminated.
+     *
+     * Some repository implementations may not allow repositories to be closed,
+     * while other implementations might allow closing only for certain
+     * configurations (e.g., repositories embedded within an application). An
+     * implementation will throw an UnsupportedRepositoryOperationException if
+     * the particular repository cannot be closed, or an AccessDeniedException
+     * when the repository can be closed but the session does not have the
+     * authority to do so.
+     *
+     * @param boolean $closeSessionsImmediately true if all existing sessions
+     *      should be closed immediately, or false if they are to be allowed to
+     *      close naturally.
+     *
+     * @throws AccessDeniedException if the caller does not have authorization
+     *      to close the repository.
+     * @throws UnsupportedRepositoryOperationException if the repository
+     *      implementation does not support or allow the repository to be
+     *      closed.
+     * @throws RepositoryException if an error occurred while shutting down the
+     *      repository.
+     */
+    public function closeRepository($closeSessionsImmediately);
+}

src/PHPCR/WorkspaceInterface.php

@@ -396,6 +396,78 @@ public function cloneFrom($srcWorkspace, $srcAbsPath, $destAbsPath, $removeExist
      */
     public function move($srcAbsPath, $destAbsPath);
 
+    /**
+     * Removes the specified item and its subgraph.
+     *
+     * This is a workspace-write method and therefore is dispatched immediately.
+     * A save is not required. In the absence of a transaction, the changes made
+     * by this method will also be persisted immediately. In the presence of a
+     * transaction the changes will be persisted upon commit of the transaction.
+     *
+     * If a node with same-name siblings is removed, this decrements by one the
+     * indices of all the siblings with indices greater than that of the removed
+     * node. In other words, a removal compacts the array of same-name siblings
+     * and causes the minimal re-numbering required to maintain the original
+     * order but leave no gaps in the numbering.
+     *
+     * A ReferentialIntegrityException will be thrown if the specified item or
+     * an item in its subgraph is currently the target of a REFERENCE property
+     * located in this workspace but outside the specified item's subgraph and
+     * the current Session has read access to that REFERENCE property.
+     *
+     * A ConstraintViolationException will be thrown either on dispatch or on
+     * persist, if removing the specified item would violate a node type or
+     * implementation-specific constraint. Implementations may differ on when
+     * this validation is performed.
+     *
+     * A VersionException will be thrown either on dispatch or on persist, if
+     * the parent node of the specified item is read-only due to a checked-in
+     * node. Implementations may differ on when this validation is performed.
+     *
+     * A LockException will be thrown either on dispatch or on persist, if a
+     * lock prevents the removal of the specified item. Implementations may
+     * differ on when this validation is performed.
+     *
+     * A PathNotFoundException will be thrown either on dispatch or on persist,
+     * if no accessible item is found at at $absPath.
+     *
+     * A AccessDeniedException will be thrown either on dispatch or on persist,
+     * if the specified item or an item in its subgraph is currently the target
+     * of a REFERENCE property located in this workspace but outside the
+     * specified item's subgraph and the current Session <i>does not</i> have
+     * read access to that REFERENCE property.
+     *
+     * @param string $absPath the absolute path of the item to be removed.
+     *
+     * @throws \PHPCR\Version\VersionException if the parent node of the item
+     *      at $absPath is read-only due to a checked-in node and this
+     *      implementation performs this validation immediately.
+     * @throws \PHPCR\Lock\LockException if a lock prevents the removal of the
+     *      specified item and this implementation performs this validation
+     *      immediately.
+     * @throws \PHPCR\NodeType\ConstraintViolationException if removing the
+     *      specified item would violate a node type or implementation-specific
+     *      constraint and this implementation performs this validation
+     *      immediately.
+     * @throws PathNotFoundException if no accessible item is found at $absPath
+     *      and this implementation performs this validation immediately.
+     * @throws AccessDeniedException if the specified item or an item in its
+     *      subgraph is currently the target of a REFERENCE property located in
+     *      this workspace but outside the specified item's subgraph and the
+     *      current Session <i>does not</i> have read access to that REFERENCE
+     *      property and this implementation performs this validation
+     *      immediately.
+     * @throws RepositoryException if another error occurs.
+     *
+     * @see Session::removeItem()
+     *
+     * @since JCR 2.1
+     *
+     * @api
+     */
+    public function removeItem($absPath);
+
+
     /**
      * Returns the LockManager object, through which locking methods are accessed.
      *
@@ -479,6 +551,20 @@ public function getNodeTypeManager();
      */
     public function getObservationManager();
 
+    /**
+     * Return a RepositoryManager that can be used to administer the repository
+     * instance through which this workspace's session was acquired.
+     *
+     * @return RepositoryManagerInterface
+     *
+     * @throws AccessDeniedException if the caller does not have authorization
+     *      to obtain the manager.
+     * @throws RepositoryException if another error occurred.
+     *
+     * @since JCR 2.1
+     */
+    public function getRepositoryManager();
+
     /**
      * Returns the VersionManager object.
      *