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 *****************************************************************************/
008package 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 */
018public 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}