001/* 002 * jDTAUS Core API 003 * Copyright (C) 2005 Christian Schulte 004 * <cs@schulte.it> 005 * 006 * This library is free software; you can redistribute it and/or 007 * modify it under the terms of the GNU Lesser General Public 008 * License as published by the Free Software Foundation; either 009 * version 2.1 of the License, or any later version. 010 * 011 * This library is distributed in the hope that it will be useful, 012 * but WITHOUT ANY WARRANTY; without even the implied warranty of 013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014 * Lesser General Public License for more details. 015 * 016 * You should have received a copy of the GNU Lesser General Public 017 * License along with this library; if not, write to the Free Software 018 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA 019 * 020 */ 021package org.jdtaus.core.container; 022 023import java.util.Locale; 024 025/** 026 * Object container. 027 * 028 * @author <a href="mailto:cs@schulte.it">Christian Schulte</a> 029 * @version $JDTAUS: Container.java 8641 2012-09-27 06:45:17Z schulte $ 030 * 031 * @see ContainerFactory 032 */ 033public interface Container 034{ 035 //--Container--------------------------------------------------------------- 036 037 /** 038 * Gets an instance of an implementation of a specification. 039 * <p>When creating objects, use of the classloader associated with the 040 * given class, as returned by method {@link Class#getClassLoader()}, is 041 * recommended. Only if that method returns {@code null}, indicating the 042 * class has been loaded by the bootstrap classloader, use of the bootstrap 043 * classloader is recommended.</p> 044 * 045 * @param specification The class of the specification to return an 046 * implementation instance of. 047 * @param implementationName The logical name of the implementation to 048 * return an instance of. 049 * 050 * @return An instance of an implementation as specified by the 051 * specification defined for class {@code specification}. 052 * 053 * @throws NullPointerException if {@code specification} or 054 * {@code implementationName} is {@code null}. 055 * @throws MissingSpecificationException if no specification is defined 056 * for {@code specification}. 057 * @throws MissingImplementationException if no implementation named 058 * {@code implementationName} is defined for the specification identified 059 * by {@code specification}. 060 * @throws org.jdtaus.core.container.InstantiationException if creating 061 * an instance of the implementation fails. 062 * @throws ContainerError for unrecoverable container errors. 063 * @throws ContextError for unrecoverable context errors. 064 * @throws ModelError for unrecoverable model errors. 065 * @deprecated Renamed to {@link #getObject(java.lang.Class, java.lang.String) }. 066 */ 067 Object getImplementation( Class specification, String implementationName ); 068 069 /** 070 * Gets an instance of an implementation of a dependency. 071 * <p>When creating objects, use of the classloader associated with the 072 * given class, as returned by method {@link Class#getClassLoader()}, is 073 * recommended. Only if that method returns {@code null}, indicating the 074 * class has been loaded by the bootstrap classloader, use of the bootstrap 075 * classloader is recommended.</p> 076 * 077 * @param implementation The class of the implementation to return an 078 * instance of a dependency of. 079 * @param dependencyName The logical name of the dependency to return an 080 * instance of. 081 * 082 * @return An instance of the implementation of the dependency named 083 * {@code dependencyName} for {@code implementation}. 084 * 085 * @throws NullPointerException if {@code implementation} or 086 * {@code dependencyName} is {@code null}. 087 * @throws MissingImplementationException if no implementation is defined 088 * for {@code implementation}. 089 * @throws MissingDependencyException if no dependency named 090 * {@code dependencyName} is defined for the implementation identified by 091 * {@code implementation}. 092 * @throws org.jdtaus.core.container.InstantiationException if creating 093 * an instance of the dependency fails. 094 * @throws ContainerError for unrecoverable container errors. 095 * @throws ContextError for unrecoverable context errors. 096 * @throws ModelError for unrecoverable model errors. 097 * @deprecated Replaced by {@link #getDependency(java.lang.Object, java.lang.String)}. 098 * This method does not take an argument providing information regarding 099 * 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}