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    }