001 // SECTION-START[License Header]
002 /*
003 * Copyright (c) 2009 The JOMC Project
004 * Copyright (c) 2005 Christian Schulte <cs@jomc.org>
005 * All rights reserved.
006 *
007 * Redistribution and use in source and binary forms, with or without
008 * modification, are permitted provided that the following conditions
009 * are met:
010 *
011 * o Redistributions of source code must retain the above copyright
012 * notice, this list of conditions and the following disclaimer.
013 *
014 * o Redistributions in binary form must reproduce the above copyright
015 * notice, this list of conditions and the following disclaimer in
016 * the documentation and/or other materials provided with the
017 * distribution.
018 *
019 * THIS SOFTWARE IS PROVIDED BY THE JOMC PROJECT AND CONTRIBUTORS "AS IS"
020 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
021 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
022 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE JOMC PROJECT OR
023 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
024 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
025 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
026 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
027 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
028 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
029 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
030 *
031 * $Id: ObjectManager.java 751 2009-10-06 06:32:50Z schulte2005 $
032 *
033 */
034 // SECTION-END
035 package org.jomc;
036
037 import java.util.Locale;
038
039 // SECTION-START[Documentation]
040 /**
041 * Manages objects.
042 * <p>This specification declares a multiplicity of {@code One}.
043 * An application assembler is required to provide no more than one implementation of this specification (including none).
044 * Use of class {@link org.jomc.ObjectManager ObjectManager} is supported for getting that implementation.<pre>
045 * ObjectManager object = (ObjectManager) ObjectManagerFactory.getObjectManager().getObject( ObjectManager.class );
046 * </pre>
047 * </p>
048 *
049 * <p>This specification applies to {@code Singleton} scope. The same singleton object is returned whenever requested.</p>
050 *
051 * @author <a href="mailto:cs@jomc.org">Christian Schulte</a> 1.0
052 * @version $Id: ObjectManager.java 751 2009-10-06 06:32:50Z schulte2005 $
053 */
054 // SECTION-END
055 // SECTION-START[Annotations]
056 @javax.annotation.Generated( value = "org.jomc.tools.JavaSources",
057 comments = "See http://jomc.sourceforge.net/jomc/1.0-alpha-5/jomc-tools" )
058 // SECTION-END
059 public interface ObjectManager
060 {
061 // SECTION-START[Object Manager]
062
063 /**
064 * Gets an instance of an implementation of a specification.
065 * <p><b>Note</b><br/>
066 * Implementations must use the class loader associated with the given class as returned by method
067 * {@link Class#getClassLoader() specification.getClassLoader()} for loading classes. Only if that method returns
068 * {@code null}, indicating the class has been loaded by the bootstrap class loader, use of the bootstrap class
069 * loader is recommended.</p>
070 *
071 * @param specification The specification class to return an implementation instance of.
072 *
073 * @return An instance of an implementation of the specification class {@code specification} or {@code null} if
074 * no such instance is available.
075 *
076 * @throws NullPointerException if {@code specification} is {@code null}.
077 * @throws ObjectManagementException if getting the object fails.
078 */
079 Object getObject( Class specification )
080 throws NullPointerException, ObjectManagementException;
081
082 /**
083 * Gets an instance of an implementation of a specification.
084 * <p><b>Note</b><br/>
085 * Implementations must use the class loader associated with the given class as returned by method
086 * {@link Class#getClassLoader() specification.getClassLoader()} for loading classes. Only if that method returns
087 * {@code null}, indicating the class has been loaded by the bootstrap class loader, use of the bootstrap class
088 * loader is recommended.</p>
089 *
090 * @param specification The specification class to return an implementation instance of.
091 * @param implementationName The name of the implementation to return an instance of.
092 * @param <T> The type of the instance.
093 *
094 * @return An instance of the implementation named {@code implementationName} of the specification class
095 * {@code specification} or {@code null} if no such instance is available.
096 *
097 * @throws NullPointerException if {@code specification} or {@code implementationName} is {@code null}.
098 * @throws ObjectManagementException if getting the object fails.
099 */
100 <T> T getObject( Class<T> specification, String implementationName )
101 throws NullPointerException, ObjectManagementException;
102
103 /**
104 * Gets an instance of a dependency of an object.
105 * <p><b>Note</b><br/>
106 * Implementations must use the class loader associated with the class of the given object as returned by method
107 * {@link Class#getClassLoader() object.getClass().getClassLoader()} for loading classes. Only if that method
108 * returns {@code null}, indicating the class has been loaded by the bootstrap class loader, use of the bootstrap
109 * class loader is recommended.</p>
110 *
111 * @param object The object to return a dependency instance of.
112 * @param dependencyName The name of the dependency of {@code object} to return an instance of.
113 *
114 * @return An instance of the dependency named {@code dependencyName} of {@code object} or {@code null} if no such
115 * instance is available.
116 *
117 * @throws NullPointerException if {@code object} or {@code dependencyName} is {@code null}.
118 * @throws ObjectManagementException if getting the dependency instance fails.
119 */
120 Object getDependency( Object object, String dependencyName )
121 throws NullPointerException, ObjectManagementException;
122
123 /**
124 * Gets an instance of a property of an object.
125 * <p><b>Note</b><br/>
126 * Implementations must use the class loader associated with the class of the given object as returned by method
127 * {@link Class#getClassLoader() object.getClass().getClassLoader()} for loading classes. Only if that method
128 * returns {@code null}, indicating the class has been loaded by the bootstrap class loader, use of the bootstrap
129 * class loader is recommended.</p>
130 *
131 * @param object The object to return a property instance of.
132 * @param propertyName The name of the property of {@code object} to return an instance of.
133 *
134 * @return An instance of the property named {@code propertyName} of {@code object} or {@code null} if no such
135 * instance is available.
136 *
137 * @throws NullPointerException if {@code object} or {@code propertyName} is {@code null}.
138 * @throws ObjectManagementException if getting the property instance fails.
139 */
140 Object getProperty( Object object, String propertyName )
141 throws NullPointerException, ObjectManagementException;
142
143 /**
144 * Gets an instance of a message of an object.
145 * <p><b>Note</b><br/>
146 * Implementations must use the class loader associated with the class of the given object as returned by method
147 * {@link Class#getClassLoader() object.getClass().getClassLoader()} for loading classes. Only if that method
148 * returns {@code null}, indicating the class has been loaded by the bootstrap class loader, use of the bootstrap
149 * class loader is recommended.</p>
150 *
151 * @param object The object to return a message instance of.
152 * @param messageName The name of the message of {@code object} to return an instance of.
153 * @param locale The locale of the message instance to return.
154 * @param arguments Arguments to format the message instance with or {@code null}.
155 *
156 * @return An instance of the message named {@code messageName} of {@code object} formatted with {@code arguments}
157 * for {@code locale} or {@code null} if no such instance is available.
158 *
159 * @throws NullPointerException if {@code object}, {@code messageName} or {@code locale} is {@code null}.
160 * @throws ObjectManagementException if getting the message instance fails.
161 */
162 String getMessage( Object object, String messageName, Locale locale, Object arguments )
163 throws NullPointerException, ObjectManagementException;
164
165 // SECTION-END
166 }