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 java.io.IOException;
27 import java.io.InputStream;
28 import java.io.Reader;
29 import java.math.BigDecimal;
30 import java.net.URI;
31 import java.util.Calendar;
32 import java.util.Date;
33 import java.util.Iterator;
34 import java.util.UUID;
35 import net.jcip.annotations.ThreadSafe;
36 import org.modeshape.common.text.TextDecoder;
37 import org.modeshape.common.text.TextEncoder;
38
39 /**
40 * A factory for {@link Property} values. Each create method may throw one of these exceptions when attempting to convert a
41 * supplied value to the {@link #getPropertyType() factory's type}:
42 * <ul>
43 * <li>{@link IllegalArgumentException} - If the supplied value is invalid in respect to the conversion being attempted.</li>
44 * <li>{@link UnsupportedOperationException} - If a conversion from the supplied value is not supported.</li>
45 * <li>{@link IoException} - If an unexpected problem occurs during the conversion (such as an {@link IOException}).</li>
46 * </ul>
47 *
48 * @param <T> the type of value to create
49 */
50 @ThreadSafe
51 public interface ValueFactory<T> {
52
53 static final TextDecoder DEFAULT_DECODER = Path.NO_OP_DECODER;
54 static final TextEncoder DEFAULT_ENCODER = Path.NO_OP_ENCODER;
55
56 /**
57 * Get the {@link PropertyType type} of values created by this factory.
58 *
59 * @return the value type; never null
60 */
61 PropertyType getPropertyType();
62
63 /**
64 * Create a value from a string, using no decoding.
65 *
66 * @param value the string from which the value is to be created
67 * @return the value, or null if the supplied string is null
68 * @throws ValueFormatException if the conversion from a string could not be performed
69 * @see #create(String, TextDecoder)
70 */
71 T create( String value ) throws ValueFormatException;
72
73 /**
74 * Create a value from a string, using the supplied decoder.
75 *
76 * @param value the string from which the value is to be created
77 * @param decoder the decoder that should be used; if null, the {@link #DEFAULT_DECODER default decoder} is used
78 * @return the value, or null if the supplied string is null
79 * @throws ValueFormatException if the conversion from a string could not be performed
80 * @see #create(String)
81 */
82 T create( String value,
83 TextDecoder decoder ) throws ValueFormatException;
84
85 /**
86 * Create a value from an integer.
87 *
88 * @param value the integer from which the value is to be created
89 * @return the value; never null
90 * @throws ValueFormatException if the conversion from an integer could not be performed
91 */
92 T create( int value ) throws ValueFormatException;
93
94 /**
95 * Create a long from a string.
96 *
97 * @param value the string from which the long is to be created
98 * @return the value; never null
99 * @throws ValueFormatException if the conversion from a long could not be performed
100 */
101 T create( long value ) throws ValueFormatException;
102
103 /**
104 * Create a boolean from a string.
105 *
106 * @param value the boolean from which the value is to be created
107 * @return the value; never null
108 * @throws ValueFormatException if the conversion from a boolean could not be performed
109 */
110 T create( boolean value ) throws ValueFormatException;
111
112 /**
113 * Create a value from a float.
114 *
115 * @param value the float from which the value is to be created
116 * @return the value; never null
117 * @throws ValueFormatException if the conversion from a float could not be performed
118 */
119 T create( float value ) throws ValueFormatException;
120
121 /**
122 * Create a value from a double.
123 *
124 * @param value the double from which the value is to be created
125 * @return the value; never null
126 * @throws ValueFormatException if the conversion from a double could not be performed
127 */
128 T create( double value ) throws ValueFormatException;
129
130 /**
131 * Create a value from a decimal.
132 *
133 * @param value the decimal from which the value is to be created
134 * @return the value, or null if the supplied decimal is null
135 * @throws ValueFormatException if the conversion from a decimal could not be performed
136 */
137 T create( BigDecimal value ) throws ValueFormatException;
138
139 /**
140 * Create a value from a Calendar instance.
141 *
142 * @param value the Calendar instance from which the value is to be created
143 * @return the value, or null if the supplied Calendar is null
144 * @throws ValueFormatException if the conversion from a Calendar could not be performed
145 */
146 T create( Calendar value ) throws ValueFormatException;
147
148 /**
149 * Create a value from a date.
150 *
151 * @param value the date from which the value is to be created
152 * @return the value, or null if the supplied date is null
153 * @throws ValueFormatException if the conversion from a Date could not be performed
154 */
155 T create( Date value ) throws ValueFormatException;
156
157 /**
158 * Create a value from a date-time instant.
159 *
160 * @param value the date-time instant from which the value is to be created
161 * @return the value, or null if the supplied date is null
162 * @throws ValueFormatException if the conversion from a Date could not be performed
163 */
164 T create( DateTime value ) throws ValueFormatException;
165
166 /**
167 * Create a value from a name.
168 *
169 * @param value the name from which the value is to be created
170 * @return the value, or null if the supplied name is null
171 * @throws ValueFormatException if the conversion from a name could not be performed
172 */
173 T create( Name value ) throws ValueFormatException;
174
175 /**
176 * Create a value from a path.
177 *
178 * @param value the path from which the value is to be created
179 * @return the value, or null if the supplied path is null
180 * @throws ValueFormatException if the conversion from a path could not be performed
181 */
182 T create( Path value ) throws ValueFormatException;
183
184 /**
185 * Create a value from a path segment.
186 *
187 * @param value the path segment from which the value is to be created
188 * @return the value, or null if the supplied path segment is null
189 * @throws ValueFormatException if the conversion from a path could not be performed
190 */
191 T create( Path.Segment value ) throws ValueFormatException;
192
193 /**
194 * Create a value from a reference.
195 *
196 * @param value the reference from which the value is to be created
197 * @return the value, or null if the supplied reference is null
198 * @throws ValueFormatException if the conversion from a reference could not be performed
199 */
200 T create( Reference value ) throws ValueFormatException;
201
202 /**
203 * Create a value from a URI.
204 *
205 * @param value the URI from which the value is to be created
206 * @return the value, or null if the supplied URI is null
207 * @throws ValueFormatException if the conversion from a URI could not be performed
208 */
209 T create( URI value ) throws ValueFormatException;
210
211 /**
212 * Create a value from a UUID.
213 *
214 * @param value the UUID from which the value is to be created
215 * @return the value, or null if the supplied URI is null
216 * @throws ValueFormatException if the conversion from a UUID could not be performed
217 */
218 T create( UUID value ) throws ValueFormatException;
219
220 /**
221 * Create a value from the binary content given by the supplied array.
222 *
223 * @param value the content to be used to create the value
224 * @return the value, or null if the supplied stream is null
225 * @throws ValueFormatException if the conversion from a byte array could not be performed
226 */
227 T create( byte[] value ) throws ValueFormatException;
228
229 /**
230 * Create a value from the binary content given by the supplied stream.
231 *
232 * @param value the binary object to be used to create the value
233 * @return the value, or null if the supplied stream is null
234 * @throws ValueFormatException if the conversion from the binary object could not be performed
235 * @throws IoException If an unexpected problem occurs while accessing the supplied binary value (such as an
236 * {@link IOException}).
237 */
238 T create( Binary value ) throws ValueFormatException, IoException;
239
240 /**
241 * Create a value from the binary content given by the supplied stream.
242 *
243 * @param stream the stream containing the content to be used to create the value
244 * @param approximateLength the approximate length of the content (in bytes)
245 * @return the value, or null if the supplied stream is null
246 * @throws ValueFormatException if the conversion from an input stream could not be performed
247 * @throws IoException If an unexpected problem occurs while accessing the supplied stream (such as an {@link IOException}).
248 */
249 T create( InputStream stream,
250 long approximateLength ) throws ValueFormatException, IoException;
251
252 /**
253 * Create a value from a the binary content given by the supplied reader.
254 *
255 * @param reader the reader containing the content to be used to create the value
256 * @param approximateLength the approximate length of the content (in bytes)
257 * @return the value, or null if the supplied string is null
258 * @throws ValueFormatException if the conversion from a reader could not be performed
259 * @throws IoException If an unexpected problem occurs while accessing the supplied reader (such as an {@link IOException}).
260 */
261 T create( Reader reader,
262 long approximateLength ) throws ValueFormatException, IoException;
263
264 /**
265 * Create a value from the specified information by determining which other <code>create</code> method applies and delegating
266 * to that method. Note that this method only will call <code>create</code> methods that take a single parameter; so this
267 * excludes {@link #create(InputStream, long)}, {@link #create(Reader, long)} and {@link #create(String, TextDecoder)}.
268 *
269 * @param value the value
270 * @return the new value, or null if the supplied parameter is null
271 * @throws ValueFormatException if the conversion from an object could not be performed
272 * @throws IoException If an unexpected problem occurs while accessing the supplied binary value (such as an
273 * {@link IOException}).
274 */
275 T create( Object value ) throws ValueFormatException, IoException;
276
277 /**
278 * Create an array of values from an array of string values, using no decoding.
279 *
280 * @param values the values
281 * @return the values, or null if the supplied string is null
282 * @throws ValueFormatException if the conversion from a string array could not be performed
283 * @see #create(String[], TextDecoder)
284 */
285 T[] create( String[] values ) throws ValueFormatException;
286
287 /**
288 * Create an array of values from an array of strings, using the supplied decoder.
289 *
290 * @param values the string values from which the values are to be created
291 * @param decoder the decoder that should be used; if null, the {@link #DEFAULT_DECODER default decoder} is used
292 * @return the value, or null if the supplied string is null
293 * @throws ValueFormatException if the conversion from a string array could not be performed
294 * @see #create(String)
295 */
296 T[] create( String[] values,
297 TextDecoder decoder ) throws ValueFormatException;
298
299 /**
300 * Create an array of values from an array of integers.
301 *
302 * @param values the integers from which the values are to be created
303 * @return the values, or null if the supplied array is null
304 * @throws ValueFormatException if the conversion from an integer array could not be performed
305 */
306 T[] create( int[] values ) throws ValueFormatException;
307
308 /**
309 * Create an array of values from an array of longs.
310 *
311 * @param values the longs from which the values are to be created
312 * @return the values, or null if the supplied array is null
313 * @throws ValueFormatException if the conversion from an array of longs could not be performed
314 */
315 T[] create( long[] values ) throws ValueFormatException;
316
317 /**
318 * Create an array of values from an array of booleans.
319 *
320 * @param values the booleans from which the values are to be created
321 * @return the values, or null if the supplied array is null
322 * @throws ValueFormatException if the conversion from an array of booleans could not be performed
323 */
324 T[] create( boolean[] values ) throws ValueFormatException;
325
326 /**
327 * Create an array of values from an array of floats.
328 *
329 * @param values the floats from which the values are to be created
330 * @return the values, or null if the supplied array is null
331 * @throws ValueFormatException if the conversion from an array of floats could not be performed
332 */
333 T[] create( float[] values ) throws ValueFormatException;
334
335 /**
336 * Create an array of values from an array of doubles.
337 *
338 * @param values the doubles from which the values are to be created
339 * @return the values, or null if the supplied array is null
340 * @throws ValueFormatException if the conversion from an array of doubles could not be performed
341 */
342 T[] create( double[] values ) throws ValueFormatException;
343
344 /**
345 * Create an array of values from an array of decimal values.
346 *
347 * @param values the decimals from which the values are to be created
348 * @return the values, or null if the supplied array is null
349 * @throws ValueFormatException if the conversion from an array of decimal values could not be performed
350 */
351 T[] create( BigDecimal[] values ) throws ValueFormatException;
352
353 /**
354 * Create an array of values from an array of Calendar instances.
355 *
356 * @param values the Calendar instances from which the values are to be created
357 * @return the values, or null if the supplied array is null
358 * @throws ValueFormatException if the conversion from an array of calendar instances could not be performed
359 */
360 T[] create( Calendar[] values ) throws ValueFormatException;
361
362 /**
363 * Create an array of values from an array of dates.
364 *
365 * @param values the dates from which the values are to be created
366 * @return the values, or null if the supplied array is null
367 * @throws ValueFormatException if the conversion from an array of date values could not be performed
368 */
369 T[] create( Date[] values ) throws ValueFormatException;
370
371 /**
372 * Create an array of values from an array of {@link DateTime} instants.
373 *
374 * @param values the instants from which the values are to be created
375 * @return the values, or null if the supplied array is null
376 * @throws ValueFormatException if the conversion from an array of date values could not be performed
377 */
378 T[] create( DateTime[] values ) throws ValueFormatException;
379
380 /**
381 * Create an array of values from an array of names.
382 *
383 * @param values the names from which the values are to be created
384 * @return the values, or null if the supplied array is null
385 * @throws ValueFormatException if the conversion from an array of names could not be performed
386 */
387 T[] create( Name[] values ) throws ValueFormatException;
388
389 /**
390 * Create an array of values from an array of paths.
391 *
392 * @param values the paths from which the values are to be created
393 * @return the values, or null if the supplied array is null
394 * @throws ValueFormatException if the conversion from an array of paths could not be performed
395 */
396 T[] create( Path[] values ) throws ValueFormatException;
397
398 /**
399 * Create an array of values from an array of references.
400 *
401 * @param values the references from which the values are to be created
402 * @return the values, or null if the supplied array is null
403 * @throws ValueFormatException if the conversion from an array of references could not be performed
404 */
405 T[] create( Reference[] values ) throws ValueFormatException;
406
407 /**
408 * Create an array of values from an array of URIs.
409 *
410 * @param values the URIs from which the values are to be created
411 * @return the values, or null if the supplied array is null
412 * @throws ValueFormatException if the conversion from an array of URIs could not be performed
413 */
414 T[] create( URI[] values ) throws ValueFormatException;
415
416 /**
417 * Create an array of values from an array of UUIDs.
418 *
419 * @param values the UUIDs from which the values are to be created
420 * @return the values, or null if the supplied array is null
421 * @throws ValueFormatException if the conversion from an array of UUIDs could not be performed
422 */
423 T[] create( UUID[] values ) throws ValueFormatException;
424
425 /**
426 * Create an array of values from the array of binary content.
427 *
428 * @param values the array of content to be used to create the values
429 * @return the value, or null if the supplied array is null
430 * @throws ValueFormatException if the conversion from an array of byte arrays could not be performed
431 */
432 T[] create( byte[][] values ) throws ValueFormatException;
433
434 /**
435 * Create an array of values from the array of binary objects.
436 *
437 * @param values the values
438 * @return the new value, or null if the supplied parameter is null
439 * @throws ValueFormatException if the conversion from an array of objects could not be performed
440 * @throws IoException If an unexpected problem occurs during the conversion.
441 */
442 T[] create( Binary[] values ) throws ValueFormatException, IoException;
443
444 /**
445 * Create an array of values from the specified information by determining which other <code>create</code> method applies for
446 * each object and then delegating to that method. Note that this method will not consider {@link #create(InputStream, long)},
447 * {@link #create(Reader, long)} and {@link #create(String, TextDecoder)}.
448 *
449 * @param values the values
450 * @return the new value, or null if the supplied parameter is null
451 * @throws ValueFormatException if the conversion from an array of objects could not be performed
452 * @throws IoException If an unexpected problem occurs during the conversion.
453 */
454 T[] create( Object[] values ) throws ValueFormatException, IoException;
455
456 /**
457 * Create an iterator over the values (of an unknown type). The factory converts any values as required. Note that this method
458 * will not consider {@link #create(InputStream, long)}, {@link #create(Reader, long)} and
459 * {@link #create(String, TextDecoder)}.
460 * <p>
461 * This is useful to use when iterating over the {@link Property#getValues() values} of a {@link Property}.
462 * </p>
463 *
464 * @param values the values
465 * @return the iterator of type <code>T</code> over the values, or null if the supplied parameter is null
466 * @throws ValueFormatException if the conversion from an iterator of objects could not be performed
467 * @throws IoException If an unexpected problem occurs during the conversion.
468 * @see Property#getValues()
469 */
470 Iterator<T> create( Iterator<?> values ) throws ValueFormatException, IoException;
471
472 /**
473 * Create an iterable with the values (of an unknown type). The factory converts any values as required. Note that this method
474 * will not consider {@link #create(InputStream, long)}, {@link #create(Reader, long)} and
475 * {@link #create(String, TextDecoder)}.
476 * <p>
477 * This is useful to use when converting all the {@link Property#getValues() values} of a {@link Property}.
478 * </p>
479 * Example:
480 *
481 * <pre>
482 * Property property = ...
483 * ExecutionContext executionContext = ...
484 * ValueFactory<String> stringFactory = executionContext.getValueFactories().getStringFactory();
485 * for (String token : stringFactory.create(property)) {
486 * ...
487 * }
488 * </pre>
489 *
490 * @param valueIterable the values
491 * @return the iterator of type <code>T</code> over the values, or null if the supplied parameter is null
492 * @throws ValueFormatException if the conversion from an iterator of objects could not be performed
493 * @throws IoException If an unexpected problem occurs during the conversion.
494 * @see Property#getValues()
495 */
496 Iterable<T> create( Iterable<?> valueIterable ) throws ValueFormatException, IoException;
497 }