1 /*
2 * Copyright 2010 Capgemini
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 *
15 */
16 package org.xmlfield.core.api;
17
18 import org.xmlfield.core.internal.XmlFieldFactory;
19
20 /**
21 * <p>
22 * An <code>XmlFieldSelectorFactory</code> instance can be used to create
23 * {@link XmlFieldSelector} objects.
24 * </p>
25 *
26 * <p>
27 * Thread safety :
28 * <ul>
29 * <li>Factories implementation <b>must</b> be thread-safe. They will be created
30 * once and reused by XmlField for every thread.</li>
31 * <li>Objects returned by factory should be considered <b>not thread safe</b>.
32 * Default behavior is to return a new object every time. However, if these
33 * objects are know to be thread safe, the factory can always return the same
34 * object for better performances.</li>
35 * </ul>
36 * </p>
37 *
38 * <p>
39 * See {@link #newInstance()} for lookup mechanism.
40 * </p>
41 *
42 * @author Guillaume Mary <guillaume.mary@capgemini.com>
43 */
44 public abstract class XmlFieldSelectorFactory extends XmlFieldFactory {
45 /**
46 * <p>
47 * Get a new <code>XmlFieldSelectorFactory</code> instance.
48 *
49 * @return Instance of an <code>XmlFieldSelectorFactory</code>.
50 *
51 * @throws RuntimeException
52 * When there is a failure in creating an
53 * <code>XmlFieldSelectorFactory</code>
54 */
55 public static final XmlFieldSelectorFactory newInstance() {
56 return newInstance(XmlFieldSelectorFactory.class);
57 }
58
59 /**
60 * <p>
61 * Return a new <code>XmlFieldSelector</code> using the underlying object
62 * model determined when the <code>XmlFieldSelectorFactory</code> was
63 * instantiated.
64 * </p>
65 *
66 * @return New instance of an <code>XmlFieldSelector</code>.
67 */
68 public abstract XmlFieldSelector newSelector();
69 }