001/*
002 * Copyright 2002-2013 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.access;
018
019import org.springframework.beans.factory.BeanFactory;
020
021/**
022 * Used to track a reference to a {@link BeanFactory} obtained through
023 * a {@link BeanFactoryLocator}.
024 *
025 * <p>It is safe to call {@link #release()} multiple times, but
026 * {@link #getFactory()} must not be called after calling release.
027 *
028 * @author Colin Sampaleanu
029 * @see BeanFactoryLocator
030 * @see org.springframework.context.access.ContextBeanFactoryReference
031 */
032public interface BeanFactoryReference {
033
034        /**
035         * Return the {@link BeanFactory} instance held by this reference.
036         * @throws IllegalStateException if invoked after {@code release()} has been called
037         */
038        BeanFactory getFactory();
039
040        /**
041         * Indicate that the {@link BeanFactory} instance referred to by this object is not
042         * needed any longer by the client code which obtained the {@link BeanFactoryReference}.
043         * <p>Depending on the actual implementation of {@link BeanFactoryLocator}, and
044         * the actual type of {@code BeanFactory}, this may possibly not actually
045         * do anything; alternately in the case of a 'closeable' {@code BeanFactory}
046         * or derived class (such as {@link org.springframework.context.ApplicationContext})
047         * may 'close' it, or may 'close' it once no more references remain.
048         * <p>In an EJB usage scenario this would normally be called from
049         * {@code ejbRemove()} and {@code ejbPassivate()}.
050         * <p>This is safe to call multiple times.
051         * @see BeanFactoryLocator
052         * @see org.springframework.context.access.ContextBeanFactoryReference
053         * @see org.springframework.context.ConfigurableApplicationContext#close()
054         */
055        void release();
056
057}