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.property;
25
26 import net.jcip.annotations.ThreadSafe;
27 import org.modeshape.common.text.TextDecoder;
28
29 /**
30 * A factory for creating {@link Path paths}. This interface extends the {@link ValueFactory} generic interface and adds specific
31 * methods for creating paths (and relative paths) from a series of names, segments, or combinations.
32 */
33 @ThreadSafe
34 public interface PathFactory extends ValueFactory<Path> {
35
36 /**
37 * Create an absolute root path. Subsequent calls will always return the same instance.
38 *
39 * @return the new path
40 */
41 Path createRootPath();
42
43 /**
44 * Create an absolute path with the supplied segment names, in order. If no segments are provided, the result will be the root
45 * path.
46 *
47 * @param segmentNames the names of the segments
48 * @return the new path
49 * @throws IllegalArgumentException if at least one segment name is provided and if any of the supplied segment names are null
50 */
51 Path createAbsolutePath( Name... segmentNames );
52
53 /**
54 * Create an absolute path with the supplied segments, in order. If no segments are provided, the result will be the root
55 * path.
56 *
57 * @param segments the segments
58 * @return the new path
59 * @throws IllegalArgumentException if at least one segment is provided and if any of the supplied segments are null
60 */
61 Path createAbsolutePath( Path.Segment... segments );
62
63 /**
64 * Create an absolute path with the supplied segments, in order. If no segments are provided, the result will be the root
65 * path.
66 *
67 * @param segments the segments
68 * @return the new path
69 * @throws IllegalArgumentException if at least one segment is provided and if any of the supplied segments are null
70 */
71 Path createAbsolutePath( Iterable<Path.Segment> segments );
72
73 /**
74 * Create an empty relative path (i.e., equivalent to {@link #createRelativePath(Path.Segment...) createRelativePath}(
75 * {@link Path#SELF_SEGMENT})). Subsequent calls will always return the same instance.
76 *
77 * @return the new path
78 */
79 Path createRelativePath();
80
81 /**
82 * Create a relative path with the supplied segment names, in order. If no segments are provided, the result will be the root
83 * path.
84 *
85 * @param segmentNames the names of the segments
86 * @return the new path
87 * @throws IllegalArgumentException if at least one segment name is provided and if any of the supplied segment names are null
88 */
89 Path createRelativePath( Name... segmentNames );
90
91 /**
92 * Create a relative path with the supplied segments, in order. If no segments are provided, the result will be the root path.
93 *
94 * @param segments the segments
95 * @return the new path
96 * @throws IllegalArgumentException if at least one segment is provided and if any of the supplied segments are null
97 */
98 Path createRelativePath( Path.Segment... segments );
99
100 /**
101 * Create a relative path with the supplied segments, in order. If no segments are provided, the result will be the root path.
102 *
103 * @param segments the segments
104 * @return the new path
105 * @throws IllegalArgumentException if at least one segment is provided and if any of the supplied segments are null
106 */
107 Path createRelativePath( Iterable<Path.Segment> segments );
108
109 /**
110 * Create a path by appending the supplied relative path to the supplied parent path. The resulting path will be
111 * {@link Path#isAbsolute() absolute} if the supplied parent path is absolute.
112 *
113 * @param parentPath the path that is to provide the basis for the new path
114 * @param childPath the path that should be appended to the parent path
115 * @return the new path
116 * @throws IllegalArgumentException if the parent path reference or the child path reference is null
117 */
118 Path create( Path parentPath,
119 Path childPath );
120
121 /**
122 * Create a path by appending the supplied names to the parent path.
123 *
124 * @param parentPath the path that is to provide the basis for the new path
125 * @param segmentName the name of the segment to be appended to the parent path
126 * @param index the index for the new segment
127 * @return the new path
128 * @throws IllegalArgumentException if the parent path reference or the segment name is null, or if the index is invalid
129 */
130 Path create( Path parentPath,
131 Name segmentName,
132 int index );
133
134 /**
135 * Create a path by appending the supplied names to the parent path.
136 *
137 * @param parentPath the path that is to provide the basis for the new path
138 * @param segmentName the name of the segment to be appended to the parent path
139 * @param index the index for the new segment
140 * @return the new path
141 * @throws IllegalArgumentException if the parent path reference or the segment name is null, or if the index is invalid
142 */
143 Path create( Path parentPath,
144 String segmentName,
145 int index );
146
147 /**
148 * Create a path by appending the supplied names to the parent path. If no names are appended, the parent path is returned.
149 *
150 * @param parentPath the path that is to provide the basis for the new path
151 * @param segmentNames the names of the segments that are to be appended, in order, to the parent path
152 * @return the new path
153 * @throws IllegalArgumentException if the parent path reference is null, or if at least one segment name is provided and if
154 * any of the supplied segment names are null
155 */
156 Path create( Path parentPath,
157 Name... segmentNames );
158
159 /**
160 * Create a path by appending the supplied names to the parent path. If no names are appended, the parent path is returned.
161 *
162 * @param parentPath the path that is to provide the basis for the new path
163 * @param segments the segments that are to be appended, in order, to the parent path
164 * @return the new path
165 * @throws IllegalArgumentException if the parent path reference is null, or if at least one segment name is provided and if
166 * any of the supplied segment names are null
167 */
168 Path create( Path parentPath,
169 Path.Segment... segments );
170
171 /**
172 * Create a path by appending the supplied names to the parent path. If no names are appended, the parent path is returned.
173 *
174 * @param parentPath the path that is to provide the basis for the new path
175 * @param segments the segments that are to be appended, in order, to the parent path
176 * @return the new path
177 * @throws IllegalArgumentException if the parent path reference is null, or if at least one segment name is provided and if
178 * any of the supplied segment names are null
179 */
180 Path create( Path parentPath,
181 Iterable<Path.Segment> segments );
182
183 /**
184 * Create a path by appending the supplied names to the parent path.
185 *
186 * @param parentPath the path that is to provide the basis for the new path
187 * @param subpath the subpath to be appended to the parent path, which must be in the form of a relative path
188 * @return the new path
189 * @throws IllegalArgumentException if the parent path reference or the segment name is null, or if the index is invalid
190 */
191 Path create( Path parentPath,
192 String subpath );
193
194 /**
195 * Create a path segment given the supplied segment name. The supplied string may contain a same-name-sibling index in the
196 * form of "<code>[<i>n</i>]</code>" at the end of the name, where <i>n</i> is a positive integer. Note that the
197 * same-name-sibling index is 1-based, not zero-based.
198 *
199 * @param segmentName the name of the segment
200 * @return the segment
201 * @throws IllegalArgumentException if the segment name reference is <code>null</code> or the value could not be created from
202 * the supplied string
203 * @throws ValueFormatException if the same-name-sibling index is not an integer, or if the supplied string is not a valid
204 * segment name
205 */
206 Path.Segment createSegment( String segmentName );
207
208 /**
209 * Create a path segment given the supplied segment name. The supplied string may contain a same-name-sibling index in the
210 * form of "<code>[<i>n</i>]</code>" at the end of the name, where <i>n</i> is a positive integer. Note that the
211 * same-name-sibling index is 1-based, not zero-based.
212 *
213 * @param segmentName the name of the segment
214 * @param decoder the decoder that should be used to decode the qualified name
215 * @return the segment
216 * @throws IllegalArgumentException if the segment name reference is <code>null</code> or the value could not be created from
217 * the supplied string
218 * @throws ValueFormatException if the same-name-sibling index is not an integer, or if the supplied string is not a valid
219 * segment name
220 */
221 Path.Segment createSegment( String segmentName,
222 TextDecoder decoder );
223
224 /**
225 * Create a path segment given the supplied segment name and index.
226 *
227 * @param segmentName the name of the new segment
228 * @param index the index of the new segment
229 * @return the segment
230 * @throws IllegalArgumentException if the segment name reference is <code>null</code> or if the index is invalid
231 * @throws ValueFormatException if the supplied string is not a valid segment name
232 */
233 Path.Segment createSegment( String segmentName,
234 int index );
235
236 /**
237 * Create a path segment given the supplied segment name. The resulting segment will have no index.
238 *
239 * @param segmentName the name of the segment
240 * @return the segment
241 * @throws IllegalArgumentException if the segment name reference is null
242 */
243 Path.Segment createSegment( Name segmentName );
244
245 /**
246 * Create a path segment given the supplied segment name and index.
247 *
248 * @param segmentName the name of the new segment
249 * @param index the index of the new segment
250 * @return the segment
251 * @throws IllegalArgumentException if the segment name reference is null or if the index is invalid
252 */
253 Path.Segment createSegment( Name segmentName,
254 int index );
255
256 }