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