001/*
002 * Licensed under the Apache License, Version 2.0 (the "License");
003 * you may not use this file except in compliance with the License.
004 * You may obtain a copy of the License at
005 *
006 * http://www.apache.org/licenses/LICENSE-2.0
007 *
008 * Unless required by applicable law or agreed to in writing, software
009 * distributed under the License is distributed on an "AS IS" BASIS,
010 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
011 * See the License for the specific language governing permissions and
012 * limitations under the License.
013 */
014package org.atteo.classindex;
015
016import java.lang.annotation.Documented;
017import java.lang.annotation.ElementType;
018import java.lang.annotation.Retention;
019import java.lang.annotation.RetentionPolicy;
020import java.lang.annotation.Target;
021import java.util.ServiceLoader;
022
023import javax.xml.bind.JAXBContext;
024
025import org.atteo.classindex.processor.ClassIndexProcessor;
026
027/**
028 * Index all subclasses of the annotated class or package.
029 *
030 * <p>
031 * During compilation {@link ClassIndexProcessor} creates a resource files listing all classes
032 * extending annotated class or located inside annotated package.
033 * </p>
034 * <p>
035 * You can retrieve the list at runtime using either {@link ClassIndex#getSubclasses(Class)}
036 * or {@link ClassIndex#getPackageClasses(String)}.
037 * </p>
038 * <p>
039 * For subclasses of the annotated class the resource file name is compatible with
040 * what {@link ServiceLoader} expects. So if all the subclasses have a zero-argument constructor
041 * you can use {@link ServiceLoader}. For subclasses of given package index file is named
042 * "jaxb.index", it is located inside the package folder and it's format is compatible with
043 * what {@link JAXBContext#newInstance(String) } expects.
044 * </p>
045 */
046@Documented
047@Retention(RetentionPolicy.RUNTIME)
048@Target({ElementType.TYPE, ElementType.PACKAGE})
049public @interface IndexSubclasses {
050    /**
051     * Specifies whether to store Javadoc for runtime retrieval.
052     *
053     * <p>
054     * You can retrieve the stored Javadoc summary using {@link ClassIndex#getClassSummary(Class)}.
055     * </p>
056     */
057    boolean storeJavadoc() default false;
058}