Package io.quarkus.qute

Annotation Type CheckedTemplate

  • @Documented
@Retention(RUNTIME)
@Target(TYPE)
public @interface CheckedTemplate

    IMPORTANT: This annotation only works in a fully integrated environment; such as a Quarkus application.

    It aims to configure type-safe templates. You can annotate a class or a Java record that implements TemplateInstance.

    @CheckedTemplate on a class

    If you place this annotation on a class, then all its static native 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 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 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));
     }
 }

    @CheckedTemplate on a template record

    If you place this annotation on a Java record that implements TemplateInstance, then attributes of this annotation are used to configure the non-default values of the type-safe template denoted by this record.

    Type-safe fragments

    By default, a native static method or a template record with the name that contains a dollar sign $ denotes a fragment of a type-safe template. It's possible to ignore the fragments and effectively disable this feature via ignoreFragments().

    The name of the fragment is derived from the annotated element name. The part before the last occurence of a dollar sign $ is the method name of the related type-safe template. The part after the last occurence of a dollar sign is the fragment identifier - the strategy defined by the relevant defaultName() is used.

    Parameters of the annotated element are validated. The required names and types are derived from the relevant fragment template. 

     @CheckedTemplate
 class Templates {

     // defines a type-safe template
     static native TemplateInstance items(List<Item> items);

     // defines a fragment of Templates#items() with identifier "item"
     @CheckedFragment
     static native TemplateInstance items$item(Item item);
 }

    • Field Detail

      • DEFAULTED

        static final String DEFAULTED
        Constant value for basePath() indicating that the default strategy should be used, i.e. the simple name of the declaring class for a nested static class or an empty string for a top level class.

      • ELEMENT_NAME

        static final String ELEMENT_NAME
        Constant value for defaultName() indicating that the method name should be used as-is.

      • HYPHENATED_ELEMENT_NAME

        static final String HYPHENATED_ELEMENT_NAME
        Constant value for defaultName() indicating that the annotated element's name should be de-camel-cased and hyphenated, and then used.

      • UNDERSCORED_ELEMENT_NAME

        static final String UNDERSCORED_ELEMENT_NAME
        Constant value fordefaultName() indicating that the annotated element's name should be de-camel-cased and parts separated by underscores, and then used.

    • Element Detail

      • basePath

        String basePath
        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);
     }
 }
        Returns:
        the base path relative to the templates root
        Default:
        "<<defaulted>>"

      • requireTypeSafeExpressions

        boolean requireTypeSafeExpressions
        If set to true then the defined templates can only contain type-safe expressions.
        Default:
        true

      • ignoreFragments

        boolean ignoreFragments
        By default, a native static method with the name that contains a dollar sign $ denotes a method that represents a fragment of a type-safe template. It's possible to ignore the fragments and effectively disable this feature.
        Returns:
        true if no method should be interpreted as a fragment, false otherwise
        See Also:
        Template.getFragment(String)
        Default:
        false