001/**
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.camel.spi;
018
019import java.lang.annotation.Annotation;
020import java.util.Set;
021
022/**
023 * A resolver that can find resources based on package scanning.
024 */
025public interface PackageScanClassResolver {
026
027    /**
028     * Sets the ClassLoader instances that should be used when scanning for
029     * classes. If none is set then the context classloader will be used.
030     *
031     * @param classLoaders loaders to use when scanning for classes
032     * @deprecated will be removed in Camel 3.0. Use {@link #addClassLoader(ClassLoader)} instead.
033     */
034    @Deprecated
035    void setClassLoaders(Set<ClassLoader> classLoaders);
036
037    /**
038     * Gets the ClassLoader instances that should be used when scanning for classes.
039     * <p/>
040     * This implementation will return a new unmodifiable set containing the classloaders.
041     * Use the {@link #addClassLoader(ClassLoader)} method if you want to add new classloaders
042     * to the class loaders list.
043     *
044     * @return the class loaders to use
045     */
046    Set<ClassLoader> getClassLoaders();
047
048    /**
049     * Adds the class loader to the existing loaders
050     *
051     * @param classLoader the loader to add
052     */
053    void addClassLoader(ClassLoader classLoader);
054
055    /**
056     * Attempts to discover classes that are annotated with to the annotation.
057     *
058     * @param annotation   the annotation that should be present on matching classes
059     * @param packageNames one or more package names to scan (including subpackages) for classes
060     * @return the classes found, returns an empty set if none found
061     */
062    Set<Class<?>> findAnnotated(Class<? extends Annotation> annotation, String... packageNames);
063
064    /**
065     * Attempts to discover classes that are annotated with to the annotation.
066     *
067     * @param annotations   the annotations that should be present (any of them) on matching classes
068     * @param packageNames one or more package names to scan (including subpackages) for classes
069     * @return the classes found, returns an empty set if none found
070     */
071    Set<Class<?>> findAnnotated(Set<Class<? extends Annotation>> annotations, String... packageNames);
072
073    /**
074     * Attempts to discover classes that are assignable to the type provided. In
075     * the case that an interface is provided this method will collect
076     * implementations. In the case of a non-interface class, subclasses will be
077     * collected.
078     *
079     * @param parent       the class of interface to find subclasses or implementations of
080     * @param packageNames one or more package names to scan (including subpackages) for classes
081     * @return the classes found, returns an empty set if none found
082     */
083    Set<Class<?>> findImplementations(Class<?> parent, String... packageNames);
084
085    /**
086     * Attempts to discover classes filter by the provided filter
087     *
088     * @param filter  filter to filter desired classes.
089     * @param packageNames one or more package names to scan (including subpackages) for classes
090     * @return the classes found, returns an empty set if none found
091     */
092    Set<Class<?>> findByFilter(PackageScanFilter filter, String... packageNames);
093    
094    /**
095     * Add a filter that will be applied to all scan operations
096     * 
097     * @param filter filter to filter desired classes in all scan operations
098     */
099    void addFilter(PackageScanFilter filter);
100
101    /**
102     * Removes the filter
103     *
104     * @param filter filter to filter desired classes in all scan operations
105     */
106    void removeFilter(PackageScanFilter filter);
107}