001 /* 002 * JBoss DNA (http://www.jboss.org/dna) 003 * See the COPYRIGHT.txt file distributed with this work for information 004 * regarding copyright ownership. Some portions may be licensed 005 * to Red Hat, Inc. under one or more contributor license agreements. 006 * See the AUTHORS.txt file in the distribution for a full listing of 007 * individual contributors. 008 * 009 * JBoss DNA is free software. Unless otherwise indicated, all code in JBoss DNA 010 * is licensed to you under the terms of the GNU Lesser General Public License as 011 * published by the Free Software Foundation; either version 2.1 of 012 * the License, or (at your option) any later version. 013 * 014 * JBoss DNA is distributed in the hope that it will be useful, 015 * but WITHOUT ANY WARRANTY; without even the implied warranty of 016 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 017 * Lesser General Public License for more details. 018 * 019 * You should have received a copy of the GNU Lesser General Public 020 * License along with this software; if not, write to the Free 021 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 022 * 02110-1301 USA, or see the FSF site: http://www.fsf.org. 023 */ 024 package org.jboss.dna.graph.property; 025 026 import org.jboss.dna.common.text.TextDecoder; 027 028 /** 029 * A factory for creating {@link Path paths}. This interface extends the {@link ValueFactory} generic interface and adds specific 030 * methods for creating paths (and relative paths) from a series of names, segments, or combinations. 031 * 032 * @author Randall Hauch 033 * @author John Verhaeg 034 */ 035 public interface PathFactory extends ValueFactory<Path> { 036 037 /** 038 * Create an absolute root path. Subsequent calls will always return the same instance. 039 * 040 * @return the new path 041 */ 042 Path createRootPath(); 043 044 /** 045 * Create an absolute path with the supplied segment names, in order. If no segments are provided, the result will be the root 046 * path. 047 * 048 * @param segmentNames the names of the segments 049 * @return the new path 050 * @throws IllegalArgumentException if at least one segment name is provided and if any of the supplied segment names are null 051 */ 052 Path createAbsolutePath( Name... segmentNames ); 053 054 /** 055 * Create an absolute path with the supplied segments, in order. If no segments are provided, the result will be the root 056 * path. 057 * 058 * @param segments the segments 059 * @return the new path 060 * @throws IllegalArgumentException if at least one segment is provided and if any of the supplied segments are null 061 */ 062 Path createAbsolutePath( Path.Segment... segments ); 063 064 /** 065 * Create an absolute path with the supplied segments, in order. If no segments are provided, the result will be the root 066 * path. 067 * 068 * @param segments the segments 069 * @return the new path 070 * @throws IllegalArgumentException if at least one segment is provided and if any of the supplied segments are null 071 */ 072 Path createAbsolutePath( Iterable<Path.Segment> segments ); 073 074 /** 075 * Create an empty relative path (i.e., equivalent to {@link #createRelativePath(Path.Segment...) createRelativePath}( 076 * {@link Path#SELF_SEGMENT})). Subsequent calls will always return the same instance. 077 * 078 * @return the new path 079 */ 080 Path createRelativePath(); 081 082 /** 083 * Create a relative path with the supplied segment names, in order. If no segments are provided, the result will be the root 084 * path. 085 * 086 * @param segmentNames the names of the segments 087 * @return the new path 088 * @throws IllegalArgumentException if at least one segment name is provided and if any of the supplied segment names are null 089 */ 090 Path createRelativePath( Name... segmentNames ); 091 092 /** 093 * Create a relative path with the supplied segments, in order. If no segments are provided, the result will be the root path. 094 * 095 * @param segments the segments 096 * @return the new path 097 * @throws IllegalArgumentException if at least one segment is provided and if any of the supplied segments are null 098 */ 099 Path createRelativePath( Path.Segment... segments ); 100 101 /** 102 * Create a relative path with the supplied segments, in order. If no segments are provided, the result will be the root path. 103 * 104 * @param segments the segments 105 * @return the new path 106 * @throws IllegalArgumentException if at least one segment is provided and if any of the supplied segments are null 107 */ 108 Path createRelativePath( Iterable<Path.Segment> segments ); 109 110 /** 111 * Create a path by appending the supplied relative path to the supplied parent path. The resulting path will be 112 * {@link Path#isAbsolute() absolute} if the supplied parent path is absolute. 113 * 114 * @param parentPath the path that is to provide the basis for the new path 115 * @param childPath the path that should be appended to the parent path 116 * @return the new path 117 * @throws IllegalArgumentException if the parent path reference or the child path reference is null 118 */ 119 Path create( Path parentPath, 120 Path childPath ); 121 122 /** 123 * Create a path by appending the supplied names to the parent path. 124 * 125 * @param parentPath the path that is to provide the basis for the new path 126 * @param segmentName the name of the segment to be appended to the parent path 127 * @param index the index for the new segment 128 * @return the new path 129 * @throws IllegalArgumentException if the parent path reference or the segment name is null, or if the index is invalid 130 */ 131 Path create( Path parentPath, 132 Name segmentName, 133 int index ); 134 135 /** 136 * Create a path by appending the supplied names to the parent path. 137 * 138 * @param parentPath the path that is to provide the basis for the new path 139 * @param segmentName the name of the segment to be appended to the parent path 140 * @param index the index for the new segment 141 * @return the new path 142 * @throws IllegalArgumentException if the parent path reference or the segment name is null, or if the index is invalid 143 */ 144 Path create( Path parentPath, 145 String segmentName, 146 int index ); 147 148 /** 149 * Create a path by appending the supplied names to the parent path. If no names are appended, the parent path is returned. 150 * 151 * @param parentPath the path that is to provide the basis for the new path 152 * @param segmentNames the names of the segments that are to be appended, in order, to the parent path 153 * @return the new path 154 * @throws IllegalArgumentException if the parent path reference is null, or if at least one segment name is provided and if 155 * any of the supplied segment names are null 156 */ 157 Path create( Path parentPath, 158 Name... segmentNames ); 159 160 /** 161 * Create a path by appending the supplied names to the parent path. If no names are appended, the parent path is returned. 162 * 163 * @param parentPath the path that is to provide the basis for the new path 164 * @param segments the segments that are to be appended, in order, to the parent path 165 * @return the new path 166 * @throws IllegalArgumentException if the parent path reference is null, or if at least one segment name is provided and if 167 * any of the supplied segment names are null 168 */ 169 Path create( Path parentPath, 170 Path.Segment... segments ); 171 172 /** 173 * Create a path by appending the supplied names to the parent path. If no names are appended, the parent path is returned. 174 * 175 * @param parentPath the path that is to provide the basis for the new path 176 * @param segments the segments that are to be appended, in order, to the parent path 177 * @return the new path 178 * @throws IllegalArgumentException if the parent path reference is null, or if at least one segment name is provided and if 179 * any of the supplied segment names are null 180 */ 181 Path create( Path parentPath, 182 Iterable<Path.Segment> segments ); 183 184 /** 185 * Create a path by appending the supplied names to the parent path. 186 * 187 * @param parentPath the path that is to provide the basis for the new path 188 * @param subpath the subpath to be appended to the parent path, which must be in the form of a relative path 189 * @return the new path 190 * @throws IllegalArgumentException if the parent path reference or the segment name is null, or if the index is invalid 191 */ 192 Path create( Path parentPath, 193 String subpath ); 194 195 /** 196 * Create a path segment given the supplied segment name. The supplied string may contain a same-name-sibling index in the 197 * form of "<code>[<i>n</i>]</code>" at the end of the name, where <i>n</i> is a positive integer. Note that the 198 * same-name-sibling index is 1-based, not zero-based. 199 * 200 * @param segmentName the name of the segment 201 * @return the segment 202 * @throws IllegalArgumentException if the segment name reference is <code>null</code> or the value could not be created from 203 * the supplied string 204 * @throws ValueFormatException if the same-name-sibling index is not an integer, or if the supplied string is not a valid 205 * segment name 206 */ 207 Path.Segment createSegment( String segmentName ); 208 209 /** 210 * Create a path segment given the supplied segment name. The supplied string may contain a same-name-sibling index in the 211 * form of "<code>[<i>n</i>]</code>" at the end of the name, where <i>n</i> is a positive integer. Note that the 212 * same-name-sibling index is 1-based, not zero-based. 213 * 214 * @param segmentName the name of the segment 215 * @param decoder the decoder that should be used to decode the qualified name 216 * @return the segment 217 * @throws IllegalArgumentException if the segment name reference is <code>null</code> or the value could not be created from 218 * the supplied string 219 * @throws ValueFormatException if the same-name-sibling index is not an integer, or if the supplied string is not a valid 220 * segment name 221 */ 222 Path.Segment createSegment( String segmentName, 223 TextDecoder decoder ); 224 225 /** 226 * Create a path segment given the supplied segment name and index. 227 * 228 * @param segmentName the name of the new segment 229 * @param index the index of the new segment 230 * @return the segment 231 * @throws IllegalArgumentException if the segment name reference is <code>null</code> or if the index is invalid 232 * @throws ValueFormatException if the supplied string is not a valid segment name 233 */ 234 Path.Segment createSegment( String segmentName, 235 int index ); 236 237 /** 238 * Create a path segment given the supplied segment name. The resulting segment will have no index. 239 * 240 * @param segmentName the name of the segment 241 * @return the segment 242 * @throws IllegalArgumentException if the segment name reference is null 243 */ 244 Path.Segment createSegment( Name segmentName ); 245 246 /** 247 * Create a path segment given the supplied segment name and index. 248 * 249 * @param segmentName the name of the new segment 250 * @param index the index of the new segment 251 * @return the segment 252 * @throws IllegalArgumentException if the segment name reference is null or if the index is invalid 253 */ 254 Path.Segment createSegment( Name segmentName, 255 int index ); 256 257 }