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.properties;
023
024 import org.jboss.dna.common.text.TextDecoder;
025
026 /**
027 * A factory for creating {@link Path paths}. This interface extends the {@link ValueFactory} generic interface and adds specific
028 * methods for creating paths (and relative paths) from a series of names, segments, or combinations.
029 *
030 * @author Randall Hauch
031 * @author John Verhaeg
032 */
033 public interface PathFactory extends ValueFactory<Path> {
034
035 /**
036 * Create an absolute root path. Subsequent calls will always return the same instance.
037 *
038 * @return the new path
039 */
040 Path createRootPath();
041
042 /**
043 * Create an absolute path with the supplied segment names, in order. If no segments are provided, the result will be the root
044 * path.
045 *
046 * @param segmentNames the names of the segments
047 * @return the new path
048 * @throws IllegalArgumentException if at least one segment name is provided and if any of the supplied segment names are null
049 */
050 Path createAbsolutePath( Name... segmentNames );
051
052 /**
053 * Create an absolute path with the supplied segments, in order. If no segments are provided, the result will be the root
054 * path.
055 *
056 * @param segments the segments
057 * @return the new path
058 * @throws IllegalArgumentException if at least one segment is provided and if any of the supplied segments are null
059 */
060 Path createAbsolutePath( Path.Segment... segments );
061
062 /**
063 * Create an absolute path with the supplied segments, in order. If no segments are provided, the result will be the root
064 * path.
065 *
066 * @param segments the segments
067 * @return the new path
068 * @throws IllegalArgumentException if at least one segment is provided and if any of the supplied segments are null
069 */
070 Path createAbsolutePath( Iterable<Path.Segment> segments );
071
072 /**
073 * Create an empty relative path (i.e., equivalent to {@link #createRelativePath(Path.Segment...) createRelativePath}(
074 * {@link Path#SELF_SEGMENT})). Subsequent calls will always return the same instance.
075 *
076 * @return the new path
077 */
078 Path createRelativePath();
079
080 /**
081 * Create a relative path with the supplied segment names, in order. If no segments are provided, the result will be the root
082 * path.
083 *
084 * @param segmentNames the names of the segments
085 * @return the new path
086 * @throws IllegalArgumentException if at least one segment name is provided and if any of the supplied segment names are null
087 */
088 Path createRelativePath( Name... segmentNames );
089
090 /**
091 * Create a relative path with the supplied segments, in order. If no segments are provided, the result will be the root path.
092 *
093 * @param segments the segments
094 * @return the new path
095 * @throws IllegalArgumentException if at least one segment is provided and if any of the supplied segments are null
096 */
097 Path createRelativePath( Path.Segment... segments );
098
099 /**
100 * Create a relative path with the supplied segments, in order. If no segments are provided, the result will be the root path.
101 *
102 * @param segments the segments
103 * @return the new path
104 * @throws IllegalArgumentException if at least one segment is provided and if any of the supplied segments are null
105 */
106 Path createRelativePath( Iterable<Path.Segment> segments );
107
108 /**
109 * Create a path by appending the supplied relative path to the supplied parent path. The resulting path will be
110 * {@link Path#isAbsolute() absolute} if the supplied parent path is absolute.
111 *
112 * @param parentPath the path that is to provide the basis for the new path
113 * @param childPath the path that should be appended to the parent path
114 * @return the new path
115 * @throws IllegalArgumentException if the parent path reference or the child path reference is null
116 */
117 Path create( Path parentPath,
118 Path childPath );
119
120 /**
121 * Create a path by appending the supplied names to the parent path.
122 *
123 * @param parentPath the path that is to provide the basis for the new path
124 * @param segmentName the name of the segment to be appended to the parent path
125 * @param index the index for the new segment
126 * @return the new path
127 * @throws IllegalArgumentException if the parent path reference or the segment name is null, or if the index is invalid
128 */
129 Path create( Path parentPath,
130 Name segmentName,
131 int index );
132
133 /**
134 * Create a path by appending the supplied names to the parent path. If no names are appended, the parent path is returned.
135 *
136 * @param parentPath the path that is to provide the basis for the new path
137 * @param segmentNames the names of the segments that are to be appended, in order, to the parent path
138 * @return the new path
139 * @throws IllegalArgumentException if the parent path reference is null, or if at least one segment name is provided and if
140 * any of the supplied segment names are null
141 */
142 Path create( Path parentPath,
143 Name... segmentNames );
144
145 /**
146 * Create a path by appending the supplied names to the parent path. If no names are appended, the parent path is returned.
147 *
148 * @param parentPath the path that is to provide the basis for the new path
149 * @param segments the segments that are to be appended, in order, to the parent path
150 * @return the new path
151 * @throws IllegalArgumentException if the parent path reference is null, or if at least one segment name is provided and if
152 * any of the supplied segment names are null
153 */
154 Path create( Path parentPath,
155 Path.Segment... segments );
156
157 /**
158 * Create a path by appending the supplied names to the parent path. If no names are appended, the parent path is returned.
159 *
160 * @param parentPath the path that is to provide the basis for the new path
161 * @param segments the segments that are to be appended, in order, to the parent path
162 * @return the new path
163 * @throws IllegalArgumentException if the parent path reference is null, or if at least one segment name is provided and if
164 * any of the supplied segment names are null
165 */
166 Path create( Path parentPath,
167 Iterable<Path.Segment> segments );
168
169 /**
170 * Create a path by appending the supplied names to the parent path.
171 *
172 * @param parentPath the path that is to provide the basis for the new path
173 * @param subpath the subpath to be appended to the parent path, which must be in the form of a relative path
174 * @return the new path
175 * @throws IllegalArgumentException if the parent path reference or the segment name is null, or if the index is invalid
176 */
177 Path create( Path parentPath,
178 String subpath );
179
180 /**
181 * Create a path segment given the supplied segment name. The resulting segment will have no index.
182 *
183 * @param segmentName the name of the segment
184 * @return the segment
185 * @throws IllegalArgumentException if the segment name reference is <code>null</code> or the value could not be created from
186 * the supplied string
187 */
188 Path.Segment createSegment( String segmentName );
189
190 /**
191 * Create a path segment given the supplied segment name. The resulting segment will have no index.
192 *
193 * @param segmentName the name of the segment
194 * @param decoder the decoder that should be used to decode the qualified name
195 * @return the segment
196 * @throws IllegalArgumentException if the segment name reference is <code>null</code> or the value could not be created from
197 * the supplied string
198 */
199 Path.Segment createSegment( String segmentName,
200 TextDecoder decoder );
201
202 /**
203 * Create a path segment given the supplied segment name and index.
204 *
205 * @param segmentName the name of the new segment
206 * @param index the index of the new segment
207 * @return the segment
208 * @throws IllegalArgumentException if the segment name reference is <code>null</code> or if the index is invalid
209 */
210 Path.Segment createSegment( String segmentName,
211 int index );
212
213 /**
214 * Create a path segment given the supplied segment name. The resulting segment will have no index.
215 *
216 * @param segmentName the name of the segment
217 * @return the segment
218 * @throws IllegalArgumentException if the segment name reference is null
219 */
220 Path.Segment createSegment( Name segmentName );
221
222 /**
223 * Create a path segment given the supplied segment name and index.
224 *
225 * @param segmentName the name of the new segment
226 * @param index the index of the new segment
227 * @return the segment
228 * @throws IllegalArgumentException if the segment name reference is null or if the index is invalid
229 */
230 Path.Segment createSegment( Name segmentName,
231 int index );
232
233 }