* The Session object is returned by {@link Repository#login}. * It encapsulates both the authorization settings of a particular user (as specified by the * passed Credentials)and a binding to the workspace specified by the * workspaceName passed on login. *

* Each Session object is associated one-to-one with a Workspace object. * The Workspace object represents a "view" of an actual repository workspace entity * as seen through the authorization settings of its associated Session. * * @author Markus Nix * @package phpcr */ interface Session { /** * Returns the Repository object through which this session was * acquired. * * @return a {@link Repository} object. */ public function getRepository(); /** * Gets the user ID that was used to acquire this session. This method is free to return an * "anonymous user id" or null if the Credentials used to acquire this session happens not * to have provided a real user ID (for example, if instead of SimpleCredentials some other * implementation of Credentials was used). * * @return the user id from the credentials used to acquire this session. */ public function getUserID(); /** * Returns the value of the named attribute as an Object, or null if no attribute of the * given name exists. See {@link Session#getAttributeNames}. * * @param name the name of an attribute passed in the credentials used to acquire this session. * * @return the value of the attribute. */ public function getAttribute( $name ); /** * Returns the names of the attributes set in this session as a result of the Credentials that were * used to acquire it. Not all Credentials implementations will contain attributes (though, for example, * SimpleCredentials does allow for them). This method returns an empty array if the * Credentials instance used to acquire this Session did not provide attributes. * * @return A string array containing the names of all attributes passed in the credentials used to acquire this session. */ public function getAttributeNames(); /** * Returns true if this Session object is usable by the client. Otherwise, * returns false. A usable Session is one that is neither logged-out, * timed-out nor in any other way disconnected from the repository. * * @return true if this Session is usable, false otherwise. */ public function isLive(); /** * This method returns a ValueFactory that is used to create Value * objects for use in setting of repository properties. * * If writing to the repository is not supported (because this is * a level 1-only implementation, for example) an * UnsupportedRepositoryOperationException will be thrown. * * @return a {@link ValueFactory} object * @throws UnsupportedRepositoryOperationException if writing to the * repository is not supported. * @throws RepositoryException if another error occurs */ public function getValueFactory(); /** * Returns the Workspace attached to this Session. * * @return a {@link Workspace} object. */ public function getWorkspace(); /** * Returns a new session in accordance with the specified (new) Credentials. * Allows the current user to "impersonate" another using incomplete * credentials (perhaps including a user name but no password, for example), * assuming that their original session gives them that permission. *

* The new Session is tied to a new Workspace instance. * In other words, Workspace instances are not re-used. However, * the Workspace instance returned represents the same actual * persistent workspace entity in the repository as is represented by the * Workspace object tied to this Session. *

* Throws a LoginException if the current session does not have * sufficient rights. * * @param credentials A Credentials object * @return a Session object * @throws LoginException if the current session does not have * sufficient rights. * @throws RepositoryException if another error occurs. */ public function impersonate( Credentials $credentials ); /** * Returns the root node of the workspace. * The root node, "/", is the main access point to the content of the * workspace. * * @return The root node of the workspace: a Node object. * * @throws RepositoryException if an error occurs. */ public function getRootNode(); /** * Returns the node specifed by the given UUID. Only applies to nodes that * expose a UUID, in other words, those of mixin node type * mix:referenceable * * @param uuid A universally unique identifier. * @return A Node. * @throws ItemNotFoundException if the specified UUID is not found. * @throws RepositoryException if another error occurs. */ public function getNodeByUUID( $uuid ); /** * Returns the item at the specified absolute path in the workspace. * * @param absPath An absolute path. * @return An Item. * @throws PathNotFoundException if the specified path cannot be found. * @throws RepositoryException if another error occurs. */ public function getItem( $absPath ); /** * Returns true if an item exists at absPath; otherwise returns false. * Also returns false if the specified absPath is malformed. * * @param absPath an absolute path * @return true if an item exists at absPath; otherwise returns false. * @throws RepositoryException if an error occurs. */ public function itemExists( $absPath ); /** * Moves the node at srcAbsPath (and its entire subtree) to the new location * at destAbsPath. *

* In order to persist the change, a save * must be called on the parents of both the source and destination * locations. *

* A ConstraintViolationException is thrown if a node-type * or other constraint violation is detected immediately. Otherwise, * if the violation is only detected later, at save, then a * ConstraintViolationException is thrown by that method. * Implementations may differ as to which constraints are enforced immediately, * and which on save. *

* As well, a ConstraintViolationException will be thrown on * save if an attempt is made to seperately save * either the source or destination node. *

* Note that this behaviour differs from that of * {@link Workspace#move}, which operates directly in the persistent * workspace and does not require a save. *

* The destAbsPath provided must not * have an index on its final element. If it does then a RepositoryException * is thrown. Strictly speaking, the destAbsPath parameter is actually an absolute path * to the parent node of the new location, appended with the new name desired for the * moved node. It does not specify a position within the child node * ordering (if such ordering is supported). If ordering is supported by the node type of * the parent node of the new location, then the newly moved node is appended to the end of the * child node list. *

* This method cannot be used to move just an individual property by itself. * It moves an entire node and its subtree (including, of course, any properties * contained therein). *

* If no node exists at srcAbsPath or no node exists one level above destAbsPath * (i.e. there is no node that will serve as the parent of the moved item) then a * PathNotFoundException is thrown. *

* An ItemExistException is thrown if a property already exists at * destAbsPath or a node already exist there, and same name * siblings are not allowed. *

* A VersionException is thrown if the parent node of destAbsPath or the parent node of * srcAbsPath is versionable and checked-in, or is non-verionable and its nearest versionable * ancestor is checked-in. *

* A LockException is thrown if the move operation would violate a lock. * * @param srcAbsPath the root of the subtree to be moved. * @param destAbsPath the location to which the subtree is to be moved. * @throws ItemExistsException if a property already exists at * destAbsPath or a node already exist there, and same name * siblings are not allowed. * @throws PathNotFoundException if either srcAbsPath or destAbsPath cannot be found. * @throws VersionException if the parent node of destAbsPath or the parent node of srcAbsPath * is versionable and checked-in, or or is non-verionable and its nearest versionable ancestor is checked-in. * @throws ConstraintViolationException if a node-type or other constraint violation is detected immediately. * @throws LockException if the move operation would violate a lock. * @throws RepositoryException if the last element of destAbsPath has an index or if another error occurs. */ public function move( $srcAbsPath, $destAbsPath ); /** * Validates all pending changes currently recorded in this Session. If validation of all * pending changes succeeds, then this change information is cleared from the Session. * If the save occurs outside a transaction, the changes are persisted and thus * made visible to other Sessions. If the save occurs within a transaction, * the changes are not persisted until the transaction is committed. *

* If validation fails, then no pending changes are saved and they remain recorded on the Session. * There is no best-effort or partial save. *

* When an item is saved the item in persistent storage to which pending changes are written is * determined as follows: *

*
• * If the transient item has a UUID, then the changes are written to the persistent item with the same UUID. *
*
• * If the transient item does not have a UUID then its nearest ancestor with a UUID, or the root node * (whichever occurs first) is found, and the relative path from the node in persistent node with that UUID is * used to determine the item in persistent storage to which the changes are to be written. *
*

* Note that save uses the same rules to match items between transient storage and persistent storage * as {@link Node#update} does to match nodes between two workspaces. *

* An AccessDeniedException will be thrown if any of the changes * to be persisted would violate the access privileges of this * Session or if. Also thrown if any of the * changes to be persisted would cause the removal of a node that is currently * referenced by a REFERENCE property that this Session * does not have read access to. *

* A ConstraintViolationException will be thrown if any of the * changes to be persisted would violate a node type restriction. * Additionally, a repository may use this exception to enforce * implementation- or configuration-dependant restrictions. *

* A LockException is thrown if any of the changes to be * persisted would violate a lock. *

* An InvalidItemStateException is thrown if any of the * changes to be persisted conflicts with a change already persisted * through another session and the implementation is such that this * conflict can only be detected at save-time and therefore was not * detected earlier, at change-time. *

* A ReferentialIntegrityException is thrown if any of the * changes to be persisted would cause the removal of a node that is currently * referenced by a REFERENCE property that this Session * has read access to. *

* A VersionException is thrown if the save would make a result in * a change to persistent storage that would violate the read-only status of a * checked-in node. *

* A LockException is thrown if the save would result in a * change to persistent storage that would violate a lock. *

* A RepositoryException will be thrown if another error * occurs. * * @throws AccessDeniedException if any of the changes to be persisted would violate * the access privileges of the this Session. Also thrown if any of the * changes to be persisted would cause the removal of a node that is currently * referenced by a REFERENCE property that this Session * does not have read access to. * @throws LockException if any of the changes to be persisted would violate a lock. * @throws ConstraintViolationException if any of the changes to be persisted would * violate a node type or restriction. Additionally, a repository may use this * exception to enforce implementation- or configuration-dependent restrictions. * @throws InvalidItemStateException if any of the * changes to be persisted conflicts with a change already persisted * through another session and the implementation is such that this * conflict can only be detected at save-time and therefore was not * detected earlier, at change-time. * @throws ReferentialIntegrityException if any of the * changes to be persisted would cause the removal of a node that is currently * referenced by a REFERENCE property that this Session * has read access to. * @throws VersionException if the save would make a result in * a change to persistent storage that would violate the read-only status of a * checked-in node. * @throws LockException if the save would result in a * change to persistent storage that would violate a lock. * @throws RepositoryException if another error occurs. */ public function save(); /** * If keepChanges is false, this method discards all pending changes * currently recorded in this Session and returns all items to reflect the current * saved state. Outside a transaction this state is simply the current state of persistent storage. * Within a transaction, this state will reflect persistent storage as modified by changes that have * been saved but not yet committed. *

* If keepChanges is true then pending change are not discarded but items that do not * have changes pending have their state refreshed to reflect the current saved state, thus revealing * changes made by other sessions. * * @throws RepositoryException if an error occurs. */ public function refresh( $keepChanges ); /** * Returns true if this session holds pending (that is, unsaved) changes; * otherwise returns false. * * @return a boolean * @throws RepositoryException if an error occurs */ public function hasPendingChanges(); /** * Determines whether this Session has permission to perform the specified actions * at the specified absPath. This method quietly returns if the access request is * permitted, or throws Exception otherwise. *

* The actions parameter is a comma separated list of action strings. The following * action strings are defined: *

*
• * add_node: If checkPermission(path, "add_node") returns quietly, then * this Session has permission to add a node at path, otherwise permission * is denied. *
*
• * set_property: If checkPermission(path, "set_property") returns quietly, * then this Session has permission to set (add or change) a property at path, * otherwise permission is denied. *
*
• * remove: If checkPermission(path, "remove") returns quietly, then this * Session has permission to remove an item at path, otherwise permission is denied. *
*
• * read: If checkPermission(path, "read") returns quietly, then this * Session has permission to retrieve (and read the value of, in the case of a property) * an item at path, otherwise permission is denied. *
*

* The information returned through this method will only reflect access control policies * and not other restrictions that may exist. For example, even though checkPermission * may indicate that a particular Session may add a property at /A/B/C, * the node type of the node at /A/B may prevent the addition of a property called * C. * * @throws Exception */ public function checkPermission( $absPath, $actions ); /** * Returns a ContentHandler which can be used to push SAX events into the repository. * If the incoming XML stream (in the form of SAX events) does not appear to be a JCR system view XML document then it is * interpreted as a document view XML document. *

* The incoming XML is deserialized into a subtree of items immediately below the node at * parentAbsPath. *

* The special properties jcr:primaryType and jcr:mixinTypes are * taken into account during deserialization in order to determine the node types of the newly created nodes. *

* This method simply returns the ContentHandler without altering the state of the * repository; the actual deserialization is done through the methods of the ContentHandler. *

* As SAX events are fed into the ContentHandler, the tree of new items is built * in the transient storage of the Session. In order to persist the new content, * save must be called. The advantage of this through-the-session method is that * invalid data can be imported, fixed and then saved. The disadvantage is that a large * import will result in a large cache of pending nodes in the Session. See * {@link Workspace#getImportContentHandler} for a version of this method that does not * go through the Session. *

* A PathNotFoundException is thrown if no node exists at parentAbsPath. *

* A ConstraintViolationException is thrown if the new subtree cannot be added to the node at * parentAbsPath due to node-type or other implementation-specific constraints, and this can * be determined before the first SAX event is sent. Unlike {@link Workspace#getImportContentHandler}, * this method does not enforce node type constraints by throwing SAXExceptions during * deserialization. These constraints are checked on save. *

* A VersionException is thrown if the node at parentAbsPath is versionable * and checked-in, or its nearest versionable ancestor is checked-in. *

* A LockException is thrown if a lock prevents the addition of the subtree. *

* A RepositoryException is thrown if another error occurs. * * @param parentAbsPath the absolute path of a node under which (as child) the imported subtree will be built. * @param mode a four-value flag that governs how incoming UUIDs are handled. * * @return an org.xml.sax.ContentHandler whose methods may be called to feed SAX events into the deserializer. * * @throws PathNotFoundException if no node exists at parentAbsPath. * @throws ConstraintViolationException if the new subtree cannot be added to the node at * parentAbsPath due to node-type or other implementation-specific constraints, and this can * be determined before the first SAX event is sent. * @throws VersionException if the node at parentAbsPath is versionable * and checked-in, or its nearest versionable ancestor is checked-in. * @throws LockException if a lock prevents the addition of the subtree. * @throws RepositoryException if another error occurs. */ public function getImportContentHandler( $parentAbsPath, $mode ); /** * Deserializes an XML document and adds the resulting item subtree as a child of the node at * parentAbsPath. Requires a save to persist. *

* If the incoming XML stream does not appear to be a JCR system view XML document then it is interpreted as a * document view XML document. *

* The special properties jcr:primaryType and jcr:mixinTypes are * taken into account during deserialization in order to determine the node types of the newly * created nodes. *

* The tree of new items is built in the transient storage of the Session. * In order to persist the new content, save must be called. The advantage * of this through-the-session method is that invalid data can be imported, fixed and * then saved. The disadvantage is that a large import will result in a large cache * of pending nodes in the Session. See {@link Workspace#importXML} * for a version of this method that does not go through the Session. *

* An IOException is thrown if an I/O error occurs. *

* If no node exists at parentAbsPath, a PathNotFoundException * is thrown. *

* If deserialization would overwrite an exisiting item, an ItemExistsException * is thrown. *

* A ConstraintViolationException is thrown if the new subtree cannot be added to the node at * parentAbsPath due to node-type or other implementation-specific constraints, and this can * be determined before deserialization begins. Unlike {@link Workspace#getImportContentHandler}, * this method does not enforce node type constraints by during * deserialization. These constraints are checked on save. *

* A VersionException is thrown if the node at parentAbsPath is versionable * and checked-in, or its nearest versionable ancestor is checked-in. *

* A LockException is thrown if a lock prevents the addition of the subtree. *

* If the incoming XML is not valid, an InvalidSerializedDataException is thrown. *

* If another error occurs a RepositoryException is thrown. * * @param parentAbsPath the absolute path of the node below which the deserialized subtree is added. * @param in The Inputstream from which the XML to be deserilaized is read. * @param mode a four-value flag that governs how incoming UUIDs are handled. * * @throws IOException if an error during an I/O operation occurs. * @throws PathNotFoundException if no node exists at parentAbsPath. * @throws ItemExistsException if deserialization would overwrite an exisiting item. * @throws ConstraintViolationException if the new subtree cannot be added to the node at * parentAbsPath due to node-type or other implementation-specific constraints, and this can * be determined before deserialization begins. * @throws VersionException if the node at parentAbsPath is versionable * and checked-in, or its nearest versionable ancestor is checked-in. * @throws InvalidSerializedDataException if incoming stream is not a valid XML document. * @throws LockException if a lock prevents the addition of the subtree. * @throws RepositoryException is another error occurs. */ public function importXML( $parentAbsPath, $in, $mode ); /** * Serializes the node (and if noRecurse is false, * the whole subtree) at absPath into a series of SAX events by * calling the methods of the supplied org.xml.sax.ContentHandler. * The resulting XML is in the system view form. Note that absPath * must be the path of a node, not a property. *

* If skipBinary is true then any properties of * PropertyType.BINARY will be ignored and will not appear in * the serialized output. If skipBinary is false then the actual * value of each BINARY property is recorded using Base64 encoding. *

* If noRecurse is true then only the node at * absPath and its properties, but not its child nodes, are * serialized. If noRecurse is false then the entire subtree * rooted at absPath is serialized. *

* If the user lacks read access to some subsection of the specified tree, * that section simply does not get serialized, since, from the user's * point of view, it is not there. *

* The serialized output will reflect the state of the current workspace as * modified by the state of this Session. This means that * pending changes (regardless of whether they are valid according to * node type constraints) and the current session-mapping of namespaces * are reflected in the output. *

* A PathNotFoundException is thrown if no node exists at absPath. *

* A SAXException is thrown if an error occurs while feeding events to the * ContentHandler. * * @param absPath The path of the root of the subtree to be serialized. * This must be the path to a node, not a property * @param contentHandler The org.xml.sax.ContentHandler to * which the SAX events representing the XML serialization of the subtree * will be output. * @param skipBinary A boolean governing whether binary * properties are to be serialized. * @param noRecurse A boolean governing whether the subtree at * absPath is to be recursed. * * @throws PathNotFoundException if no node exists at absPath. * @throws org.xml.sax.SAXException if an error occurs while feeding events to the * org.xml.sax.ContentHandler. * @throws RepositoryException if another error occurs. */ public function exportSystemView( $absPath, $out, $skipBinary, $noRecurse ); /** * Serializes the node (and if noRecurse is false, * the whole subtree) at absPath into a series of SAX events by * calling the methods of the supplied org.xml.sax.ContentHandler. * The resulting XML is in the document view form. Note that absPath * must be the path of a node, not a property. *

* If skipBinary is true then any properties of * PropertyType.BINARY will be ignored and will not appear in * the serialized output. If skipBinary is false then the actual * value of each BINARY property is recorded using Base64 encoding. *

* If noRecurse is true then only the node at * absPath and its properties, but not its child nodes, are * serialized. If noRecurse is false then the entire subtree * rooted at absPath is serialized. *

* If the user lacks read access to some subsection of the specified tree, * that section simply does not get serialized, since, from the user's * point of view, it is not there. *

* The serialized output will reflect the state of the current workspace as * modified by the state of this Session. This means that * pending changes (regardless of whether they are valid according to * node type constraints) and the current session-mapping of namespaces * are reflected in the output. *

* A PathNotFoundException is thrown if no node exists at absPath. *

* A SAXException is thrown if an error occurs while feeding events to the * ContentHandler. * * @param absPath The path of the root of the subtree to be serialized. * This must be the path to a node, not a property * @param out The OutputStream to which the XML * serialization of the subtree will be output. * @param skipBinary A boolean governing whether binary * properties are to be serialized. * @param noRecurse A boolean governing whether the subtree at * absPath is to be recursed. * * @throws PathNotFoundException if no node exists at absPath. * @throws org.xml.sax.SAXException if an error occurs while feeding events to the * org.xml.sax.ContentHandler. * @throws RepositoryException if another error occurs. */ public function exportDocumentView( $absPath, $out, $skipBinary, $noRecurse ); /** * Within the scope of this session, rename a persistently registered * namespace URI to the new prefix. The renaming only affects operations * done through this session. To clear all renamings the client must acquire * a new session. *

* Note that a prefix that is currently mapped in the global namespace registry * to some URI cannot be remapped to a new URI using this method, since this would * make any content stored using the old URI unreadable. An attempt to do * this will throw a NamespaceException. *

* A NamespaceException will be thrown if an attempt is made to remap a URI to a * prefix beginning with "xml". These prefixes are reserved by the XML * specification. *

* A NamespaceException will also be thrown if * the specified uri is not among those registered in the NamespaceRegistry. * * @param prefix a string * @param uri a string * @throws NamespaceException if the specified uri is not registered or an attempt is made to remap to an illegal prefix. * @throws RepositoryException if another error occurs. */ public function setNamespacePrefix( $prefix, $uri ); /** * Returns all prefixes currently set for this session. This includes all * those registered in the NamespaceRegistry but not * over-ridden by a Session.setNamespacePrefix, plus those * currently set locally by Session.setNamespacePrefix. * * @throws RepositoryException if an error occurs * @return a string array */ public function getNamespacePrefixes(); /** * For a given prefix, returns the URI to which it is mapped as currently * set in this Session. If the prefix is unknown, a NamespaceException is thrown. * * @param prefix a string * @return a string * @throws NamespaceException if the prefix is unknown. * @throws RepositoryException if another error occurs */ public function getNamespaceURI( $prefix ); /** * Returns the prefix to which the given URI is mapped * * @param uri a string * @return a string * @throws NamespaceException if the URI is unknown. * @throws RepositoryException if another error occurs */ public function getNamespacePrefix( $uri ); /** * Releases all resources associated with this Session. This method should be called when a * Session is no longer needed. */ public function logout(); /** * Adds the specified lock token to this session. Holding a lock token allows the Session object of the * lock owner to alter nodes that are locked by the lock specified by that particular lock token. * * @param lt a lock token (a string) */ public function addLockToken( $lt ); /** * Returns an array containing all lock tokens currently held by this session. * * @return an array of lock tokens (strings) */ public function getLockTokens(); /** * Removes the specified lock token from this session. * @param lt a lock token (a string) */ public function removeLockToken( $lt ); } ?>