io.quarkus.qute.api.CheckedTemplate Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of quarkus-qute Show documentation

Offer templating support for web, email, etc in a build time, type-safe way

There is a newer version: 3.17.0.CR1

package io.quarkus.qute.api;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import io.quarkus.qute.TemplateInstance;

/**
 * If you place this annotation on a class, all its native static methods will be used to declare
 * templates and the list of parameters they require.
 * 
 * The name of a method and the base path are used to locate the template contents.
 * By default, the base path is derived from the annotation target:
 * 

 * If this is placed on a static nested class of an enclosing class with a simple name X, a
 * native static method of the name foo will refer to a template at the path X/foo
 * (template file extensions are
 * not part of the method name) relative to the templates root.
 * If this is placed on a top-level class, a native static method of the name foo will refer to a
 * template at the path foo (template file extensions are
 * not part of the method name) at the toplevel of the templates root.
 * 
 * The base path can be also specified via {@link #basePath()}.
 * 
 * Each parameter of the native static will be used to validate the template at build time, to
 * make sure that those parameters are used properly in a type-safe manner. The return type of each
 * native static method should be {@link TemplateInstance}.
 * 

 * Example:
 * 

 * 
 * 
 * @Path("item")
 * public class ItemResource {
 * 
 *     @CheckedTemplate
 *     static class Templates {
 *         // defines a template at ItemResource/item, taking an Item parameter named item
 *         static native TemplateInstance item(Item item);
 *     }
 * 
 *     @GET
 *     @Path("{id}")
 *     @Produces(MediaType.TEXT_HTML)
 *     public TemplateInstance get(@PathParam("id") Integer id) {
 *         // instantiate that template and pass it the required template parameter
 *         return Templates.item(service.findItem(id));
 *     }
 * }
 * 
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface CheckedTemplate {

    /**
     * Constant value for {@link #basePath()} indicating that the default strategy should be used.
     */
    String DEFAULTED = "<>";

    /**
     * Example:
     * 
     *      * @Path("item")
     * public class ItemResource {
     * 
     *     @CheckedTemplate(basePath = "items_v1")
     *     static class Templates {
     *         // defines a template at items_v1/item
     *         static native TemplateInstance item(Item item);
     * 
     *         // defines a template at items_v1/allItems
     *         static native TemplateInstance allItems(List<Item> items);
     *     }
     * }
     * 
     * 
     * @return the base path relative to the templates root
     */
    String basePath() default DEFAULTED;

}