Package com.blackbuild.klum.ast.layer3

Annotation Interface Cluster

@Target({METHOD,FIELD,TYPE,PACKAGE}) @Retention(RUNTIME) @Documented @Inherited public @interface Cluster
Automatically converts the annotated field into a getter method providing access to all matching fields, possibly filtered by the given annotation.

if placed on a (potentially abstract) method, that method is replaced with such a getter.

This is usually used to provide the API layer of a three layer model.

For example:


 abstract class Database {
     @Cluster Map<String, User> users
 }

 class MyApplicationDatabase extends Database {
     User ddl
     User dml
     User monitoring
 }

Will implement the getUsers() method to return a Map with the keys being 'ddl', 'dml' and 'monitoring' and the values containing the actual values of those fields, including null values.

Note that in addition to abstract methods, methods with an empty body or a body containing just 'null' or an empty Map can also be annotated. This prevents IDEs from complaining if using API layer and schema layer in the same project.

Using the value field, an annotation can be provided. In that case, only the fields of the class that have this annotation are returned. Note that the given annotation must have RetentionPolicy.RUNTIME.


 abstract class Database {
     @Cluster Map<String, User> users
     @Cluster(Required) Map<String, User> requiredUsers
 }

 class MyApplicationDatabase extends Database {
     @Required User ddl
     @Required User dml
     User monitoring
 }

In that example, getUsers() still returns all user fields, while getRequiredUsers() only returns 'ddl' and 'dml'.

Cluster Factories

In addition to the getter, a cluster factory is created (much like a collection factory), containing only the dsl methods of the respective cluster field

So with the above example, the following is correct: 

 MyApplicationDatabase.Create.With {
     users {
         ddl {...}
         dml {...}
         monitoring {...}
     }
 }

Using the bounded() attribute, the setter methods can be restricted to be only available inside a factory (note that this is done by making the methods protected, not completely removing them).

The annotation can also be used for methods return Maps of Collections. If the (subclass of) Collection is generic, the result is a map of the matching Collections. If the Collection does not use a generic parameter, all collections would be returned.

The annotation can also be set on classes or packages. If so, the bounded member is set for all cluster fields of a a class/all classes of its package. Other members are not allowed on classes/packages.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static @interface 
    Cluster.Undefined
     

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    boolean
    bounded
    If set to true, the setter methods for matching fields are only created inside a named factory.
    boolean
    includeNulls
    If set to false, null values are not included in the result.
    Class<? extends Annotation>
    value
    If set, filters the results by the given annotation.

  • Element Details

    • value

      Class<? extends Annotation> value
      If set, filters the results by the given annotation.
      Returns:
      The annotation to filter on.
      Default:
      com.blackbuild.klum.ast.layer3.Cluster.Undefined.class

    • includeNulls

      boolean includeNulls
      If set to false, null values are not included in the result.
      Returns:
      To return or ignore null values.
      Default:
      true

    • bounded

      boolean bounded
      If set to true, the setter methods for matching fields are only created inside a named factory.
      Returns:
      Whether the setter methods are only created inside a factory.
      Default:
      false