1 /*
2 * jDTAUS Core API
3 * Copyright (C) 2005 Christian Schulte
4 * <cs@schulte.it>
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this library; if not, write to the Free Software
18 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
19 *
20 */
21 package org.jdtaus.core.container;
22
23 import java.util.Locale;
24
25 /**
26 * Object container.
27 *
28 * @author <a href="mailto:cs@schulte.it">Christian Schulte</a>
29 * @version $JDTAUS: Container.java 8641 2012-09-27 06:45:17Z schulte $
30 *
31 * @see ContainerFactory
32 */
33 public interface Container
34 {
35 //--Container---------------------------------------------------------------
36
37 /**
38 * Gets an instance of an implementation of a specification.
39 * <p>When creating objects, use of the classloader associated with the
40 * given class, as returned by method {@link Class#getClassLoader()}, is
41 * recommended. Only if that method returns {@code null}, indicating the
42 * class has been loaded by the bootstrap classloader, use of the bootstrap
43 * classloader is recommended.</p>
44 *
45 * @param specification The class of the specification to return an
46 * implementation instance of.
47 * @param implementationName The logical name of the implementation to
48 * return an instance of.
49 *
50 * @return An instance of an implementation as specified by the
51 * specification defined for class {@code specification}.
52 *
53 * @throws NullPointerException if {@code specification} or
54 * {@code implementationName} is {@code null}.
55 * @throws MissingSpecificationException if no specification is defined
56 * for {@code specification}.
57 * @throws MissingImplementationException if no implementation named
58 * {@code implementationName} is defined for the specification identified
59 * by {@code specification}.
60 * @throws org.jdtaus.core.container.InstantiationException if creating
61 * an instance of the implementation fails.
62 * @throws ContainerError for unrecoverable container errors.
63 * @throws ContextError for unrecoverable context errors.
64 * @throws ModelError for unrecoverable model errors.
65 * @deprecated Renamed to {@link #getObject(java.lang.Class, java.lang.String) }.
66 */
67 Object getImplementation( Class specification, String implementationName );
68
69 /**
70 * Gets an instance of an implementation of a dependency.
71 * <p>When creating objects, use of the classloader associated with the
72 * given class, as returned by method {@link Class#getClassLoader()}, is
73 * recommended. Only if that method returns {@code null}, indicating the
74 * class has been loaded by the bootstrap classloader, use of the bootstrap
75 * classloader is recommended.</p>
76 *
77 * @param implementation The class of the implementation to return an
78 * instance of a dependency of.
79 * @param dependencyName The logical name of the dependency to return an
80 * instance of.
81 *
82 * @return An instance of the implementation of the dependency named
83 * {@code dependencyName} for {@code implementation}.
84 *
85 * @throws NullPointerException if {@code implementation} or
86 * {@code dependencyName} is {@code null}.
87 * @throws MissingImplementationException if no implementation is defined
88 * for {@code implementation}.
89 * @throws MissingDependencyException if no dependency named
90 * {@code dependencyName} is defined for the implementation identified by
91 * {@code implementation}.
92 * @throws org.jdtaus.core.container.InstantiationException if creating
93 * an instance of the dependency fails.
94 * @throws ContainerError for unrecoverable container errors.
95 * @throws ContextError for unrecoverable context errors.
96 * @throws ModelError for unrecoverable model errors.
97 * @deprecated Replaced by {@link #getDependency(java.lang.Object, java.lang.String)}.
98 * This method does not take an argument providing information regarding
99 * the identity of the object to return a dependency of.
100 */
101 Object getDependency( Class implementation, String dependencyName );
102
103 /**
104 * Gets an instance of an implementation of a specification.
105 * <p>The object to return is resolved based on the multiplicity of the
106 * specification defined for the specification identified by the given
107 * identifier. For a multiplicity equal to
108 * {@link Specification#MULTIPLICITY_ONE}, the returned object will be an
109 * instance of the class of that specification. For a multiplicity equal to
110 * {@link Specification#MULTIPLICITY_MANY}, the returned object will be a
111 * one-dimensional array of instances of the class of that specification.</p>
112 *
113 * @param specificationIdentifier The identifier of the specification to
114 * return an implementation instance of.
115 *
116 * @return An instance of an implementation as specified by the
117 * specification identified by {@code specificationIdentifier}.
118 *
119 * @throws NullPointerException if {@code specificationIdentifier} is
120 * {@code null}.
121 * @throws MissingSpecificationException if no specification is defined
122 * for {@code specificationIdentifier}.
123 * @throws MultiplicityConstraintException if the multiplicity of the
124 * specification equals {@code MULTIPLICITY_ONE} and the model holds either
125 * no or more than one implementation.
126 * @throws org.jdtaus.core.container.InstantiationException if creating an
127 * implementation instance fails.
128 * @throws ContainerError for unrecoverable container errors.
129 * @throws ContextError for unrecoverable context errors.
130 * @throws ModelError for unrecoverable model errors.
131 * @deprecated Replaced by {@link #getObject(java.lang.Class) }. This method
132 * does not take an argument providing information regarding the classloader
133 * in use. It is recommended to use the classloader which loaded the
134 * implementation of this interface as returned by method
135 * {@link Class#getClassLoader()}. Only if that method returns {@code null},
136 * use of the bootstrap classloader is recommended.
137 */
138 Object getObject( String specificationIdentifier );
139
140 /**
141 * Gets an instance of an implementation of a specification.
142 *
143 * @param specificationIdentifier The identifier of the specification to
144 * return an implementation instance of.
145 * @param implementationName The logical name of the implementation to
146 * return an instance of.
147 *
148 * @return An instance of the implementation named
149 * {@code implementationName} as specified by the specification identified
150 * by {@code specificationIdentifier}.
151 *
152 * @throws NullPointerException if {@code specificationIdentifier} or
153 * {@code implementationName} is {@code null}.
154 * @throws MissingSpecificationException if no specification is defined
155 * for {@code specificationIdentifier}.
156 * @throws MissingImplementationException if no implementation named
157 * {@code implementationName} is defined for the specification identified by
158 * {@code specificationIdentifier}.
159 * @throws org.jdtaus.core.container.InstantiationException if creating an
160 * implementation instance fails.
161 * @throws ContainerError for unrecoverable container errors.
162 * @throws ContextError for unrecoverable context errors.
163 * @throws ModelError for unrecoverable model errors.
164 * @deprecated Replaced by {@link #getObject(java.lang.Class, java.lang.String) }.
165 * This method does not take an argument providing information regarding the
166 * classloader in use. It is recommended to use the classloader which loaded
167 * the implementation of this interface as returned by method
168 * {@link Class#getClassLoader()}. Only if that method returns {@code null},
169 * use of the bootstrap classloader is recommended.
170 */
171 Object getObject( String specificationIdentifier,
172 String implementationName );
173
174 /**
175 * Gets an instance of an implementation of a specification.
176 * <p>The object to return is resolved based on the multiplicity of the
177 * specification defined for the given class. For a multiplicity equal to
178 * {@link Specification#MULTIPLICITY_ONE}, the returned object will be an
179 * instance of the given class. For a multiplicity equal to
180 * {@link Specification#MULTIPLICITY_MANY}, the returned object will be a
181 * one-dimensional array of instances of the given class.</p>
182 * <p>When creating objects, use of the classloader associated with the
183 * given class, as returned by method {@link Class#getClassLoader()}, is
184 * recommended. Only if that method returns {@code null}, indicating the
185 * class has been loaded by the bootstrap classloader, use of the bootstrap
186 * classloader is recommended.</p>
187 *
188 * @param specification The class of the specification to return an
189 * implementation instance of.
190 *
191 * @return An instance of an implementation as specified by the
192 * specification defined for class {@code specification}.
193 *
194 * @throws NullPointerException if {@code specification} is {@code null}.
195 * @throws MissingSpecificationException if no specification is defined
196 * for {@code specification}.
197 * @throws MultiplicityConstraintException if the multiplicity of the
198 * specification defined for {@code specification} equals
199 * {@code MULTIPLICITY_ONE} and the model holds either no or more than one
200 * implementation.
201 * @throws org.jdtaus.core.container.InstantiationException if creating an
202 * implementation instance fails.
203 * @throws ContainerError for unrecoverable container errors.
204 * @throws ContextError for unrecoverable context errors.
205 * @throws ModelError for unrecoverable model errors.
206 */
207 Object getObject( Class specification );
208
209 /**
210 * Gets an instance of an implementation of a specification.
211 * <p>When creating objects, use of the classloader associated with the
212 * given class, as returned by method {@link Class#getClassLoader()}, is
213 * recommended. Only if that method returns {@code null}, indicating the
214 * class has been loaded by the bootstrap classloader, use of the bootstrap
215 * classloader is recommended.</p>
216 *
217 * @param specification The class of the specification to return an
218 * implementation instance of.
219 * @param implementationName The logical name of the implementation to
220 * return an instance of.
221 *
222 * @return An instance of the implementation named
223 * {@code implementationName} as specified by the specification defined for
224 * class {@code specification}.
225 *
226 * @throws NullPointerException if {@code specification} or
227 * {@code implementationName} is {@code null}.
228 * @throws MissingSpecificationException if no specification is defined
229 * for {@code specification}.
230 * @throws MissingImplementationException if no implementation named
231 * {@code implementationName} is defined for the specification for
232 * {@code specification}.
233 * @throws org.jdtaus.core.container.InstantiationException if creating an
234 * implementation instance fails.
235 * @throws ContainerError for unrecoverable container errors.
236 * @throws ContextError for unrecoverable context errors.
237 * @throws ModelError for unrecoverable model errors.
238 */
239 Object getObject( Class specification, String implementationName );
240
241 /**
242 * Gets an instance of a dependency of an object.
243 * <p>The object to return is resolved based on the multiplicity of the
244 * specification defined for the dependency. For a multiplicity equal to
245 * {@link Specification#MULTIPLICITY_ONE}, the returned object will be an
246 * instance of the class of that specification. For a multiplicity equal to
247 * {@link Specification#MULTIPLICITY_MANY}, the returned object will be a
248 * one-dimensional array of instances of the class of that specification.</p>
249 * <p>When creating objects, use of the classloader associated with the
250 * class of the given object, as returned by method
251 * {@link Class#getClassLoader()}, is recommended. Only if that method
252 * returns {@code null}, indicating the class has been loaded by the
253 * bootstrap classloader, use of the bootstrap classloader is recommended.</p>
254 *
255 * @param object The object to return a dependency instance of.
256 * @param dependencyName The logical name of the dependency to return an
257 * instance of.
258 *
259 * @return An instance of the dependency named {@code dependencyName} of
260 * {@code object}.
261 *
262 * @throws NullPointerException if {@code object} or {@code dependencyName}
263 * is {@code null}.
264 * @throws MissingImplementationException if no implementation is defined
265 * for {@code object}.
266 * @throws MissingDependencyException if no dependency named
267 * {@code dependencyName} is defined for {@code object}.
268 * @throws MultiplicityConstraintException if the specification of the
269 * dependency has a multiplicity of {@code MULTIPLICITY_ONE} without any
270 * implementation being available.
271 * @throws org.jdtaus.core.container.InstantiationException if creating an
272 * instance of the dependency fails.
273 * @throws ContainerError for unrecoverable container errors.
274 * @throws ContextError for unrecoverable context errors.
275 * @throws ModelError for unrecoverable model errors.
276 */
277 Object getDependency( Object object, String dependencyName );
278
279 /**
280 * Gets an instance of a property of an object.
281 * <p>When creating objects, use of the classloader associated with the
282 * class of the given object, as returned by method
283 * {@link Class#getClassLoader()}, is recommended. Only if that method
284 * returns {@code null}, indicating the class has been loaded by the
285 * bootstrap classloader, use of the bootstrap classloader is recommended.</p>
286 *
287 * @param object The object to return a property instance of.
288 * @param propertyName The logical name of the property to return an
289 * instance of.
290 *
291 * @return An instance of the property named {@code propertyName} of
292 * {@code object}.
293 *
294 * @throws NullPointerException if {@code object} or {@code propertyName} is
295 * {@code null}.
296 * @throws MissingImplementationException if no implementation is defined
297 * for {@code object}.
298 * @throws MissingPropertyException if no property named
299 * {@code propertyName} is defined for {@code object}.
300 * @throws ContainerError for unrecoverable container errors.
301 * @throws ContextError for unrecoverable context errors.
302 * @throws ModelError for unrecoverable model errors.
303 */
304 Object getProperty( Object object, String propertyName );
305
306 /**
307 * Gets an instance of a message of an object.
308 * <p>When creating objects, use of the classloader associated with the
309 * class of the given object, as returned by method
310 * {@link Class#getClassLoader()}, is recommended. Only if that method
311 * returns {@code null}, indicating the class has been loaded by the
312 * bootstrap classloader, use of the bootstrap classloader is recommended.</p>
313 *
314 * @param object The object to return a message instance of.
315 * @param messageName The logical name of the message to return an instance
316 * of.
317 * @param arguments Arguments to format the message instance with or
318 * {@code null}.
319 *
320 * @return An instance of the message named {@code messageName} of
321 * {@code object} formatted with {@code arguments}.
322 *
323 * @throws NullPointerException if {@code object} or {@code messageName} is
324 * {@code null}.
325 * @throws MissingImplementationException if no implementation is defined
326 * for {@code object}.
327 * @throws MissingMessageException if no message named
328 * {@code messageName} is defined for {@code object}.
329 * @throws ContainerError for unrecoverable container errors.
330 * @throws ContextError for unrecoverable context errors.
331 * @throws ModelError for unrecoverable model errors.
332 * @deprecated Replaced by {@link #getMessage(java.lang.Object, java.lang.String, java.util.Locale, java.lang.Object) }
333 * This method does not take information regarding the locale to use when
334 * formatting text.
335 */
336 String getMessage( Object object, String messageName, Object arguments );
337
338 /**
339 * Gets an instance of a message of an object for a given locale.
340 * <p>When creating objects, use of the classloader associated with the
341 * class of the given object, as returned by method
342 * {@link Class#getClassLoader()}, is recommended. Only if that method
343 * returns {@code null}, indicating the class has been loaded by the
344 * bootstrap classloader, use of the bootstrap classloader is recommended.</p>
345 *
346 * @param object The object to return a message instance of.
347 * @param messageName The logical name of the message to return an instance
348 * of.
349 * @param locale The locale of the message instance to return.
350 * @param arguments Arguments to format the message instance with or
351 * {@code null}.
352 *
353 * @return An instance of the message named {@code messageName} of
354 * {@code object} formatted with {@code arguments} for {@code locale}.
355 *
356 * @throws NullPointerException if {@code object}, {@code locale} or
357 * {@code messageName} is {@code null}.
358 * @throws MissingImplementationException if no implementation is defined
359 * for {@code object}.
360 * @throws MissingMessageException if no message named
361 * {@code messageName} is defined for {@code object}.
362 * @throws ContainerError for unrecoverable container errors.
363 * @throws ContextError for unrecoverable context errors.
364 * @throws ModelError for unrecoverable model errors.
365 */
366 String getMessage( Object object, String messageName, Locale locale,
367 Object arguments );
368
369 //---------------------------------------------------------------Container--
370 }