https://github.com/smallrye/smallrye-safer-annotations
Safer annotation constraints
https://github.com/smallrye/smallrye-safer-annotations
Last synced: 6 months ago
JSON representation
Safer annotation constraints
- Host: GitHub
- URL: https://github.com/smallrye/smallrye-safer-annotations
- Owner: smallrye
- License: apache-2.0
- Created: 2021-02-18T15:43:29.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2023-04-05T12:58:16.000Z (almost 3 years ago)
- Last Synced: 2023-07-28T18:09:35.515Z (over 2 years ago)
- Language: Java
- Size: 53.7 KB
- Stars: 3
- Watchers: 3
- Forks: 2
- Open Issues: 3
-
Metadata Files:
- Readme: README.MD
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
Safer Annotations helps you define constraints on your annotations that are richer than the
stock Java constraints (type, method, field…).
# Usage, for library authors
Import the Safer Annotations module in your `pom.xml`:
```xml
io.smallrye
smallrye-safer-annotations
1.0.2
```
And start annotating your library annotations with safer constraints:
```java
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
// Restrict the type signature of target methods
@TargetMethod(
/* set of allowed return types */
returnTypes = { void.class, Response.class, UniResponse.class, OptionalResponse.class },
/* set of allowed parameter types */
parameterTypes = { ContainerRequestContext.class, ContainerResponseContext.class, ResourceInfo.class, SimpleResourceInfo.class, ThrowableSubtype.class}
)
public @interface ServerResponseFilter {
}
// Allows us to pass generic types to the @TargetMethod annotation
class UniResponse extends TargetMethod.GenericType> {
}
class OptionalResponse extends TargetMethod.GenericType> {
}
// Allows us to declare parameter types that can be any subtype of Throwable
class ThrowableSubtype extends TargetMethod.Subtype {
}
```
# Usage, for your library's users
Tell your build tool to invoke our compiler plugin:
```xml
maven-compiler-plugin
${compiler-plugin.version}
io.smallrye
smallrye-safer-annotations
1.0.2
```
Now your users can get compile-time errors if they misplace your annotations:
```java
@ServerResponseFilter
// ERROR: Invalid parameter type: must be one of: […]
public void myFilter(NonSupportedType something){
}
```
# Supported annotation constraints
- `@TargetAccessor`: annotated method must be a Java Bean getter or setter
- `@TargetMethod`: annotated method must have a compatible method signature
# Declaring or overriding annotation constraints on external annotations
If you cannot annotate the contained annotation directly, because it is external to your project,
you can declare a `DefinitionOverride` implementation and place the constaints on it instead.
First, create a `META-INF/services/io.smallrye.safer.annotations.DefinitionOverride` file containing
the list of override class names:
```
com.example.foo.MyOverride
```
And place your constraints on your override class:
```java
package com.example.foo;
import io.smallrye.safer.annotations.DefinitionOverride;
import io.smallrye.safer.annotations.OverrideTarget;
import io.smallrye.safer.annotations.TargetMethod;
// Designate which external annotation we are targeting
@OverrideTarget(ServerExceptionMapper.class)
// Restrict the type signature of target methods
@TargetMethod(
/* set of allowed return types */
returnTypes = { void.class, Response.class, UniResponse.class, OptionalResponse.class },
/* set of allowed parameter types */
parameterTypes = { ContainerRequestContext.class, ContainerResponseContext.class, ResourceInfo.class, SimpleResourceInfo.class, ThrowableSubtype.class}
)
public class MyOverride implements DefinitionOverride {
}
```