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.net.URL;
021import java.util.Set;
022
023import org.apache.camel.StaticService;
024
025/**
026 * A resolver that can find classes based on package scanning.
027 *
028 * @see PackageScanResourceResolver
029 */
030public interface PackageScanClassResolver extends StaticService {
031
032    /**
033     * Gets the ClassLoader instances that should be used when scanning for classes.
034     * <p/>
035     * This implementation will return a new unmodifiable set containing the classloaders.
036     * Use the {@link #addClassLoader(ClassLoader)} method if you want to add new classloaders
037     * to the class loaders list.
038     *
039     * @return the class loaders to use
040     */
041    Set<ClassLoader> getClassLoaders();
042
043    /**
044     * Adds the class loader to the existing loaders
045     *
046     * @param classLoader the loader to add
047     */
048    void addClassLoader(ClassLoader classLoader);
049
050    /**
051     * Attempts to discover classes that are annotated with to the annotation.
052     *
053     * @param annotation   the annotation that should be present on matching classes
054     * @param packageNames one or more package names to scan (including subpackages) for classes
055     * @return the classes found, returns an empty set if none found
056     */
057    Set<Class<?>> findAnnotated(Class<? extends Annotation> annotation, String... packageNames);
058
059    /**
060     * Attempts to discover classes that are annotated with to the annotation.
061     *
062     * @param annotations   the annotations that should be present (any of them) on matching classes
063     * @param packageNames one or more package names to scan (including subpackages) for classes
064     * @return the classes found, returns an empty set if none found
065     */
066    Set<Class<?>> findAnnotated(Set<Class<? extends Annotation>> annotations, String... packageNames);
067
068    /**
069     * Attempts to discover classes that are assignable to the type provided. In
070     * the case that an interface is provided this method will collect
071     * implementations. In the case of a non-interface class, subclasses will be
072     * collected.
073     *
074     * @param parent       the class of interface to find subclasses or implementations of
075     * @param packageNames one or more package names to scan (including subpackages) for classes
076     * @return the classes found, returns an empty set if none found
077     */
078    Set<Class<?>> findImplementations(Class<?> parent, String... packageNames);
079
080    /**
081     * Attempts to discover classes filter by the provided filter
082     *
083     * @param filter  filter to filter desired classes.
084     * @param packageNames one or more package names to scan (including subpackages) for classes
085     * @return the classes found, returns an empty set if none found
086     */
087    Set<Class<?>> findByFilter(PackageScanFilter filter, String... packageNames);
088    
089    /**
090     * Add a filter that will be applied to all scan operations
091     * 
092     * @param filter filter to filter desired classes in all scan operations
093     */
094    void addFilter(PackageScanFilter filter);
095
096    /**
097     * Removes the filter
098     *
099     * @param filter filter to filter desired classes in all scan operations
100     */
101    void removeFilter(PackageScanFilter filter);
102
103    /**
104     * To specify a set of accepted schemas to use for loading resources as URL connections
105     * (besides http and https schemas)
106     */
107    void setAcceptableSchemes(String schemes);
108
109    /**
110     * Clears the internal cache.
111     */
112    void clearCache();
113}