1 package com.sourceforge.jpatterns.patterns.factory;
2
3 import com.sourceforge.jpatterns.core.configuration.exceptions.JPConfigException;
4 import com.sourceforge.jpatterns.patterns.IJPattern;
5
6 import java.util.List;
7 import java.util.Map;
8
9 /**
10 * The factory pattern implementation (in the terms of the JPatterns concept). Please be noticed the real implementation of this interface
11 * is specified at the JPatterns config properties file. When we have the factory pattern working then we would be able to save other
12 * implementationsw at the factory. Be noticed that there would be mapping
13 * castor type base name <-> implementation of the JPatterns interface we would need for working with the concrete castor type.
14 * <br/>
15 * <strong>All the methods of this interface have "scope" argument. It is optional. If this is null we use the scope of the appropriate
16 * Factory object to obtain the scope of the implementation. if it is not null - we are using it as the scope id - please review
17 * comments to {@link com.sourceforge.jpatterns.core.IJPEngine#getFactory(String,String)} for more on that.</strong>
18 * todo [zmicer]: provide XML based examples of the configurations for the each method. Document the pattern.
19 * <p/>
20 * note [zmicer]: be noticed this interface and the implementation are used for both consumer and framework specific operations.
21 * <p/>
22 * $Author:: zmicer $<br/>
23 * $Rev:: 67 $<br/> * $Date:: 2007-08-28 21:37:07 #$<br/>
24 */
25 public interface IJPFactory extends IJPattern
26 {
27 /**
28 * Get implementation of the interface defined by the given class and the scope we need to obtain.
29 * <br/>
30 * Be noticed the validation if the implementation specified at the JPatterns config file is casted to the interface provided.
31 *
32 * @param interfaceClass the class representing the interface
33 * Can not be null (otherwise <code>IllegalArgumentException</code> would appear).
34 * @param scope the scope where do we need to find the implementation. In the case this is null -
35 * the default value for scope would be used (would be taken from factory object)
36 *
37 * @return the Object = the real implementation of the class.
38 *
39 * @throws JPConfigException in the case we can not retrieve the implementation for some reasons
40 */
41 Object getImplementation(final Class interfaceClass, final String scope)
42 throws JPConfigException;
43
44 /**
45 * Get implementation of the interface defined by the given class (class of the interface).
46 * <br/>
47 * Validation if the implementation is casted to the interface defining by interfaceClassBaseName is not done here as this String
48 * could be just any key string
49 *
50 * @param interfaceClassBaseName the base name of the interface (e.g. <code>IJPFactory</code>), also it could be just String key
51 * (just logical case for which we need to obtain smth.)
52 * @param scope the scope where do we need to find the implementation. In the case this is null -
53 * the default value for scope would be used (would be taken from factory object)
54 *
55 * @return the Object = the real implementation of the class.
56 *
57 * @throws JPConfigException in the case we can not retrieve the implementation for some reasons
58 */
59 Object getImplementation(final String interfaceClassBaseName, final String scope)
60 throws JPConfigException;
61
62 /**
63 * Get the full name of the implementation of the interface defined by the given class and the scope we need to obtain.
64 *
65 * @param interfaceClass the class representing the interface
66 * Can not be null (otherwise <code>IllegalArgumentException</code> would appear).
67 * @param scope the scope where do we need to find the implementation. In the case this is null -
68 * the default value for scope would be used (would be taken from factory object)
69 *
70 * @return the Object = the real implementation of the class.
71 *
72 * @throws JPConfigException in the case we can not retrieve the implementation for some reasons
73 */
74 String getImplementationFullName(final Class interfaceClass, final String scope)
75 throws JPConfigException;
76
77 /**
78 * Get the full name of the implementation of the interface defined by the given class (class of the interface).
79 *
80 * @param interfaceClassBaseName the base name of the interface (e.g. <code>IJPFactory</code>)
81 * @param scope the scope where do we need to find the implementation. In the case this is null -
82 * the default value for scope would be used (would be taken from factory object)
83 *
84 * @return the Object = the real implementation of the class.
85 *
86 * @throws JPConfigException in the case we can not retrieve the implementation for some reasons
87 */
88 String getImplementationFullName(final String interfaceClassBaseName, final String scope)
89 throws JPConfigException;
90
91 /**
92 * Get implementation of the interface defined by the given class and the scope we need to obtain.
93 * <br/>
94 * note [zmicer]: be noticed that validation if the given interface is the super type of the implementation is performed in this method
95 *
96 * @param interfaceClass the class representing the interface
97 * Can not be null (otherwise <code>IllegalArgumentException</code> would appear).
98 * @param implType the type of implementation
99 * @param scope the scope where do we need to find the implementation. In the case this is null -
100 * the default value for scope would be used (would be taken from factory object)
101 *
102 * @return the Object = the real implementation of the class.
103 *
104 * @throws JPConfigException in the case we can not retrieve the implementation for some reasons
105 */
106 Object getImplementation(final Class interfaceClass, final String implType, final String scope)
107 throws JPConfigException;
108
109 /**
110 * Get implementation of the interface defined by the given class (class of the interface).
111 * <br/>
112 * note [zmicer]: be noticed that validation if the given interface is the super type of the implementation
113 * <strong>is not</strong> performed in this method
114 *
115 * @param interfaceClassBaseName the base name of the interface (e.g. <code>IJPFactory</code>)
116 * @param implType the type of implementation
117 * @param scope the scope where do we need to find the implementation. In the case this is null -
118 * the default value for scope would be used (would be taken from factory object)
119 *
120 * @return the Object = the real implementation of the class.
121 *
122 * @throws JPConfigException in the case we can not retrieve the implementation for some reasons
123 */
124 Object getImplementation(final String interfaceClassBaseName, final String implType, final String scope)
125 throws JPConfigException;
126
127 /**
128 * Get the Map of implementations of the interface defined by the given class and the scope we need to obtain.
129 * <br/>
130 * The format is as follows:
131 * #key: logical type we need
132 * #value: the Object - the concrete implementation of the interface provided corresponding to the logical type
133 *
134 * @param interfaceClass the class representing the interface
135 * Can not be null (otherwise <code>IllegalArgumentException</code> would appear).
136 * @param scope the scope where do we need to find the implementation. In the case this is null -
137 * the default value for scope would be used (would be taken from factory object)
138 *
139 * @return the Object = the real implementation of the class.
140 *
141 * @throws JPConfigException in the case we can not retrieve the implementation for some reasons
142 */
143 Map<String, Object> getImplementations(final Class interfaceClass, final String scope)
144 throws JPConfigException;
145
146 /**
147 * Get the Map of implementations of the interface defined by the given class and the scope we need to obtain.
148 * <br/>
149 * The format is as follows:
150 * #key: logical type we need
151 * #value: the Object - the concrete implementation of the interface provided corresponding to the logical type
152 *
153 * @param interfaceClassBaseName the base name of the interface (e.g. <code>IJPFactory</code>)
154 * @param scope the scope where do we need to find the implementation. In the case this is null -
155 * the default value for scope would be used (would be taken from factory object)
156 *
157 * @return the Object = the real implementation of the class.
158 *
159 * @throws JPConfigException in the case we can not retrieve the implementation for some reasons
160 */
161 Map<String, Object> getImplementations(final String interfaceClassBaseName, final String scope)
162 throws JPConfigException;
163
164 /**
165 * Get the Map of implementations of the interface defined by the given class and the scope we need to obtain.
166 * <br/>
167 * The format is as follows:
168 * #key: logical type we need
169 * #value: the full name of the concrete implementation of the interface provided corresponding to the logical type
170 *
171 * @param interfaceClass the class representing the interface
172 * Can not be null (otherwise <code>IllegalArgumentException</code> would appear).
173 * @param scope the scope where do we need to find the implementation. In the case this is null -
174 * the default value for scope would be used (would be taken from factory object)
175 *
176 * @return the Object = the real implementation of the class.
177 *
178 * @throws JPConfigException in the case we can not retrieve the implementation for some reasons
179 */
180 Map<String, String> getImplementationsFullNames(final Class interfaceClass, final String scope)
181 throws JPConfigException;
182
183 /**
184 * Get the Map of implementations of the interface defined by the given class and the scope we need to obtain.
185 * <br/>
186 * The format is as follows:
187 * #key: logical type we need
188 * #value: the full name of the concrete implementation of the interface provided corresponding to the logical type
189 *
190 * @param interfaceClassBaseName the base name of the interface (e.g. <code>IJPFactory</code>)
191 * @param scope the scope where do we need to find the implementation. In the case this is null -
192 * the default value for scope would be used (would be taken from factory object)
193 *
194 * @return the Object = the real implementation of the class.
195 *
196 * @throws JPConfigException in the case we can not retrieve the implementation for some reasons
197 */
198 Map<String, String> getImplementationsFullNames(final String interfaceClassBaseName, final String scope)
199 throws JPConfigException;
200
201 /**
202 * The the operator for the provided object and scope. This method would determine the base interface of the product
203 * (we would consider the implementation class implements the appropriate interface at once).
204 * <br/>
205 * The key we would find to obtained the appropriate castor config item would be:
206 * %base name of productBaseClass% + "_" + %base name of operatorBaseClass%
207 *
208 * @param productBaseClass the interface or base class of the product for which we are finding the implementation of the operator.
209 * Still the actual class of the product provided would be used too. Can not be null (otherwise
210 * <code>IllegalArgumentException</code> would appear).
211 * @param operatorBaseClass the interface of the base class of the operator we would need to obtain the appropriate configuration item.
212 * Be noticed this base class defines the scope we need to consider to obtain the necessary operator
213 * Can not be null (otherwise <code>IllegalArgumentException</code> would appear).
214 * @param productObj the product for which we need the implementation. This product should of the
215 * <code>productBaseClass</code> class
216 * Can not be null (otherwise <code>IllegalArgumentException</code> would appear).
217 * @param scope the scope where do we need to find the implementation. In the case this is null -
218 * the default value for scope would be used (would be taken from factory object)
219 *
220 * @return the instance of the operator to be used for the given product.
221 *
222 * @throws JPConfigException in the case we can not retrieve the implementation for some reasons
223 */
224 Object getOperator(final Class productBaseClass, final Class operatorBaseClass, final Object productObj, final String scope)
225 throws JPConfigException;
226
227 /**
228 * Get the mappings between the operators (which would be created at this methods) and the List of the products objects provided here.
229 * Also the classes for the products and operators are provided as the base path to the necessary Jpatterns configuration.
230 * note [zmicer]: In the case there are some different products instances with identical class only one operator would be created.
231 *
232 * @param productBaseClass the interface or base class of the product for which we are finding the implementation of the operator.
233 * Still the actual class of the product provided would be used too. Can not be null (otherwise
234 * <code>IllegalArgumentException</code> would appear).
235 * @param operatorBaseClass the interface of the base class of the operator we would need to obtain the appropriate configuration item.
236 * Be noticed this base class defines the scope we need to consider to obtain the necessary operator
237 * Can not be null (otherwise <code>IllegalArgumentException</code> would appear).
238 * @param productObjs the List of the products for which we need to obtain the appropriate operators. These products should of the
239 * <code>productBaseClass</code> class. Can not be null (otherwise <code>IllegalArgumentException</code>
240 * would appear).
241 * @param scope the scope where do we need to find the implementation. In the case this is null -
242 * the default value for scope would be used (would be taken from factory object)
243 *
244 * @return the mapping between the products objects (all of them were provided as the members of the <code>productObjs</code> list) and
245 * the appropriate operators.
246 *
247 * @throws JPConfigException in the case we can not retrieve the implementation for some reasons
248 */
249 Map<Object, Object> getOperators(final Class productBaseClass, final Class operatorBaseClass, final List<Object> productObjs, final String scope)
250 throws JPConfigException;
251 }