uk.autores.handling.ResourceFiles Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of annotations Show documentation
Annotation driven library for handling embedded resources
There is a newer version: 11.0.35-beta
// Copyright 2023 https://github.com/autores-uk/autores/blob/main/LICENSE.txt
// SPDX-License-Identifier: Apache-2.0
package uk.autores.handling;

import uk.autores.Processing;
import uk.autores.naming.Namer;
import uk.autores.repeat.RepeatableResources;

import javax.annotation.processing.Filer;
import javax.tools.JavaFileManager;
import java.lang.annotation.*;

/**
 * 
 *     Indicates resources that are to be processed at compile time.
 * 
 * {@code @ResourceFiles("some-resource.txt")}
 * 
 *     The compiler must be able to load referenced resources using
 *     {@link Filer#getResource(JavaFileManager.Location, CharSequence, CharSequence)}.
 * 
 * 
 *     It is recommended that resources be placed in a bundled directory path equivalent to the type or package.
 *     For example, annotated class foo.bar.Baz can reference the relative resource
 *     foo/bar/X.txt with the string "X.txt".
 * 
 * 
 *     Absolute paths like "/META-INF/resources/X.txt must be start with a forward slash.
 * 
 * 
 *     As a minimum this annotation can be used to verify a resource exists without the need for unit tests.
 *     Set {@link #handler()} for other behaviour.
 * 
 * 
 *     Custom generation or validation can be provided by implementing a {@link Handler}.
 *     Alternative naming strategies can be set by providing a {@link Namer} via {@link #processing()}.
 *     The compiler must be able to load and instantiate any value set in {@link #handler()}.
 *     This typically means compiling the code in a separate project to the one where they are used.
 * 
 */
@Target({ElementType.PACKAGE, ElementType.TYPE})
@Retention(RetentionPolicy.SOURCE)
@Repeatable(RepeatableResources.class)
public @interface ResourceFiles {

    /**
     * Defines the resource files to be processed.
     * In an Apache Maven project these will likely be placed in the src/main/resources directory.
     *
     * @return the resources to handle
     */
    String[] value();

    /**
     * Enables non-default resource handling.
     *
     * @return the Handler for these resources
     * @see Handler Handler for provided implementations
     */
    Class handler() default AssertResourceExists.class;

    /**
     * Common processing instructions
     *
     * @return processing instructions
     */
    Processing processing() default @Processing(namer = Namer.class);

    /**
     * Some implementations of {@link Handler} support configuration.
     *
     * @return configured options
     * @see Handler#config()
     * @see Sets
     */
    Cfg[] config() default {};

    /**
     * Configuration option.
     *
     * @see Handler#config()
     * @see ConfigDef
     */
    @interface Cfg {
        /**
         * Key.
         *
         * @return name of config option
         * @see ConfigDef#key()
         */
        String key();

        /**
         * Value.
         *
         * @return config option value
         * @see ConfigDef#isValid(String)
         */
        String value();
    }
}