1 /* 2 * ModeShape (http://www.modeshape.org) 3 * See the COPYRIGHT.txt file distributed with this work for information 4 * regarding copyright ownership. Some portions may be licensed 5 * to Red Hat, Inc. under one or more contributor license agreements. 6 * See the AUTHORS.txt file in the distribution for a full listing of 7 * individual contributors. 8 * 9 * ModeShape is free software. Unless otherwise indicated, all code in ModeShape 10 * is licensed to you under the terms of the GNU Lesser General Public License as 11 * published by the Free Software Foundation; either version 2.1 of 12 * the License, or (at your option) any later version. 13 * 14 * ModeShape is distributed in the hope that it will be useful, 15 * but WITHOUT ANY WARRANTY; without even the implied warranty of 16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 17 * Lesser General Public License for more details. 18 * 19 * You should have received a copy of the GNU Lesser General Public 20 * License along with this software; if not, write to the Free 21 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 22 * 02110-1301 USA, or see the FSF site: http://www.fsf.org. 23 */ 24 package org.modeshape.graph; 25 26 import net.jcip.annotations.Immutable; 27 import org.modeshape.graph.property.Name; 28 import org.modeshape.graph.property.Path; 29 30 /** 31 * A subgraph returned by the {@link Graph}, containing the nodes in the subgraph as well as the properties and children for each 32 * of those nodes. The {@link #iterator()} method may be used to walk the nodes in the subgraph in a pre-order traversal. 33 * <p> 34 * Since this subgraph has a single {@link #getLocation() node that is the top of the subgraph}, the methods that take a String 35 * path or {@link Path path object} will accept absolute or relative paths. 36 * </p> 37 * <p> 38 * This subgraph will not contain any {@link #iterator() nodes} that exist below the {@link #getMaximumDepth() maximum depth}. 39 * Also, all nodes included in the subgraph have all their properties and children. However, nodes that are at the maximum depth 40 * of the subgraph will contain the locations for child nodes that are below the maximum depth and therefore not included in this 41 * subgraph. 42 * </p> 43 */ 44 @Immutable 45 public interface Subgraph extends Graph.BaseResults<SubgraphNode> { 46 47 /** 48 * Get the location of the subgraph, which is the location of the node at the top of the subgraph. 49 * 50 * @return the location of the top node in the subgraph; never null 51 */ 52 Location getLocation(); 53 54 /** 55 * Get the maximum depth requested for this subgraph. The actual subgraph may not be as deep, but will never be deeper than 56 * this value. 57 * 58 * @return the maximum depth requested; always positive 59 */ 60 int getMaximumDepth(); 61 62 /** 63 * Get the node at the supplied location. 64 * 65 * @param relativePath the name that makes up a relative path to the node that is an immediate child of the {@link #getRoot() 66 * root} 67 * @return the node, or null if the node is not {@link #includes(Path) included} in these results 68 */ 69 SubgraphNode getNode( Name relativePath ); 70 71 /** 72 * Get the node that is at the {@link #getLocation() root} of the subgraph. 73 * 74 * @return the root node in the subgraph 75 */ 76 SubgraphNode getRoot(); 77 78 }