Preloader image

Introducción

Cualquier anotación que reciba parámetros se puede beneficiar de las meta-annotations. Aquí obsvervamos cómo @AccessTimeout puede ser más facíl de comprender y administrar mediante meta-annotatios. Usaremos [access-timeout](../access-timeout/README.html) como nuestro ejemplo de caso de uso.

El valor de los parámetros suministrador a @AccessTimeout tienen un efecto dramático en lo que la anotación realmente hace. Además, @AccessTimeout tiene uno de esos diseños donde -1 y 0 tienen un significado totalmente diferente. Uno quiere decir "espera por siempre", el otro "nunca esperes". Solo algunos con suerte pueden recordar cual es cual. Para el resto de nosotros es una fuente constante de bugs.

Meta-Annotations al rescate!

Creando Meta-Annotations

Con respecto a las mejores prácticas, pondremos nuestras meta-annotations en el paquete llamado api, para este ejempo que nos da org.superbiz.accesstimeout.api. El paquete org.superbiz.api también funcionará.

La idea básica es tener un paquete donde anotaciones "aprovadas" sean usadas y prohibr uso de versiones non-meta de anotaciones. Toda la configuración estará centralizada en el paquete api y cambios en los valores de tiempo de espera estarán localizados en ese paquete y automaticamente reflejados a través de toda la aplicación.

Un efecto secundario interesante de este enfoque es que si el paquete api donde las definiciones de meta-annotation existe ubicado en un jar separado, entonces efectivamente alguien puede cambiar toda la configuración de una aplicación simplemente remplazando el jar api.

@Metatype La Meta-Annotation" root"

Así como con todo el uso meta-annotation, primero debes de crear tu propia meta-annotation "root". Esto es tan facil como crear una anotación llamada Metatype que esta anotada con esta misma anotación y tiene un ElementType.ANNOTATION_TYPE como su objetivo.

package org.superbiz.accesstimeout.api;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Metatype
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Metatype {
}

@AwaitNever

Cuando la anotacion @AccessTimeout tiene el valor de 0 que tiene la implicación que nunca debe de esperar para acceder al bean. Si el bean esta ocupado, el que lo llama inmediatamente recibirá una ConcurrentAccessException. Esto es difícil de recordar y definitivamente no es auto-documentado para aquellos que nunca conocieron los detalles.

Para crear una version de la meta-annotation @AccessTimeout(0) nosotros simplemente debemos pensar un buen nombre de anotación, crear esa anotación y anotarla con ambas @AccessTimeout y @Metatype

package org.superbiz.accesstimeout.api;

import jakarta.ejb.AccessTimeout;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Metatype
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)

@AccessTimeout(0)
public @interface AwaitNever {
}

@AwaitForever

Así como 0 tiene su significado especial como "nunca esperes" , el valor de -1 quiere decir "espera por siempre."

Mientras seamos exigentes, lo que podemos hacer con las meta-anotaciones, técincamente "esperar por siempre" no es la mejor descripción. Actualmete los métodos de javax.util.concurrent APIs usan "await" en vez de "wait". Un (wait) probablemente implica un comando de espera, que en este caso no es , el otro (await) más bien quiere decir que la espera es posible pero no certera. Así que usaremos "await" en el nombre de nuestras anotaciones.

Nosotros hacemos nuestra propia @AwaitForever y la anotamos con @AccessTimeout(0) y @Metatype

package org.superbiz.accesstimeout.api;

import jakarta.ejb.AccessTimeout;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Metatype
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)

@AccessTimeout(-1)
public @interface AwaitForever {
}

@AwaitBriefly

Tanto los valores de -1 y 0 a @AccessTimeout no incluyen todo el alcance de la anotación. Aqui es donde tú puedes especificar el máximo de minutos , segundos, milisegundos,etc. donde uno podrá esperar acceder a la instancia del bean.

@Metatype
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.TYPE})

@AccessTimeout(value = 5, unit = TimeUnit.SECONDS)
public @interface AwaitBriefly {
}

Configuración vs Operación

Una vez que hayas creado un par de meta-annotations y la diversión se vuelva vulgar, empiezas a preguntarte cual será la mejor forma de beneficiarte de las meta-annotations.

Realmente tienes que empezar a pensar como quieres hacer uso de la meta-annotation y ponerte el sombrero de diseñador. El dilema fundamental es configuración vs operación y la respuesta es subjetiva; cuanta flexibilidad quieres diseñar en tu aplicación y en donde?

Nombres de configuración describiendo la configuración

El enfoque más sencillo es llamar a tus meta-annotations después de la configuración que encapsulan. Hemos seguido este formato hasta ahora con @AwaitNever y @AwaitForever para que sea claro el contenido de cada meta-annotation (@AccessTimeout(-1) y @AccessTimeout(0) respectivamente).

Los contras de este enfoque es que tu querrás cambiar la configuración de esta aplicación con tan solo cambiar las meta-annotations — este es uno de los grandes beneficios de meta-annotations — pero esto podría cambiar el significado de la anotación. Ciertamente , la anotación @AwaitNever no puede tener otro valor más que 0 si es que esta a la altura del nombre.

Nombres de operación describiendo el código

El enfoque alterno es llamar las meta-annotations después de operaciones a las cuales aplica. En breve para describir , para describir el código en si y no la configuración. Así que, nombres como @OrderCheckTimeout ó @TwitterUpdateTimeout. Estos nombres son prueba de cambio de configuración. Estos no cambiarán si la configuración cambia y de hecho, pueden facilitar control de buscardor-de-grano sobre la configuación de la aplicación.

Los contras de este enfoque es que requiere mucha más deliberación y consideración, sin mencionar más anotaciones. Tus habilidades como arquitecto, diseñador y hablilidad para pensar como administrador serán puestas a prueba. Tienes que ser bueno para ponerte el sombrero dev-opts.

Pragmatismo lo mejor de ambos mundos

Afortunadamente, meta-annotations son recursivas. Puedes hacer un poco de ambas.

@Metatype
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)

@AwaitBriefly
public @interface TwitterUpdateTimeout {
}

Claro todavía tienes que ser muy deliberado en como usar las anotaciones. Cuando se use una "configuracion" llamada meta-annotation en código puede ser usada para decirte a tí mismo, "No quiere reconfigurarlo después". Si eso no se siente bien, haz un esfuerzo extra en crear una operación llamada anotación y úsala en el código.

Aplicando las Meta-Annotations

Juntando todo , tal vez así es como deberíamos aplicar nuestras meta-annotations para el ejemplo [access-timeout](../access-timeout/README.html).

Antes

package org.superbiz.accesstimeout;

import jakarta.ejb.AccessTimeout;
import jakarta.ejb.Asynchronous;
import jakarta.ejb.Lock;
import jakarta.ejb.Singleton;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.Future;
import java.util.concurrent.TimeUnit;

import static jakarta.ejb.LockType.WRITE;

/**
    * @version $Revision$ $Date$
    */
@Singleton
@Lock(WRITE)
public class BusyBee {

    @Asynchronous
    public Future stayBusy(CountDownLatch ready) {
        ready.countDown();

        try {
            new CountDownLatch(1).await();
        } catch (InterruptedException e) {
            Thread.interrupted();
        }

        return null;
    }

    @AccessTimeout(0)
    public void doItNow() {
        // do something
    }

    @AccessTimeout(value = 5, unit = TimeUnit.SECONDS)
    public void doItSoon() {
        // do something
    }

    @AccessTimeout(-1)
    public void justDoIt() {
        // do something
    }

}

Después

package org.superbiz.accesstimeout;

import org.superbiz.accesstimeout.api.AwaitBriefly;
import org.superbiz.accesstimeout.api.AwaitForever;
import org.superbiz.accesstimeout.api.AwaitNever;

import jakarta.ejb.Asynchronous;
import jakarta.ejb.Lock;
import jakarta.ejb.Singleton;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.Future;

import static jakarta.ejb.LockType.WRITE;

/**
    * @version $Revision$ $Date$
    */
@Singleton
@Lock(WRITE)
public class BusyBee {

    @Asynchronous
    public Future stayBusy(CountDownLatch ready) {
        ready.countDown();

        try {
            new CountDownLatch(1).await();
        } catch (InterruptedException e) {
            Thread.interrupted();
        }

        return null;
    }

    @AwaitNever
    public void doItNow() {
        // do something
    }

    @AwaitBriefly
    public void doItSoon() {
        // do something
    }

    @AwaitForever
    public void justDoIt() {
        // do something
    }

}