Package io.quarkus.qute

Annotation Interface 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 Details

    • 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.
      See Also:

    • ELEMENT_NAME

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

    • 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.
      See Also:

    • 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.
      See Also:

  • Element Details

    • 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

    • defaultName

      String defaultName
      The value may be one of the following: ELEMENT_NAME, HYPHENATED_ELEMENT_NAME and UNDERSCORED_ELEMENT_NAME.
      Returns:
      the default name
      Default:
      "<<element name>>"

    • 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:
      Default:
      false