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     * Gets the ClassLoader instances that should be used when scanning for classes.
029     * <p/>
030     * This implementation will return a new unmodifiable set containing the classloaders.
031     * Use the {@link #addClassLoader(ClassLoader)} method if you want to add new classloaders
032     * to the class loaders list.
033     *
034     * @return the class loaders to use
035     */
036    Set<ClassLoader> getClassLoaders();
037
038    /**
039     * Adds the class loader to the existing loaders
040     *
041     * @param classLoader the loader to add
042     */
043    void addClassLoader(ClassLoader classLoader);
044
045    /**
046     * Attempts to discover classes that are annotated with to the annotation.
047     *
048     * @param annotation   the annotation that should be present on matching classes
049     * @param packageNames one or more package names to scan (including subpackages) for classes
050     * @return the classes found, returns an empty set if none found
051     */
052    Set<Class<?>> findAnnotated(Class<? extends Annotation> annotation, String... packageNames);
053
054    /**
055     * Attempts to discover classes that are annotated with to the annotation.
056     *
057     * @param annotations   the annotations that should be present (any of them) on matching classes
058     * @param packageNames one or more package names to scan (including subpackages) for classes
059     * @return the classes found, returns an empty set if none found
060     */
061    Set<Class<?>> findAnnotated(Set<Class<? extends Annotation>> annotations, String... packageNames);
062
063    /**
064     * Attempts to discover classes that are assignable to the type provided. In
065     * the case that an interface is provided this method will collect
066     * implementations. In the case of a non-interface class, subclasses will be
067     * collected.
068     *
069     * @param parent       the class of interface to find subclasses or implementations of
070     * @param packageNames one or more package names to scan (including subpackages) for classes
071     * @return the classes found, returns an empty set if none found
072     */
073    Set<Class<?>> findImplementations(Class<?> parent, String... packageNames);
074
075    /**
076     * Attempts to discover classes filter by the provided filter
077     *
078     * @param filter  filter to filter desired classes.
079     * @param packageNames one or more package names to scan (including subpackages) for classes
080     * @return the classes found, returns an empty set if none found
081     */
082    Set<Class<?>> findByFilter(PackageScanFilter filter, String... packageNames);
083    
084    /**
085     * Add a filter that will be applied to all scan operations
086     * 
087     * @param filter filter to filter desired classes in all scan operations
088     */
089    void addFilter(PackageScanFilter filter);
090
091    /**
092     * Removes the filter
093     *
094     * @param filter filter to filter desired classes in all scan operations
095     */
096    void removeFilter(PackageScanFilter filter);
097}