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 java.io.IOException;
027 import java.io.InputStream;
028 import java.io.Reader;
029 import java.math.BigDecimal;
030 import java.net.URI;
031 import java.util.Calendar;
032 import java.util.Date;
033 import java.util.Iterator;
034 import java.util.UUID;
035 import org.jboss.dna.common.text.TextDecoder;
036 import org.jboss.dna.common.text.TextEncoder;
037
038 /**
039 * A factory for {@link Property} values. Each create method may throw one of these exceptions when attempting to convert a
040 * supplied value to the {@link #getPropertyType() factory's type}:
041 * <ul>
042 * <li>{@link IllegalArgumentException} - If the supplied value is invalid in respect to the conversion being attempted.</li>
043 * <li>{@link UnsupportedOperationException} - If a conversion from the supplied value is not supported.</li>
044 * <li>{@link IoException} - If an unexpected problem occurs during the conversion (such as an {@link IOException}).</li>
045 * </ul>
046 *
047 * @author Randall Hauch
048 * @author John Verhaeg
049 * @param <T> the type of value to create
050 */
051 public interface ValueFactory<T> {
052
053 static final TextDecoder DEFAULT_DECODER = Path.NO_OP_DECODER;
054 static final TextEncoder DEFAULT_ENCODER = Path.NO_OP_ENCODER;
055
056 /**
057 * Get the {@link PropertyType type} of values created by this factory.
058 *
059 * @return the value type; never null
060 */
061 PropertyType getPropertyType();
062
063 /**
064 * Create a value from a string, using no decoding.
065 *
066 * @param value the string from which the value is to be created
067 * @return the value, or null if the supplied string is null
068 * @throws ValueFormatException if the conversion from a string could not be performed
069 * @see #create(String, TextDecoder)
070 */
071 T create( String value ) throws ValueFormatException;
072
073 /**
074 * Create a value from a string, using the supplied decoder.
075 *
076 * @param value the string from which the value is to be created
077 * @param decoder the decoder that should be used; if null, the {@link #DEFAULT_DECODER default decoder} is used
078 * @return the value, or null if the supplied string is null
079 * @throws ValueFormatException if the conversion from a string could not be performed
080 * @see #create(String)
081 */
082 T create( String value,
083 TextDecoder decoder ) throws ValueFormatException;
084
085 /**
086 * Create a value from an integer.
087 *
088 * @param value the integer from which the value is to be created
089 * @return the value; never null
090 * @throws ValueFormatException if the conversion from an integer could not be performed
091 */
092 T create( int value ) throws ValueFormatException;
093
094 /**
095 * Create a long from a string.
096 *
097 * @param value the string from which the long is to be created
098 * @return the value; never null
099 * @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 reference.
186 *
187 * @param value the reference from which the value is to be created
188 * @return the value, or null if the supplied reference is null
189 * @throws ValueFormatException if the conversion from a reference could not be performed
190 */
191 T create( Reference value ) throws ValueFormatException;
192
193 /**
194 * Create a value from a URI.
195 *
196 * @param value the URI from which the value is to be created
197 * @return the value, or null if the supplied URI is null
198 * @throws ValueFormatException if the conversion from a URI could not be performed
199 */
200 T create( URI value ) throws ValueFormatException;
201
202 /**
203 * Create a value from a UUID.
204 *
205 * @param value the UUID 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 UUID could not be performed
208 */
209 T create( UUID value ) throws ValueFormatException;
210
211 /**
212 * Create a value from the binary content given by the supplied array.
213 *
214 * @param value the content to be used to create the value
215 * @return the value, or null if the supplied stream is null
216 * @throws ValueFormatException if the conversion from a byte array could not be performed
217 */
218 T create( byte[] value ) throws ValueFormatException;
219
220 /**
221 * Create a value from the binary content given by the supplied stream.
222 *
223 * @param value the binary object 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 the binary object could not be performed
226 * @throws IoException If an unexpected problem occurs while accessing the supplied binary value (such as an
227 * {@link IOException}).
228 */
229 T create( Binary value ) throws ValueFormatException, IoException;
230
231 /**
232 * Create a value from the binary content given by the supplied stream.
233 *
234 * @param stream the stream containing the content to be used to create the value
235 * @param approximateLength the approximate length of the content (in bytes)
236 * @return the value, or null if the supplied stream is null
237 * @throws ValueFormatException if the conversion from an input stream could not be performed
238 * @throws IoException If an unexpected problem occurs while accessing the supplied stream (such as an {@link IOException}).
239 */
240 T create( InputStream stream,
241 long approximateLength ) throws ValueFormatException, IoException;
242
243 /**
244 * Create a value from a the binary content given by the supplied reader.
245 *
246 * @param reader the reader containing the content to be used to create the value
247 * @param approximateLength the approximate length of the content (in bytes)
248 * @return the value, or null if the supplied string is null
249 * @throws ValueFormatException if the conversion from a reader could not be performed
250 * @throws IoException If an unexpected problem occurs while accessing the supplied reader (such as an {@link IOException}).
251 */
252 T create( Reader reader,
253 long approximateLength ) throws ValueFormatException, IoException;
254
255 /**
256 * Create a value from the specified information by determining which other <code>create</code> method applies and delegating
257 * to that method. Note that this method only will call <code>create</code> methods that take a single parameter; so this
258 * excludes {@link #create(InputStream, long)}, {@link #create(Reader, long)} and {@link #create(String, TextDecoder)}.
259 *
260 * @param value the value
261 * @return the new value, or null if the supplied parameter is null
262 * @throws ValueFormatException if the conversion from an object could not be performed
263 * @throws IoException If an unexpected problem occurs while accessing the supplied binary value (such as an
264 * {@link IOException}).
265 */
266 T create( Object value ) throws ValueFormatException, IoException;
267
268 /**
269 * Create an array of values from an array of string values, using no decoding.
270 *
271 * @param values the values
272 * @return the values, or null if the supplied string is null
273 * @throws ValueFormatException if the conversion from a string array could not be performed
274 * @see #create(String[], TextDecoder)
275 */
276 T[] create( String[] values ) throws ValueFormatException;
277
278 /**
279 * Create an array of values from an array of strings, using the supplied decoder.
280 *
281 * @param values the string values from which the values are to be created
282 * @param decoder the decoder that should be used; if null, the {@link #DEFAULT_DECODER default decoder} is used
283 * @return the value, or null if the supplied string is null
284 * @throws ValueFormatException if the conversion from a string array could not be performed
285 * @see #create(String)
286 */
287 T[] create( String[] values,
288 TextDecoder decoder ) throws ValueFormatException;
289
290 /**
291 * Create an array of values from an array of integers.
292 *
293 * @param values the integers from which the values are to be created
294 * @return the values, or null if the supplied array is null
295 * @throws ValueFormatException if the conversion from an integer array could not be performed
296 */
297 T[] create( int[] values ) throws ValueFormatException;
298
299 /**
300 * Create an array of values from an array of longs.
301 *
302 * @param values the longs 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 array of longs could not be performed
305 */
306 T[] create( long[] values ) throws ValueFormatException;
307
308 /**
309 * Create an array of values from an array of booleans.
310 *
311 * @param values the booleans 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 booleans could not be performed
314 */
315 T[] create( boolean[] values ) throws ValueFormatException;
316
317 /**
318 * Create an array of values from an array of floats.
319 *
320 * @param values the floats 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 floats could not be performed
323 */
324 T[] create( float[] values ) throws ValueFormatException;
325
326 /**
327 * Create an array of values from an array of doubles.
328 *
329 * @param values the doubles 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 doubles could not be performed
332 */
333 T[] create( double[] values ) throws ValueFormatException;
334
335 /**
336 * Create an array of values from an array of decimal values.
337 *
338 * @param values the decimals 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 decimal values could not be performed
341 */
342 T[] create( BigDecimal[] values ) throws ValueFormatException;
343
344 /**
345 * Create an array of values from an array of Calendar instances.
346 *
347 * @param values the Calendar instances 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 calendar instances could not be performed
350 */
351 T[] create( Calendar[] values ) throws ValueFormatException;
352
353 /**
354 * Create an array of values from an array of dates.
355 *
356 * @param values the dates 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 date values could not be performed
359 */
360 T[] create( Date[] values ) throws ValueFormatException;
361
362 /**
363 * Create an array of values from an array of {@link DateTime} instants.
364 *
365 * @param values the instants 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( DateTime[] values ) throws ValueFormatException;
370
371 /**
372 * Create an array of values from an array of names.
373 *
374 * @param values the names 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 names could not be performed
377 */
378 T[] create( Name[] values ) throws ValueFormatException;
379
380 /**
381 * Create an array of values from an array of paths.
382 *
383 * @param values the paths 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 paths could not be performed
386 */
387 T[] create( Path[] values ) throws ValueFormatException;
388
389 /**
390 * Create an array of values from an array of references.
391 *
392 * @param values the references 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 references could not be performed
395 */
396 T[] create( Reference[] values ) throws ValueFormatException;
397
398 /**
399 * Create an array of values from an array of URIs.
400 *
401 * @param values the URIs 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 URIs could not be performed
404 */
405 T[] create( URI[] values ) throws ValueFormatException;
406
407 /**
408 * Create an array of values from an array of UUIDs.
409 *
410 * @param values the UUIDs 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 UUIDs could not be performed
413 */
414 T[] create( UUID[] values ) throws ValueFormatException;
415
416 /**
417 * Create an array of values from the array of binary content.
418 *
419 * @param values the array of content to be used to create the values
420 * @return the value, or null if the supplied array is null
421 * @throws ValueFormatException if the conversion from an array of byte arrays could not be performed
422 */
423 T[] create( byte[][] values ) throws ValueFormatException;
424
425 /**
426 * Create an array of values from the array of binary objects.
427 *
428 * @param values the values
429 * @return the new value, or null if the supplied parameter is null
430 * @throws ValueFormatException if the conversion from an array of objects could not be performed
431 * @throws IoException If an unexpected problem occurs during the conversion.
432 */
433 T[] create( Binary[] values ) throws ValueFormatException, IoException;
434
435 /**
436 * Create an array of values from the specified information by determining which other <code>create</code> method applies for
437 * each object and then delegating to that method. Note that this method will not consider {@link #create(InputStream, long)},
438 * {@link #create(Reader, long)} and {@link #create(String, TextDecoder)}.
439 *
440 * @param values the values
441 * @return the new value, or null if the supplied parameter is null
442 * @throws ValueFormatException if the conversion from an array of objects could not be performed
443 * @throws IoException If an unexpected problem occurs during the conversion.
444 */
445 T[] create( Object[] values ) throws ValueFormatException, IoException;
446
447 /**
448 * Create an iterator over the values (of an unknown type). The factory converts any values as required. Note that this method
449 * will not consider {@link #create(InputStream, long)}, {@link #create(Reader, long)} and
450 * {@link #create(String, TextDecoder)}.
451 * <p>
452 * This is useful to use when iterating over the {@link Property#getValues() values} of a {@link Property}.
453 * </p>
454 *
455 * @param values the values
456 * @return the iterator of type <code>T</code> over the values, or null if the supplied parameter is null
457 * @throws ValueFormatException if the conversion from an iterator of objects could not be performed
458 * @throws IoException If an unexpected problem occurs during the conversion.
459 * @see Property#getValues()
460 */
461 Iterator<T> create( Iterator<?> values ) throws ValueFormatException, IoException;
462
463 /**
464 * Create an iterable with the values (of an unknown type). The factory converts any values as required. Note that this method
465 * will not consider {@link #create(InputStream, long)}, {@link #create(Reader, long)} and
466 * {@link #create(String, TextDecoder)}.
467 * <p>
468 * This is useful to use when converting all the {@link Property#getValues() values} of a {@link Property}.
469 * </p>
470 * Example:
471 *
472 * <pre>
473 * Property property = ...
474 * ExecutionContext executionContext = ...
475 * ValueFactory<String> stringFactory = executionContext.getValueFactories().getStringFactory();
476 * for (String token : stringFactory.create(property)) {
477 * ...
478 * }
479 * </pre>
480 *
481 * @param valueIterable the values
482 * @return the iterator of type <code>T</code> over the values, or null if the supplied parameter is null
483 * @throws ValueFormatException if the conversion from an iterator of objects could not be performed
484 * @throws IoException If an unexpected problem occurs during the conversion.
485 * @see Property#getValues()
486 */
487 Iterable<T> create( Iterable<?> valueIterable ) throws ValueFormatException, IoException;
488 }