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