EJB3 w Poznaniu i Chapter 10 - Metadata Annotations - koniec lektury EJB3 Simplified

Veni, vidi, vici! Poznań rozkopany, padało, więc nie było co podziwiać. Dobrze, że frekwencja dopisała (około 15-20 osób). Prezentacja EJB3 trwała 3 godziny i pozwoliła mi na poznanie kolejnych udoskonaleń EJB3 w praktyce. Ekipa tak się rozgrzała na koniec (zaraz po tym, kiedy się wyspali, kiedy ja opowiadałem), że padały pomysły utworzenia aplikacji tak, że ostatecznie dotknęliśmy @Entity i @PersistenceUnit i przykład się rozwalił ;-) W trakcie podróży doczytałem o wyjątkach aplikacyjnych i systemowych, więc pojawiły się kolejne 2 slajdy. Wydaje mi się, że wypadło nieźle. Coś wspominali o kolejnych wojażach, ale to na razie odłożymy - czas zabrać się za EJB Core Contracts and Requirements (w skrócie EJB3 Core).

Zanim zabiorę się za EJB3 Core, relacja z lektury EJB3 Simplified i jej ostatniego rozdziału Chapter 10 Metadata Annotations.

Patrząc na merytoryczną stronę dokumentu, rozdział 10 jest rozdziałem ostatnim, zamykającym uproszczony opis zmian w EJB3 (następujące po nim rozdziały to bibliografia - Chapter 11 Related Documents - oraz historia zmian - Appendix A Revision History). Mimo, że występuje jako ostatni, zawarte w nim informacje dotyczą bodaj najbardziej rewolucyjnych zmian w specyfikacji EJB3 - annotacji. Pojawiły się one już wcześniej przy opisie poszczególnych typów komponentów (SLSB, SFSB i MDB), jednak w tym rozdziale znajdziemy opis nie tylko tych należących do pakietu javax.ejb, ale również javax.interceptor, javax.annotation i javax.annotation.security (nie znajdziemy tutaj jednak annotacji związanych z Java Persistence API - javax.persistence). Na uwagę może również zwrócić ilość stron rozdziału, aż 10, co ustawia go na I miejscu pod względem objętości.

UWAGA 1: Wszystkie annotacje oznaczone są z Retention=RUNTIME, a więc są dostępne dla mechanizmu refleksji podczas instalacji i uruchomienia komponentów.

UWAGA 2: Elementy value annotacji nie muszą być poprzedzone nazwą parametru value i bezpośrednio definiuje się wartość.

Rozdział rozpoczyna się przedstawieniem annotacji wyznaczających typy komponentów.

Wypadałoby stworzyć tabelę dla uproszczenia prezentacji annotacji - nazwa annotacji, metoda/klasa, parametry, domyślna wartość, znaczenie. Może jednak później ;-)

Annotacje związane z bezstanowym komponentem sesyjnym (ang. SLSB - stateless session bean)

@Stateless - określenie klasy jako bezstanowy komponent sesyjny. Atrybuty:

• name - ejb-name dla komponentu (domyślnie niekwalifikowana nazwa klasy, tj. nazwa bez pakietu)
• mappedName - specyficzna dla serwera nazwa, do której należy dowiązać komponent (globalna nazwa JNDI)
• description - opis komponentu
  

Annotacje związane ze stanowym komponentem sesyjnym (ang. SFSB - stateful session bean)

@Stateful - określenie klasy jako stanowy komponent sesyjny. Atrybuty:

• name - ejb-name dla komponentu (domyślnie niekwalifikowana nazwa klasy, tj. nazwa bez pakietu)
• mappedName - specyficzna dla serwera nazwa, do której należy dowiązać komponent (globalna nazwa JNDI)
• description - opis komponentu
  

@Init - przypisanie metody w SFSB jako odpowiadającej metodzie create<METODA> w interfejsie EJBHome i EJBLocalHome, dla klientów korzystających z wywołań EJB 2.1. Zwracana wartość musi być void, a parametry muszą odpowiadać parametrom związanej metody create<METODA>.
Określenie metody Init jest jedynie wymagane dla komponentów SFSB, które dostęne są dla klientów EJB 2.1 poprzez interfejsy oznaczone @RemoteHome lub @LocalHome.
Atrybuty:

• value - używana przy SFSB dla określenia pojedyńczej metody, z którą annotacja jest związana, kiedy interfejs domowy posiada więcej niż jedną metodę create<METODA>.

@Remove - metoda usuwająca komponent z systemu. Poprawne zakończenie metody informuje serwer o możliwości usunięcia komponentu, po wcześniejszym wywołaniu metody udekorowanej @PreDestroy.
Atrybuty:

• retainIfException (domyślnie false) - wskazuje, że komponent powinien pozostać w systemie, jeśli wystąpi wyjątek aplikacyjny podczas wywołania metody.

Annotacje związane z komponentem sterowanym komunikatami (ang. MDB - message-driven bean)

@MessageDriven - związana klasa jest klasą MDB. Atrybuty:

• name - ejb-name dla komponentu (domyślnie niekwalifikowana nazwa klasy, tj. nazwa bez pakietu)
• mappedName - nazwa specyficzna dla serwera, do której należy dowiązać komponent (np. globalna nazwa JNDI dla kolejki)
• description - opis komponentu
• messageListenerInterface - interfejs komunikacyjny. Musi być podany, jeśli MDB nie implementuje interfejsu lub implementuje więcej niż jeden interfejs inny niż java.io.Serializable, java.io.Externalizable lub dowolny interfejs z javax.ejb.
• activationConfig - właściwości aktywacyjne komponentu (pary propertyName i propertyValue)
  

Annotacje do wyznaczenia interfejsów biznesowych (wyłącznie dla komponentów sesyjnych)

@Remote - dekoruje klasę komponentu lub interfejs biznesowy określająca zdalny interfejs biznesowy komponentu.

@Local - związana z klasą komponentu lub interfejsem biznesowym określająca lokalny interfejs biznesowy komponentu. Konieczny, jeśli klasa komponentu implementuje interfejsy inne niż: java.io.Serializable, java.io.Externalizable lub interfejsy z pakietu javax.ejb.

Atrybuty @Remote i @Local:

• value - lista interfejsów biznesowych

Annotacje wspierające klientów korzystających z interfejsów EJB 2.1 i wcześniejszych

Terminy i korzystanie z annotacji jest przeznaczone dla aplikacji migrujących do EJB3 z poprzednich wersji.

@RemoteHome - zdalny interfejs domowy komponentu

• value - nazwa klasy interfejsu (typy Class)

@LocalHome - lokalny interfejs domowy komponentu

• value - nazwa klasy interfejsu (typu Class)

Annotacje związane z transakcjami ("annotacje transakcyjne")

@TransactionManagement - określenie, kto odpowiada za zarządzanie transakcją - kontener (ang. CMTD - container-managed transaction demarcation) czy komponent (ang. BMTD - bean-managed transaction demarcation)

• value - CONTAINER (domyślnie) lub BEAN

@TransactionAttribute - określenie kontekstu transakcji podczas wywoływania przez kontener udekorowanej metody. Stosowana wyłącznie dla komponentów sesyjnych i MDB, których transakcja zarządzana jest przez kontener (domyślnie bądź, gdy @TransactionManagement wynosi CONTAINER).
Udekorowaniu podlegają klasa komponentu bądź poszczególne metody interfejsu biznesowego (ale wyłącznie metody interfejsu biznesowego). Udekorowanie klasy określa wymaganie transakcyjne dla wszystkich metod interfejsu biznesowego komponentu. Udekorowanie metody interfejsu biznesowego określa stan transakcji wyłącznie dla niej samej. Jeśli udekorowano i klasę i metodę/-y, wtedy wartość annotacji dla metody jest ostateczną wartością dla niej (oczywiście nie wpływa to na konfigurację pozostałych metod).
Atrybuty:

• value - MANDATORY, REQUIRED (domyślny), REQUIRES_NEW, SUPPORTS, NOT_SUPPORTED, NEVER

Annotacje związane z interceptorami (w tym i metodami zwrotnymi)

@Interceptors - określenie jednej bądź wielu klas interceptorów. Udekorowaniu podlegają klasa komponentu i metody biznesowe. Atrybuty:

• value - klasy interceptorów

@AroundInvoke - określenie metody interceptora. Udekorowane wyłącznie metody nie będącej częścią interfejsu biznesowego.

@ExcludeDefaultInterceptors - przypisana do klasy komponentu wskazując, aby wykonanie domyślnych interceptorów (tych zadeklarowanych w deskryptorze instalacji - ejb-jar.xml) dla wszystkich metod biznesowych jest wyłączone. Udekorowanie metody biznesowej to wyłączenie domyślnych interceptorów tylko dla niej.

@ExcludeClassInterceptors - służy do udekorowania metody biznesowej, aby wyłączyć wykonanie interceptorów przypisanych do komponentu (na poziomie klasy komponentu, patrz @Interceptors), ale nie wyłącza interceptorów domyślnych (tych z deskryptora instalacji)

@PostConstruct, @PreDestroy, @PrePassivate, @PostActivate - "annotacje zwrotne" przypisywane do metod dla określenia metod nie-biznesowych wywoływanych podczas zdarzeń z życia komponentu - utworzenia, usunięcia, pasywacji i aktywacji (dwa ostatnie wyłącznie dla SFSB).

Annotacja @Timeout

@Timeout - przypisana do metody komponentów SLSB oraz MDB, która będzie wywoływana po wygaśnięciu ważności zegara (więcej o tym w rozdziale Chapter 18 Timer Service w EJB3 Core).

Annotacje związane z wyjątkami

@ApplicationException - przypisana do klasy wyjątków kontrolowanych (ang. checked exception) i niekontrolowanych (ang. unchecked exception), aby wskazać wyjątki aplikacyjne, które będą przekazane klientowi bezpośrednio bez opakowywania ich w EJBException.

• rollback - (domyślnie false) - wskazuje, czy kontener musi wycofać transakcję przy rzuceniu wyjątku przez metodę biznesową.

Annotacje związane z bezpieczeństwem (w tym i uprawnieniami wywoływania metod biznesowych)

Annotacje należą do pakietu javax.annotation.security i są zaprezentowane dla kompletności specyfikacji.

@DeclareRoles - przypisana do klasy komponentu, aby zadeklarować role wykorzytane przez komponent

• value - lista ról (typu String)

@RolesAllowed - przypisana do metody deklaruje role uprawnione do jej wywołania, podczas, gdy przypisanie do klasy komponentu określa role uprawnione do wykonania wszystkich metod biznesowych komponentu. Jeśli annotacja występuje na poziomie klasy i metod/-y, wtedy wartość annotacji dla metody jest ostateczną wartością dla niej (oczywiście nie wpływa to na konfigurację pozostałych metod).

@PermitAll - przypisana do metody, która może zostać wywołana przez dowolną rolę w systemie. Jest to ustawienie domyślne. Przypisana do klasy dotyczy wszystkich metod biznesowych komponentu podczas, gdy przypisana do metody dotyczy wyłącznie jej nadpisując wszelkie ustawienia związane z klasą.

@DenyAll - specyfikuje, że żadna z ról nie ma prawa wykonać metody, tj. wykonanie metody jest niemożliwe.

@RunAs - specyfikuje rolę, jaka będzie przypisana z wykonaniem metod (właściwość run-as).

Annotacje związane z referencjami do EJB

@EJB - ustanawia referencję do interfejsu biznesowego lub domowego komponentu.

• name - nazwa komponentu, pod którą można go odszukać w środowisku
• beanInterface - interfejs biznesowy lub domowy komponentu
• beanName - wskazuje na nazwę komponentu (domyślną lub tą podaną jako element name w annotacjach @Stateful lub @Stateless lub ostatecznie jako wartość ejb-name w deskryptorze instalacji). Istnieje możliwość wyróżnienia komponentu, jeśli istnieje więcej komponentów realizujących ten sam interfejs biznesowy należących do tego samego pliku jar. Dla komponentów z innego pliku jar należących do tej samej aplikacji przemysłowej podajemy ścieżkę względną względem pliku jar, do którego należy komponent korzystający z @EJB, rozdzieloną '#' od nazwy komponentu.
• mappedName - specyficzna dla serwera nazwa, do której komponent powinien być przypisany. UWAGA na możliwą nieprzenośność.
  

@EJBs - ustanawia referencje do wielu komponentów EJB (korzystając z elementów @EJB)

Annotacje związane z referencjami do zasobów zewnętrznych (innych niż EJB)

@Resource i @Resources należą do pakietu javax.annotation.

@Resource - określa zależność od zewnętrznego zasobu dostępnym w środowisku komponentu.

• name - nazwa zależności, pod jaką jest znana w środowisku
• type - typ fabryki połączeń zarządcy zasobów
• authenticationType - CONTAINER (domyślnie), APPLICATION - kto odpowiada za uwierzytelnienie
• shareable - (domyślnie true) współdzielność połączeń zarządcy zasobów
• mappedName - specyficzna dla serwera nazwa, do której komponent powinien być przypisany. UWAGA na możliwą nieprzenośność.
  

@Resources - ustanawia zależność do wielu komponentów EJB (korzystając z elementów @Resource)