com.blackbuild.klum.ast.util.layer3.annotations.Cluster Maven / Gradle / Ivy
/*
* The MIT License (MIT)
*
* Copyright (c) 2015-2024 Stephan Pauxberger
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*/
package com.blackbuild.klum.ast.util.layer3.annotations;
import org.codehaus.groovy.transform.GroovyASTTransformationClass;
import java.lang.annotation.*;
/**
* Automatically implements the annotated method by providing access to all matching fields,
* possibly filtered by the given annotation. This is usually use to provide the API layer of
* a three layer model.
*
* For example:
*
*
* abstract class Database {
* {@literal @}Cluster abstract {@literal Map} getUsers
* }
*
* 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 {@link RetentionPolicy#RUNTIME}.
*
*
* abstract class Database {
* {@literal @}Cluster abstract {@literal Map} getUsers
* {@literal @}Cluster(Required) abstract {@literal Map} getRequiredUsers
* }
*
* class MyApplicationDatabase extends Database {
* {@literal @}Required User ddl
* {@literal @}Required User dml
* User monitoring
* }
*
*
* In that example, getUsers() still returns all user fields, while
* getRequiredUsers() only returns 'ddl' and 'dml'.
*
* 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
*
*/
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@GroovyASTTransformationClass("com.blackbuild.klum.ast.util.layer3.ClusterTransformation")
public @interface Cluster {
/**
* If set, filters the results by the given annotation.
* @return The annotation to filter on.
*/
Class value() default Undefined.class;
/**
* If set to false, null values are not included in the result.
* @return To return or ignore null values.
*/
boolean includeNulls() default true;
@interface Undefined {}
}