001 /*
002 * JBoss, Home of Professional Open Source.
003 * Copyright 2008, Red Hat Middleware LLC, and individual contributors
004 * as indicated by the @author tags. See the copyright.txt file in the
005 * distribution for a full listing of individual contributors.
006 *
007 * This is free software; you can redistribute it and/or modify it
008 * under the terms of the GNU Lesser General Public License as
009 * published by the Free Software Foundation; either version 2.1 of
010 * the License, or (at your option) any later version.
011 *
012 * This software is distributed in the hope that it will be useful,
013 * but WITHOUT ANY WARRANTY; without even the implied warranty of
014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015 * Lesser General Public License for more details.
016 *
017 * You should have received a copy of the GNU Lesser General Public
018 * License along with this software; if not, write to the Free
019 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
021 */
022 package org.jboss.dna.graph.commands;
023
024 import java.util.Iterator;
025 import org.jboss.dna.graph.properties.Path;
026 import org.jboss.dna.graph.properties.Property;
027
028 /**
029 * Command that records the structure of a branch. To process this command, the recipient should walk the branch rooted at
030 * {@link ActsOnPath#getPath()} and, for each node in the branch, {@link #record(Path, Iterable)} the node's information. If
031 * {@link #record(Path, Iterable)} returns true, then the children of that node should also be recorded; if false, then the
032 * recording the children of that node can be ignored.
033 *
034 * @author Randall Hauch
035 */
036 public interface RecordBranchCommand extends GraphCommand, ActsOnPath {
037
038 /**
039 * Sets the properties of the supplied node.
040 * <p>
041 * If the supplied path is a relative path, it is assumed to be relative to the {@link ActsOnPath#getPath() branch root}. If
042 * the supplied path is an absolute path, it must be a {@link Path#isDecendantOf(Path) decendant} of the
043 * {@link ActsOnPath#getPath() branch root}; if not, this method returns false and ignores the call.
044 * </p>
045 * <p>
046 * This method should not be called multiple times with the same path. The behavior for such cases is not defined.
047 * </p>
048 *
049 * @param path the path for the node; may not be null
050 * @param properties the properties for the node; may be null if there are no properties
051 * @return true if the children of the node should be recorded, or false if this new node is as deep as the recording should
052 * go
053 */
054 boolean record( Path path,
055 Iterable<Property> properties );
056
057 /**
058 * Sets the properties of the supplied node.
059 * <p>
060 * If the supplied path is a relative path, it is assumed to be relative to the {@link ActsOnPath#getPath() branch root}. If
061 * the supplied path is an absolute path, it must be a {@link Path#isDecendantOf(Path) decendant} of the
062 * {@link ActsOnPath#getPath() branch root}; if not, this method returns false and ignores the call.
063 * </p>
064 * <p>
065 * This method should not be called multiple times with the same path. The behavior for such cases is not defined.
066 * </p>
067 *
068 * @param path the path for the node; may not be null
069 * @param properties the properties for the node; may be null if there are no properties
070 * @return true if the children of the node should be recorded, or false if this new node is as deep as the recording should
071 * go
072 */
073 boolean record( Path path,
074 Iterator<Property> properties );
075
076 /**
077 * Sets the properties of the supplied node.
078 * <p>
079 * If the supplied path is a relative path, it is assumed to be relative to the {@link ActsOnPath#getPath() branch root}. If
080 * the supplied path is an absolute path, it must be a {@link Path#isDecendantOf(Path) decendant} of the
081 * {@link ActsOnPath#getPath() branch root}; if not, this method returns false and ignores the call.
082 * </p>
083 * <p>
084 * This method should not be called multiple times with the same path. The behavior for such cases is not defined.
085 * </p>
086 *
087 * @param path the path for the node; may not be null
088 * @param properties the properties for the node; may be null if there are no properties
089 * @return true if the children of the node should be recorded, or false if this new node is as deep as the recording should
090 * go
091 */
092 boolean record( Path path,
093 Property... properties );
094
095 }