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    package org.picocontainer;
009    
010    /**
011     * Interface realizing a visitor pattern for {@link PicoContainer} as described in the GoF.
012     * The visitor should visit the container, its children, all registered {@link ComponentAdapter}
013     * instances and all instantiated components.
014     * 
015     * @author Aslak Hellesøy
016     * @author Jörg Schaible
017     */
018    public interface PicoVisitor {
019            
020            
021            /**
022             * Constant that indicates that the traversal should continue after the 
023             * visit*() method has been called.
024             */
025            boolean CONTINUE_TRAVERSAL = true;
026            
027            /**
028             * Constant that indicates that the traversal should abort after the 
029             * visit*() method has been called.
030             */
031            boolean ABORT_TRAVERSAL = false;
032            
033        /**
034         * Entry point for the PicoVisitor traversal. The given node is the first object, that is 
035         * asked for acceptance. Only objects of type {@link PicoContainer}, {@link ComponentAdapter},
036         * or {@link Parameter} are valid.
037         * 
038         * @param node the start node of the traversal.
039         * @return a visitor-specific value.
040         * @throws IllegalArgumentException in case of an argument of invalid type. 
041         */
042        Object traverse(Object node);
043    
044        /**
045         * Visit a {@link PicoContainer} that has to accept the visitor.
046         * 
047         * @param pico the visited container.
048         * @return CONTINUE_TRAVERSAL if the traversal should continue.  
049         * Any visitor callback that returns ABORT_TRAVERSAL indicates
050         * the desire to abort any further traversal.
051         */
052        boolean visitContainer(PicoContainer pico);
053    
054        /**
055         * Visit a {@link ComponentAdapter} that has to accept the visitor.
056         * 
057         * @param componentAdapter the visited ComponentAdapter.
058         */
059        void visitComponentAdapter(ComponentAdapter<?> componentAdapter);
060    
061        /**
062         * Visit a {@link ComponentAdapter} that has to accept the visitor.
063         *
064         * @param componentAdapter the visited ComponentAdapter.
065         */
066        void visitComponentFactory(ComponentFactory componentFactory);
067    
068        /**
069         * Visit a {@link Parameter} that has to accept the visitor.
070         * 
071         * @param parameter the visited Parameter.
072         */
073        void visitParameter(Parameter parameter);
074    }