001 /*
002 * jDTAUS Core API
003 * Copyright (c) 2005 Christian Schulte
004 *
005 * Christian Schulte, Haldener Strasse 72, 58095 Hagen, Germany
006 * <schulte2005@users.sourceforge.net> (+49 2331 3543887)
007 *
008 * This library is free software; you can redistribute it and/or
009 * modify it under the terms of the GNU Lesser General Public
010 * License as published by the Free Software Foundation; either
011 * version 2.1 of the License, or any later version.
012 *
013 * This library is distributed in the hope that it will be useful,
014 * but WITHOUT ANY WARRANTY; without even the implied warranty of
015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
016 * Lesser General Public License for more details.
017 *
018 * You should have received a copy of the GNU Lesser General Public
019 * License along with this library; if not, write to the Free Software
020 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
021 *
022 */
023 package org.jdtaus.core.container;
024
025 import java.util.Locale;
026
027 /**
028 * Object container.
029 *
030 * @author <a href="mailto:schulte2005@users.sourceforge.net">Christian Schulte</a>
031 * @version $Id: Container.java 8044 2009-07-02 01:29:05Z schulte2005 $
032 *
033 * @see ContainerFactory
034 */
035 public interface Container
036 {
037 //--Container---------------------------------------------------------------
038
039 /**
040 * Gets an instance of an implementation of a specification.
041 * <p>When creating objects, use of the classloader associated with the
042 * given class, as returned by method {@link Class#getClassLoader()}, is
043 * recommended. Only if that method returns {@code null}, indicating the
044 * class has been loaded by the bootstrap classloader, use of the bootstrap
045 * classloader is recommended.</p>
046 *
047 * @param specification The class of the specification to return an
048 * implementation instance of.
049 * @param implementationName The logical name of the implementation to
050 * return an instance of.
051 *
052 * @return An instance of an implementation as specified by the
053 * specification defined for class {@code specification}.
054 *
055 * @throws NullPointerException if {@code specification} or
056 * {@code implementationName} is {@code null}.
057 * @throws MissingSpecificationException if no specification is defined
058 * for {@code specification}.
059 * @throws MissingImplementationException if no implementation named
060 * {@code implementationName} is defined for the specification identified
061 * by {@code specification}.
062 * @throws org.jdtaus.core.container.InstantiationException if creating
063 * an instance of the implementation fails.
064 * @throws ContainerError for unrecoverable container errors.
065 * @throws ContextError for unrecoverable context errors.
066 * @throws ModelError for unrecoverable model errors.
067 * @deprecated Renamed to {@link #getObject(java.lang.Class, java.lang.String) }.
068 */
069 Object getImplementation( Class specification, String implementationName );
070
071 /**
072 * Gets an instance of an implementation of a dependency.
073 * <p>When creating objects, use of the classloader associated with the
074 * given class, as returned by method {@link Class#getClassLoader()}, is
075 * recommended. Only if that method returns {@code null}, indicating the
076 * class has been loaded by the bootstrap classloader, use of the bootstrap
077 * classloader is recommended.</p>
078 *
079 * @param implementation The class of the implementation to return an
080 * instance of a dependency of.
081 * @param dependencyName The logical name of the dependency to return an
082 * instance of.
083 *
084 * @return An instance of the implementation of the dependency named
085 * {@code dependencyName} for {@code implementation}.
086 *
087 * @throws NullPointerException if {@code implementation} or
088 * {@code dependencyName} is {@code null}.
089 * @throws MissingImplementationException if no implementation is defined
090 * for {@code implementation}.
091 * @throws MissingDependencyException if no dependency named
092 * {@code dependencyName} is defined for the implementation identified by
093 * {@code implementation}.
094 * @throws org.jdtaus.core.container.InstantiationException if creating
095 * an instance of the dependency fails.
096 * @throws ContainerError for unrecoverable container errors.
097 * @throws ContextError for unrecoverable context errors.
098 * @throws ModelError for unrecoverable model errors.
099 * @deprecated Replaced by {@link #getDependency(java.lang.Object, java.lang.String)}.
100 * This method does not take an argument providing information regarding
101 * the identity of the object to return a dependency of.
102 */
103 Object getDependency( Class implementation, String dependencyName );
104
105 /**
106 * Gets an instance of an implementation of a specification.
107 * <p>The object to return is resolved based on the multiplicity of the
108 * specification defined for the specification identified by the given
109 * identifier. For a multiplicity equal to
110 * {@link Specification#MULTIPLICITY_ONE}, the returned object will be an
111 * instance of the class of that specification. For a multiplicity equal to
112 * {@link Specification#MULTIPLICITY_MANY}, the returned object will be a
113 * one-dimensional array of instances of the class of that specification.</p>
114 *
115 * @param specificationIdentifier The identifier of the specification to
116 * return an implementation instance of.
117 *
118 * @return An instance of an implementation as specified by the
119 * specification identified by {@code specificationIdentifier}.
120 *
121 * @throws NullPointerException if {@code specificationIdentifier} is
122 * {@code null}.
123 * @throws MissingSpecificationException if no specification is defined
124 * for {@code specificationIdentifier}.
125 * @throws MultiplicityConstraintException if the multiplicity of the
126 * specification equals {@code MULTIPLICITY_ONE} and the model holds either
127 * no or more than one implementation.
128 * @throws org.jdtaus.core.container.InstantiationException if creating an
129 * implementation instance fails.
130 * @throws ContainerError for unrecoverable container errors.
131 * @throws ContextError for unrecoverable context errors.
132 * @throws ModelError for unrecoverable model errors.
133 * @deprecated Replaced by {@link #getObject(java.lang.Class) }. This method
134 * does not take an argument providing information regarding the classloader
135 * in use. It is recommended to use the classloader which loaded the
136 * implementation of this interface as returned by method
137 * {@link Class#getClassLoader()}. Only if that method returns {@code null},
138 * use of the bootstrap classloader is recommended.
139 */
140 Object getObject( String specificationIdentifier );
141
142 /**
143 * Gets an instance of an implementation of a specification.
144 *
145 * @param specificationIdentifier The identifier of the specification to
146 * return an implementation instance of.
147 * @param implementationName The logical name of the implementation to
148 * return an instance of.
149 *
150 * @return An instance of the implementation named
151 * {@code implementationName} as specified by the specification identified
152 * by {@code specificationIdentifier}.
153 *
154 * @throws NullPointerException if {@code specificationIdentifier} or
155 * {@code implementationName} is {@code null}.
156 * @throws MissingSpecificationException if no specification is defined
157 * for {@code specificationIdentifier}.
158 * @throws MissingImplementationException if no implementation named
159 * {@code implementationName} is defined for the specification identified by
160 * {@code specificationIdentifier}.
161 * @throws org.jdtaus.core.container.InstantiationException if creating an
162 * implementation instance fails.
163 * @throws ContainerError for unrecoverable container errors.
164 * @throws ContextError for unrecoverable context errors.
165 * @throws ModelError for unrecoverable model errors.
166 * @deprecated Replaced by {@link #getObject(java.lang.Class, java.lang.String) }.
167 * This method does not take an argument providing information regarding the
168 * classloader in use. It is recommended to use the classloader which loaded
169 * the implementation of this interface as returned by method
170 * {@link Class#getClassLoader()}. Only if that method returns {@code null},
171 * use of the bootstrap classloader is recommended.
172 */
173 Object getObject( String specificationIdentifier,
174 String implementationName );
175
176 /**
177 * Gets an instance of an implementation of a specification.
178 * <p>The object to return is resolved based on the multiplicity of the
179 * specification defined for the given class. For a multiplicity equal to
180 * {@link Specification#MULTIPLICITY_ONE}, the returned object will be an
181 * instance of the given class. For a multiplicity equal to
182 * {@link Specification#MULTIPLICITY_MANY}, the returned object will be a
183 * one-dimensional array of instances of the given class.</p>
184 * <p>When creating objects, use of the classloader associated with the
185 * given class, as returned by method {@link Class#getClassLoader()}, is
186 * recommended. Only if that method returns {@code null}, indicating the
187 * class has been loaded by the bootstrap classloader, use of the bootstrap
188 * classloader is recommended.</p>
189 *
190 * @param specification The class of the specification to return an
191 * implementation instance of.
192 *
193 * @return An instance of an implementation as specified by the
194 * specification defined for class {@code specification}.
195 *
196 * @throws NullPointerException if {@code specification} is {@code null}.
197 * @throws MissingSpecificationException if no specification is defined
198 * for {@code specification}.
199 * @throws MultiplicityConstraintException if the multiplicity of the
200 * specification defined for {@code specification} equals
201 * {@code MULTIPLICITY_ONE} and the model holds either no or more than one
202 * implementation.
203 * @throws org.jdtaus.core.container.InstantiationException if creating an
204 * implementation instance fails.
205 * @throws ContainerError for unrecoverable container errors.
206 * @throws ContextError for unrecoverable context errors.
207 * @throws ModelError for unrecoverable model errors.
208 */
209 Object getObject( Class specification );
210
211 /**
212 * Gets an instance of an implementation of a specification.
213 * <p>When creating objects, use of the classloader associated with the
214 * given class, as returned by method {@link Class#getClassLoader()}, is
215 * recommended. Only if that method returns {@code null}, indicating the
216 * class has been loaded by the bootstrap classloader, use of the bootstrap
217 * classloader is recommended.</p>
218 *
219 * @param specification The class of the specification to return an
220 * implementation instance of.
221 * @param implementationName The logical name of the implementation to
222 * return an instance of.
223 *
224 * @return An instance of the implementation named
225 * {@code implementationName} as specified by the specification defined for
226 * class {@code specification}.
227 *
228 * @throws NullPointerException if {@code specification} or
229 * {@code implementationName} is {@code null}.
230 * @throws MissingSpecificationException if no specification is defined
231 * for {@code specification}.
232 * @throws MissingImplementationException if no implementation named
233 * {@code implementationName} is defined for the specification for
234 * {@code specification}.
235 * @throws org.jdtaus.core.container.InstantiationException if creating an
236 * implementation instance fails.
237 * @throws ContainerError for unrecoverable container errors.
238 * @throws ContextError for unrecoverable context errors.
239 * @throws ModelError for unrecoverable model errors.
240 */
241 Object getObject( Class specification, String implementationName );
242
243 /**
244 * Gets an instance of a dependency of an object.
245 * <p>The object to return is resolved based on the multiplicity of the
246 * specification defined for the dependency. For a multiplicity equal to
247 * {@link Specification#MULTIPLICITY_ONE}, the returned object will be an
248 * instance of the class of that specification. For a multiplicity equal to
249 * {@link Specification#MULTIPLICITY_MANY}, the returned object will be a
250 * one-dimensional array of instances of the class of that specification.</p>
251 * <p>When creating objects, use of the classloader associated with the
252 * class of the given object, as returned by method
253 * {@link Class#getClassLoader()}, is recommended. Only if that method
254 * returns {@code null}, indicating the class has been loaded by the
255 * bootstrap classloader, use of the bootstrap classloader is recommended.</p>
256 *
257 * @param object The object to return a dependency instance of.
258 * @param dependencyName The logical name of the dependency to return an
259 * instance of.
260 *
261 * @return An instance of the dependency named {@code dependencyName} of
262 * {@code object}.
263 *
264 * @throws NullPointerException if {@code object} or {@code dependencyName}
265 * is {@code null}.
266 * @throws MissingImplementationException if no implementation is defined
267 * for {@code object}.
268 * @throws MissingDependencyException if no dependency named
269 * {@code dependencyName} is defined for {@code object}.
270 * @throws MultiplicityConstraintException if the specification of the
271 * dependency has a multiplicity of {@code MULTIPLICITY_ONE} without any
272 * implementation being available.
273 * @throws org.jdtaus.core.container.InstantiationException if creating an
274 * instance of the dependency fails.
275 * @throws ContainerError for unrecoverable container errors.
276 * @throws ContextError for unrecoverable context errors.
277 * @throws ModelError for unrecoverable model errors.
278 */
279 Object getDependency( Object object, String dependencyName );
280
281 /**
282 * Gets an instance of a property of an object.
283 * <p>When creating objects, use of the classloader associated with the
284 * class of the given object, as returned by method
285 * {@link Class#getClassLoader()}, is recommended. Only if that method
286 * returns {@code null}, indicating the class has been loaded by the
287 * bootstrap classloader, use of the bootstrap classloader is recommended.</p>
288 *
289 * @param object The object to return a property instance of.
290 * @param propertyName The logical name of the property to return an
291 * instance of.
292 *
293 * @return An instance of the property named {@code propertyName} of
294 * {@code object}.
295 *
296 * @throws NullPointerException if {@code object} or {@code propertyName} is
297 * {@code null}.
298 * @throws MissingImplementationException if no implementation is defined
299 * for {@code object}.
300 * @throws MissingPropertyException if no property named
301 * {@code propertyName} is defined for {@code object}.
302 * @throws ContainerError for unrecoverable container errors.
303 * @throws ContextError for unrecoverable context errors.
304 * @throws ModelError for unrecoverable model errors.
305 */
306 Object getProperty( Object object, String propertyName );
307
308 /**
309 * Gets an instance of a message of an object.
310 * <p>When creating objects, use of the classloader associated with the
311 * class of the given object, as returned by method
312 * {@link Class#getClassLoader()}, is recommended. Only if that method
313 * returns {@code null}, indicating the class has been loaded by the
314 * bootstrap classloader, use of the bootstrap classloader is recommended.</p>
315 *
316 * @param object The object to return a message instance of.
317 * @param messageName The logical name of the message to return an instance
318 * of.
319 * @param arguments Arguments to format the message instance with or
320 * {@code null}.
321 *
322 * @return An instance of the message named {@code messageName} of
323 * {@code object} formatted with {@code arguments}.
324 *
325 * @throws NullPointerException if {@code object} or {@code messageName} is
326 * {@code null}.
327 * @throws MissingImplementationException if no implementation is defined
328 * for {@code object}.
329 * @throws MissingMessageException if no message named
330 * {@code messageName} is defined for {@code object}.
331 * @throws ContainerError for unrecoverable container errors.
332 * @throws ContextError for unrecoverable context errors.
333 * @throws ModelError for unrecoverable model errors.
334 * @deprecated Replaced by {@link #getMessage(java.lang.Object, java.lang.String, java.util.Locale, java.lang.Object) }
335 * This method does not take information regarding the locale to use when
336 * formatting text.
337 */
338 String getMessage( Object object, String messageName, Object arguments );
339
340 /**
341 * Gets an instance of a message of an object for a given locale.
342 * <p>When creating objects, use of the classloader associated with the
343 * class of the given object, as returned by method
344 * {@link Class#getClassLoader()}, is recommended. Only if that method
345 * returns {@code null}, indicating the class has been loaded by the
346 * bootstrap classloader, use of the bootstrap classloader is recommended.</p>
347 *
348 * @param object The object to return a message instance of.
349 * @param messageName The logical name of the message to return an instance
350 * of.
351 * @param locale The locale of the message instance to return.
352 * @param arguments Arguments to format the message instance with or
353 * {@code null}.
354 *
355 * @return An instance of the message named {@code messageName} of
356 * {@code object} formatted with {@code arguments} for {@code locale}.
357 *
358 * @throws NullPointerException if {@code object}, {@code locale} or
359 * {@code messageName} is {@code null}.
360 * @throws MissingImplementationException if no implementation is defined
361 * for {@code object}.
362 * @throws MissingMessageException if no message named
363 * {@code messageName} is defined for {@code object}.
364 * @throws ContainerError for unrecoverable container errors.
365 * @throws ContextError for unrecoverable context errors.
366 * @throws ModelError for unrecoverable model errors.
367 */
368 String getMessage( Object object, String messageName, Locale locale,
369 Object arguments );
370
371 //---------------------------------------------------------------Container--
372 }