001/*
002 * Copyright 2002-2015 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.beans.factory.config;
018
019import org.springframework.lang.Nullable;
020
021/**
022 * Interface that defines a registry for shared bean instances.
023 * Can be implemented by {@link org.springframework.beans.factory.BeanFactory}
024 * implementations in order to expose their singleton management facility
025 * in a uniform manner.
026 *
027 * <p>The {@link ConfigurableBeanFactory} interface extends this interface.
028 *
029 * @author Juergen Hoeller
030 * @since 2.0
031 * @see ConfigurableBeanFactory
032 * @see org.springframework.beans.factory.support.DefaultSingletonBeanRegistry
033 * @see org.springframework.beans.factory.support.AbstractBeanFactory
034 */
035public interface SingletonBeanRegistry {
036
037        /**
038         * Register the given existing object as singleton in the bean registry,
039         * under the given bean name.
040         * <p>The given instance is supposed to be fully initialized; the registry
041         * will not perform any initialization callbacks (in particular, it won't
042         * call InitializingBean's {@code afterPropertiesSet} method).
043         * The given instance will not receive any destruction callbacks
044         * (like DisposableBean's {@code destroy} method) either.
045         * <p>When running within a full BeanFactory: <b>Register a bean definition
046         * instead of an existing instance if your bean is supposed to receive
047         * initialization and/or destruction callbacks.</b>
048         * <p>Typically invoked during registry configuration, but can also be used
049         * for runtime registration of singletons. As a consequence, a registry
050         * implementation should synchronize singleton access; it will have to do
051         * this anyway if it supports a BeanFactory's lazy initialization of singletons.
052         * @param beanName the name of the bean
053         * @param singletonObject the existing singleton object
054         * @see org.springframework.beans.factory.InitializingBean#afterPropertiesSet
055         * @see org.springframework.beans.factory.DisposableBean#destroy
056         * @see org.springframework.beans.factory.support.BeanDefinitionRegistry#registerBeanDefinition
057         */
058        void registerSingleton(String beanName, Object singletonObject);
059
060        /**
061         * Return the (raw) singleton object registered under the given name.
062         * <p>Only checks already instantiated singletons; does not return an Object
063         * for singleton bean definitions which have not been instantiated yet.
064         * <p>The main purpose of this method is to access manually registered singletons
065         * (see {@link #registerSingleton}). Can also be used to access a singleton
066         * defined by a bean definition that already been created, in a raw fashion.
067         * <p><b>NOTE:</b> This lookup method is not aware of FactoryBean prefixes or aliases.
068         * You need to resolve the canonical bean name first before obtaining the singleton instance.
069         * @param beanName the name of the bean to look for
070         * @return the registered singleton object, or {@code null} if none found
071         * @see ConfigurableListableBeanFactory#getBeanDefinition
072         */
073        @Nullable
074        Object getSingleton(String beanName);
075
076        /**
077         * Check if this registry contains a singleton instance with the given name.
078         * <p>Only checks already instantiated singletons; does not return {@code true}
079         * for singleton bean definitions which have not been instantiated yet.
080         * <p>The main purpose of this method is to check manually registered singletons
081         * (see {@link #registerSingleton}). Can also be used to check whether a
082         * singleton defined by a bean definition has already been created.
083         * <p>To check whether a bean factory contains a bean definition with a given name,
084         * use ListableBeanFactory's {@code containsBeanDefinition}. Calling both
085         * {@code containsBeanDefinition} and {@code containsSingleton} answers
086         * whether a specific bean factory contains a local bean instance with the given name.
087         * <p>Use BeanFactory's {@code containsBean} for general checks whether the
088         * factory knows about a bean with a given name (whether manually registered singleton
089         * instance or created by bean definition), also checking ancestor factories.
090         * <p><b>NOTE:</b> This lookup method is not aware of FactoryBean prefixes or aliases.
091         * You need to resolve the canonical bean name first before checking the singleton status.
092         * @param beanName the name of the bean to look for
093         * @return if this bean factory contains a singleton instance with the given name
094         * @see #registerSingleton
095         * @see org.springframework.beans.factory.ListableBeanFactory#containsBeanDefinition
096         * @see org.springframework.beans.factory.BeanFactory#containsBean
097         */
098        boolean containsSingleton(String beanName);
099
100        /**
101         * Return the names of singleton beans registered in this registry.
102         * <p>Only checks already instantiated singletons; does not return names
103         * for singleton bean definitions which have not been instantiated yet.
104         * <p>The main purpose of this method is to check manually registered singletons
105         * (see {@link #registerSingleton}). Can also be used to check which singletons
106         * defined by a bean definition have already been created.
107         * @return the list of names as a String array (never {@code null})
108         * @see #registerSingleton
109         * @see org.springframework.beans.factory.support.BeanDefinitionRegistry#getBeanDefinitionNames
110         * @see org.springframework.beans.factory.ListableBeanFactory#getBeanDefinitionNames
111         */
112        String[] getSingletonNames();
113
114        /**
115         * Return the number of singleton beans registered in this registry.
116         * <p>Only checks already instantiated singletons; does not count
117         * singleton bean definitions which have not been instantiated yet.
118         * <p>The main purpose of this method is to check manually registered singletons
119         * (see {@link #registerSingleton}). Can also be used to count the number of
120         * singletons defined by a bean definition that have already been created.
121         * @return the number of singleton beans
122         * @see #registerSingleton
123         * @see org.springframework.beans.factory.support.BeanDefinitionRegistry#getBeanDefinitionCount
124         * @see org.springframework.beans.factory.ListableBeanFactory#getBeanDefinitionCount
125         */
126        int getSingletonCount();
127
128        /**
129         * Return the singleton mutex used by this registry (for external collaborators).
130         * @return the mutex object (never {@code null})
131         * @since 4.2
132         */
133        Object getSingletonMutex();
134
135}