This is an automated email from the ASF dual-hosted git repository. dblevins pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/tomee.git
The following commit(s) were added to refs/heads/master by this push: new a8211f1 Create README_es.adoc new 87cbe4c Merge pull request #381 from fost14oct/TOMEE-2459 a8211f1 is described below commit a8211f1747a4511ca2fea868efabaf07c4139e94 Author: fost14oct <36649784+fost14...@users.noreply.github.com> AuthorDate: Sat Jan 26 14:39:04 2019 -0600 Create README_es.adoc --- examples/access-timeout-meta/README_es.adoc | 287 ++++++++++++++++++++++++++++ 1 file changed, 287 insertions(+) diff --git a/examples/access-timeout-meta/README_es.adoc b/examples/access-timeout-meta/README_es.adoc new file mode 100644 index 0000000..8b7dac9 --- /dev/null +++ b/examples/access-timeout-meta/README_es.adoc @@ -0,0 +1,287 @@ += @AccessTimeout la forma Meta-Annotation +:index-group: Meta-Annotations +:jbake-type: page +:jbake-status: status=published +ifdef::env-github[] +:tip-caption: :bulb: +:note-caption: :information_source: +:important-caption: :heavy_exclamation_mark: +:caution-caption: :fire: +:stylesheet: ../github-stylesheet.css +endif::[] + +== 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. + +TIP: 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 [.small]#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. + + +[source,java,numbered] +---- +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` + + +[source,java,numbered] +---- +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` + +[source,java,numbered] +---- +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. + +[source,java,numbered] +---- +@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 [.small]#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 [.small]#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 [.small]#lo mejor de ambos mundos# + +Afortunadamente, meta-annotations son recursivas. Puedes hacer un poco de ambas. + +[source,java,numbered] +---- +@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 + +[source,java,numbered] +---- +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 + +[source,java,numbered] +---- +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 + } + +} +----