* JBoss DNA (http://www.jboss.org/dna)

* See the COPYRIGHT.txt file distributed with this work for information

* regarding copyright ownership.  Some portions may be licensed

* to Red Hat, Inc. under one or more contributor license agreements.

* See the AUTHORS.txt file in the distribution for a full listing of

* individual contributors.

*

* JBoss DNA is free software. Unless otherwise indicated, all code in JBoss DNA

* is licensed to you under the terms of the GNU Lesser General Public License as

* published by the Free Software Foundation; either version 2.1 of

* the License, or (at your option) any later version.

*

* JBoss DNA is distributed in the hope that it will be useful,

* but WITHOUT ANY WARRANTY; without even the implied warranty of

* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU

* Lesser General Public License for more details.

*

* You should have received a copy of the GNU Lesser General Public

* License along with this software; if not, write to the Free

* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA

* 02110-1301 USA, or see the FSF site: http://www.fsf.org.

*/

* This class represents an interactive session for working with the content within a graph. This session maintains a cache of

* content read from the repository, as well as transient changes that have been made to the nodes within this session that are

* then pushed to the graph when the session is {@link #save() saved}.

* <p>

* Like the other Graph APIs, the mutable objects in this session should not be held onto for very long periods of time. When the

* session is {@link #save() saved} or {{@link #refresh(boolean) refreshed} (or when a node is {@link #save(Node) saved} or

* {@link #refresh(Node, boolean) refreshed}), the session may {@link Node#unload() unload} and discard some of its nodes. Using

* nodes after they are discarded may result in assertion errors (assuming Java assertions are enabled).

* </p>

*

* @param <Payload> the type of the payload object for each node, used to allow the nodes to hold additional cached information

* @param <PropertyPayload> the type of payload object for each property, used to allow the nodes to hold additional cached

*        information

*/

    protected final ListMultimap<Name, Node<Payload, PropertyPayload>> NO_CHILDREN = LinkedListMultimap.create();

    protected final Map<Name, PropertyInfo<PropertyPayload>> NO_PROPERTIES = Collections.emptyMap();

    protected final Authorizer authorizer;

    protected final ExecutionContext context;

    protected final Graph store;

    protected final Node<Payload, PropertyPayload> root;

    protected final Operations<Payload, PropertyPayload> nodeOperations;

    protected final PathFactory pathFactory;

    protected final NodeIdFactory idFactory;

    protected final String workspaceName;

    protected int loadDepth = 1;

    /**

     * A map of the nodes keyed by their identifier.

     */

    protected final Map<NodeId, Node<Payload, PropertyPayload>> nodes = new HashMap<NodeId, Node<Payload, PropertyPayload>>();

    /**

     * A map that records how the changes to a node are dependent upon other nodes.

     */

    protected final Map<NodeId, Dependencies> changeDependencies = new HashMap<NodeId, Dependencies>();

    private LinkedList<Request> requests;

    private BatchRequestBuilder requestBuilder;

    protected Graph.Batch operations;

    /**

     * Create a session that uses the supplied graph and the supplied node operations.

     *

     * @param graph the graph that this session is to use

     * @param workspaceName the name of the workspace that is to be used, or null if the current workspace should be used

     * @param nodeOperations the operations that are to be performed during various stages in the lifecycle of a node, or null if

     *        there are no special operations that should be performed

     */

    public GraphSession( Graph graph,

                         String workspaceName,

                         Operations<Payload, PropertyPayload> nodeOperations ) {

        this(graph, workspaceName, nodeOperations, null);

    }

    /**

     * Create a session that uses the supplied graph and the supplied node operations.

     *

     * @param graph the graph that this session is to use

     * @param workspaceName the name of the workspace that is to be used, or null if the current workspace should be used

     * @param nodeOperations the operations that are to be performed during various stages in the lifecycle of a node, or null if

     *        there are no special operations that should be performed

     * @param authorizer the authorizing component, or null if no special authorization is to be performed

     * @throws IllegalArgumentException if the graph reference is null

     * @throws IllegalArgumentException if the depth is not positive

     */

    public GraphSession( Graph graph,

                         String workspaceName,

                         Operations<Payload, PropertyPayload> nodeOperations,

                         Authorizer authorizer ) {

        assert graph != null;

        this.store = graph;

        this.context = store.getContext();

        if (workspaceName != null) {

            this.workspaceName = this.store.useWorkspace(workspaceName).getName();

        } else {

            this.workspaceName = this.store.getCurrentWorkspaceName();

        }

        this.nodeOperations = nodeOperations != null ? nodeOperations : new NodeOperations<Payload, PropertyPayload>();

        this.pathFactory = context.getValueFactories().getPathFactory();

        this.authorizer = authorizer != null ? authorizer : new NoOpAuthorizer();

        // Create the NodeId factory ...

        this.idFactory = new NodeIdFactory() {

            private long nextId = 0L;

            public NodeId create() {

                return new NodeId(++nextId);

            }

        };

        // Create the root node ...

        Location rootLocation = Location.create(pathFactory.createRootPath());

        NodeId rootId = idFactory.create();

        this.root = createNode(null, rootId, rootLocation);

        this.nodes.put(rootId, root);

        // Create the batch operations ...

        this.requests = new LinkedList<Request>();

        this.requestBuilder = new BatchRequestBuilder(this.requests);

        this.operations = this.store.batch(this.requestBuilder);

    }

    final String readable( Name name ) {

        return name.getString(context.getNamespaceRegistry());

    }

    final String readable( Path.Segment segment ) {

        return segment.getString(context.getNamespaceRegistry());

    }

    final String readable( Path path ) {

        return path.getString(context.getNamespaceRegistry());

    }

    final String readable( Location location ) {

        return location.getString(context.getNamespaceRegistry());

    }

    /**

     * Get the subgraph depth that is read when a node is loaded from the persistence store. By default, this value is 1.

     *

     * @return the loading depth; always positive

     */

    public int getDepthForLoadingNodes() {

        return loadDepth;

    }

    /**

     * Set the loading depth parameter, which controls how deep a subgraph should be read when a node is loaded from the

     * persistence store. By default, this value is 1.

     *

     * @param depth the depth that should be read whenever a single node is loaded

     * @throws IllegalArgumentException if the depth is not positive

     */

    public void setDepthForLoadingNodes( int depth ) {

        CheckArg.isPositive(depth, "depth");

        this.loadDepth = depth;

    }

    /**

     * Get the root node.

     *

     * @return the root node; never null

     */

    public Node<Payload, PropertyPayload> getRoot() {

        return root;

    }

    /**

     * Get the path factory that should be used to adjust the path objects.

     *

     * @return the path factory; never null

     */

    public PathFactory getPathFactory() {

        return pathFactory;

    }

    /**

     * Find in the session the node with the supplied location. If the location does not have a path, this method must first query

     * the actual persistent store, even if the session already has loaded the node. Thus, this method may not be the most

     * efficient technique to find a node.

     *

     * @param location the location of the node

     * @return the cached node at the supplied location

     * @throws PathNotFoundException if the node at the supplied location does not exist

     * @throws AccessControlException if the user does not have permission to read the node given by the supplied location

     * @throws IllegalArgumentException if the location is null

     */

    public Node<Payload, PropertyPayload> findNodeWith( Location location ) throws PathNotFoundException, AccessControlException {

        if (!location.hasPath()) {

            // Query for the actual location ...

            location = store.getNodeAt(location).getLocation();

        }

        assert location.hasPath();

        return findNodeWith(null, location.getPath());

    }

    /**

     * Find in the session the node with the supplied identifier.

     *

     * @param id the identifier of the node

     * @return the identified node, or null if the session has no node with the supplied identifier

     * @throws IllegalArgumentException if the identifier is null

     */

    public Node<Payload, PropertyPayload> findNodeWith( NodeId id ) {

        CheckArg.isNotNull(id, "id");

        return nodes.get(id);

    }

    /**

     * Find the node with the supplied identifier or, if no such node is found, the node at the supplied path. Note that if a node

     * was found by the identifier, the resulting may not have the same path as that supplied as a parameter.

     *

     * @param id the identifier to the node; may be null if the node is to be found by path

     * @param path the path that should be used to find the node only when the cache doesn't contain a node with the identifier

     * @return the node with the supplied id and/or path

     * @throws IllegalArgumentException if the identifier and path are both node

     * @throws PathNotFoundException if the node at the supplied path does not exist

     * @throws AccessControlException if the user does not have permission to read the nodes given by the supplied path

     */

    public Node<Payload, PropertyPayload> findNodeWith( NodeId id,

                                                        Path path ) throws PathNotFoundException, AccessControlException {

        if (id == null && path == null) {

            CheckArg.isNotNull(id, "id");

            CheckArg.isNotNull(path, "path");

        }

        Node<Payload, PropertyPayload> result = id != null ? nodes.get(id) : null; // if found, the user should have read

        // privilege since it was

        // already in the cache

        if (result == null || result.isStale()) {

            assert path != null;

            result = findNodeWith(path);

        }

        return result;

    }

    /**

     * Find the node with the supplied path. This node quickly finds the node if it exists in the cache, or if it is not in the

     * cache, it loads the nodes down the supplied path.

     *

     * @param path the path to the node

     * @return the node information

     * @throws PathNotFoundException if the node at the supplied path does not exist

     * @throws AccessControlException if the user does not have permission to read the nodes given by the supplied path

     */

    public Node<Payload, PropertyPayload> findNodeWith( Path path ) throws PathNotFoundException, AccessControlException {

        if (path.isRoot()) return getRoot();

        return findNodeRelativeTo(root, path.relativeTo(root.getPath()), true);

    }

    /**

     * Find the node with the supplied path. This node quickly finds the node if it exists in the cache, or if it is not in the

     * cache, it loads the nodes down the supplied path. However, if <code>loadIfRequired</code> is <code>false</code>, then any

     * node along the path that is not loaded will result in this method returning null.

     *

     * @param path the path to the node

     * @param loadIfRequired true if any missing nodes should be loaded, or false if null should be returned if any nodes along

     *        the path are not loaded

     * @return the node information

     * @throws PathNotFoundException if the node at the supplied path does not exist

     * @throws AccessControlException if the user does not have permission to read the nodes given by the supplied path

     */

    protected Node<Payload, PropertyPayload> findNodeWith( Path path,

                                                           boolean loadIfRequired )

        throws PathNotFoundException, AccessControlException {

        if (path.isRoot()) return getRoot();

        return findNodeRelativeTo(root, path.relativeTo(root.getPath()), loadIfRequired);

    }

    /**

     * Find the node with the supplied path relative to another node. This node quickly finds the node by walking the supplied

     * relative path starting at the supplied node. As soon as a cached node is found to not be fully loaded, the persistent

     * information for that node and all remaining nodes along the relative path are read from the persistent store and inserted

     * into the cache.

     *

     * @param startingPoint the node from which the path is relative

     * @param relativePath the relative path from the designated starting point to the desired node; may not be null and may not

     *        be an {@link Path#isAbsolute() absolute} path

     * @return the node information

     * @throws PathNotFoundException if the node at the supplied path does not exist

     * @throws AccessControlException if the user does not have permission to read the nodes given by the supplied path

     */

    public Node<Payload, PropertyPayload> findNodeRelativeTo( Node<Payload, PropertyPayload> startingPoint,

                                                              Path relativePath )

        throws PathNotFoundException, AccessControlException {

        return findNodeRelativeTo(startingPoint, relativePath, true);

    }

    /**

     * Find the node with the supplied path relative to another node. This node quickly finds the node by walking the supplied

     * relative path starting at the supplied node. As soon as a cached node is found to not be fully loaded, the persistent

     * information for that node and all remaining nodes along the relative path are read from the persistent store and inserted

     * into the cache.

     *

     * @param startingPoint the node from which the path is relative

     * @param relativePath the relative path from the designated starting point to the desired node; may not be null and may not

     *        be an {@link Path#isAbsolute() absolute} path

     * @param loadIfRequired true if any missing nodes should be loaded, or false if null should be returned if any nodes along

     *        the path are not loaded

     * @return the node information, or null if the node was not yet loaded (and <code>loadRequired</code> was false)

     * @throws PathNotFoundException if the node at the supplied path does not exist

     * @throws AccessControlException if the user does not have permission to read the nodes given by the supplied path

     */

    @SuppressWarnings( "synthetic-access" )

    protected Node<Payload, PropertyPayload> findNodeRelativeTo( Node<Payload, PropertyPayload> startingPoint,

                                                                 Path relativePath,

                                                                 boolean loadIfRequired )

        throws PathNotFoundException, AccessControlException {

        Node<Payload, PropertyPayload> node = startingPoint;

        if (!relativePath.isRoot()) {

            // Find the absolute path, which ensures that the relative path is well-formed ...

            Path absolutePath = relativePath.resolveAgainst(startingPoint.getPath());

            // Verify that the user has the appropriate privileges to read these nodes...

            authorizer.checkPermissions(absolutePath, Action.READ);

            // Walk down the path ...

            Iterator<Path.Segment> iter = relativePath.iterator();

            while (iter.hasNext()) {

                Path.Segment segment = iter.next();

                try {

                    if (segment.isSelfReference()) continue;

                    if (segment.isParentReference()) {

                        node = node.getParent();

                        assert node != null; // since the relative path is well-formed

                        continue;

                    }

                    if (node.isLoaded()) {

                        // The child is the next node we need to process ...

                        node = node.getChild(segment);

                    } else {

                        if (!loadIfRequired) return null;

                        // The node has not yet been loaded into the cache, so read this node

                        // from the store as well as all nodes along the path to the node we're really

                        // interested in. We'll do this in a batch, so first create this batch ...

                        Graph.Batch batch = store.batch();

                        // Figure out which nodes along the path need to be loaded from the store ...

                        Path firstPath = node.getPath();

                        batch.read(firstPath);

                        // Now add the path to the child (which is no longer on the iterator) ...

                        Path nextPath = pathFactory.create(firstPath, segment);

                        if (!iter.hasNext() && loadDepth > 1) {

                            batch.readSubgraphOfDepth(loadDepth).at(nextPath);