001    /*****************************************************************************
002     * Copyright (c) PicoContainer Organization. All rights reserved.            *
003     * ------------------------------------------------------------------------- *
004     * The software in this package is published under the terms of the BSD      *
005     * style license a copy of which has been included with this distribution in *
006     * the LICENSE.txt file.                                                     *
007     *                                                                           *
008     * Original code by Joerg Schaible                                           *
009     *****************************************************************************/
010    
011    package org.picocontainer.defaults;
012    
013    /**
014     * Interface for a guard implementation looking after cyclic dependencies.
015     * 
016     * @author Jörg Schaible
017     * @since 1.1
018     */
019    public interface CyclicDependencyGuard {
020    
021        /**
022         * Derive from this class and implement this function with the functionality 
023         * to observe for a dependency cycle.
024         * 
025         * @return a value, if the functionality result in an expression, 
026         *      otherwise just return <code>null</code>
027         */
028        public Object run();
029        
030        /**
031         * Call the observing function. The provided guard will hold the {@link Boolean} value.
032         * If the guard is already <code>Boolean.TRUE</code> a {@link CyclicDependencyException} 
033         * will be  thrown.
034         * 
035         * @param stackFrame the current stack frame
036         * @return the result of the <code>run</code> method
037         */
038        public Object observe(Class stackFrame);
039    }