001// SECTION-START[License Header]
002// <editor-fold defaultstate="collapsed" desc=" Generated License ">
003/*
004 *   Java Object Management and Configuration
005 *   Copyright (C) Christian Schulte, 2005-206
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 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
021 *   INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
022 *   AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
023 *   THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY DIRECT, INDIRECT,
024 *   INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
025 *   NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
026 *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
027 *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
028 *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
029 *   THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
030 *
031 *   $JOMC: ObjectManager.java 4588 2012-06-03 06:01:30Z schulte2005 $
032 *
033 */
034// </editor-fold>
035// SECTION-END
036package org.jomc;
037
038import java.util.Locale;
039
040// SECTION-START[Documentation]
041// <editor-fold defaultstate="collapsed" desc=" Generated Documentation ">
042/**
043 * Manages objects.
044 *
045 * <dl>
046 *   <dt><b>Identifier:</b></dt><dd>org.jomc.ObjectManager</dd>
047 *   <dt><b>Multiplicity:</b></dt><dd>One</dd>
048 *   <dt><b>Scope:</b></dt><dd>Singleton</dd>
049 * </dl>
050 *
051 * @author <a href="mailto:schulte2005@users.sourceforge.net">Christian Schulte</a> 1.0
052 * @version 1.0
053 * @see org.jomc.ObjectManager#getObject(java.lang.Class) getObject(ObjectManager.class)
054 * @see org.jomc.ObjectManager#getObject(java.lang.Class,java.lang.String) getObject(ObjectManager.class, "<i>implementation name</i>")
055 * @see org.jomc.ObjectManagerFactory
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.SourceFileProcessor 1.3", comments = "See http://jomc.sourceforge.net/jomc/1.3/jomc-tools-1.3" )
062// </editor-fold>
063// SECTION-END
064public interface ObjectManager
065{
066    // SECTION-START[ObjectManager]
067
068    /**
069     * Gets an instance of an implementation of a specification.
070     * <p><b>Note:</b><br/>
071     * Implementations must use the class loader associated with the given class as returned by method
072     * {@link Class#getClassLoader() specification.getClassLoader()} for loading classes. Only if that method returns
073     * {@code null}, indicating the class has been loaded by the bootstrap class loader, use of the bootstrap class
074     * loader is recommended.</p>
075     *
076     * @param <T> The type of the instance.
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 no
080     * such instance is available.
081     *
082     * @throws NullPointerException if {@code specification} is {@code null}.
083     * @throws ObjectManagementException if getting the object fails.
084     */
085    <T> T getObject( Class<T> 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 <T> The type of the instance.
097     * @param specification The specification class to return an implementation instance of.
098     * @param implementationName The name of the implementation to return an instance of.
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.
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}