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 4268 2012-02-16 23:14:52Z schulte2005 $
032     *
033     */
034    // </editor-fold>
035    // SECTION-END
036    package org.jomc;
037    
038    import 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.2", comments = "See http://jomc.sourceforge.net/jomc/1.2/jomc-tools-1.2" )
062    // </editor-fold>
063    // SECTION-END
064    public 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    }