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 {
}
@AccessTimeout la forma Meta-Annotation
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.
@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 javax.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 javax.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 javax.ejb.AccessTimeout;
import javax.ejb.Asynchronous;
import javax.ejb.Lock;
import javax.ejb.Singleton;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.Future;
import java.util.concurrent.TimeUnit;
import static javax.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 javax.ejb.Asynchronous;
import javax.ejb.Lock;
import javax.ejb.Singleton;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.Future;
import static javax.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
}
}