[[EJB3_Reference_Guide]] = EJB 3 Reference Guide This chapter details the extensions that are available when developing Enterprise Java Beans ^tm^ on WildFly {wildflyVersion}. Currently there is no support for configuring the extensions using an implementation specific descriptor file. [[resource-adapter-for-message-driven-beans]] == Resource Adapter for Message Driven Beans Each Message Driven Bean must be connected to a resource adapter. [[specification-of-resource-adapter-using-metadata-annotations]] === Specification of Resource Adapter using Metadata Annotations The `ResourceAdapter` annotation is used to specify the resource adapter with which the MDB should connect. The `value` of the annotation is the name of the deployment unit containing the resource adapter. For example `jms-ra.rar`. For example: [source, java] ---- @MessageDriven(messageListenerInterface = PostmanPat.class) @ResourceAdapter("ejb3-rar.rar") ---- [[run-as-principal]] == Run-as Principal Whenever a run-as role is specified for a given method invocation the default anonymous principal is used as the caller principal. This principal can be overridden by specifying a run-as principal. [[specification-of-run-as-principal-using-metadata-annotations]] === Specification of Run-as Principal using Metadata Annotations The `RunAsPrincipal` annotation is used to specify the run-as principal to use for a given method invocation. The `value` of the annotation specifies the name of the principal to use. The actual type of the principal is undefined and should not be relied upon. Using this annotation without specifying a run-as role is considered an error. For example: [source, java] ---- @RunAs("admin") @RunAsPrincipal("MyBean") ---- [[security-domain]] == Security Domain Each Enterprise Java Bean ^tm^ can be associated with a security domain. Only when an EJB is associated with a security domain will authentication and authorization be enforced. [[specification-of-security-domain-using-metadata-annotations]] === Specification of Security Domain using Metadata Annotations The `SecurityDomain` annotation is used to specify the security domain to associate with the EJB. The `value` of the annotation is the name of the security domain to be used. For example: [source, java] ---- @SecurityDomain("other") ---- [[transaction-timeout]] == Transaction Timeout For any newly started transaction a transaction timeout can be specified in seconds. When a transaction timeout of `0` is used, then the actual transaction timeout will default to the domain configured default. + _TODO: add link to tx subsystem_ Although this is only applicable when using transaction attribute `REQUIRED` or `REQUIRES_NEW` the application server will not detect invalid setups. New Transactions [IMPORTANT] Take care that even when transaction attribute `REQUIRED` is specified, the timeout will only be applicable if a *new* transaction is started. [[specification-of-transaction-timeout-with-metadata-annotations]] === Specification of Transaction Timeout with Metadata Annotations The `TransactionTimeout` annotation is used to specify the transaction timeout for a given method. The `value` of the annotation is the timeout used in the given `unit` granularity. It must be a positive integer or 0. Whenever 0 is specified the default domain configured timeout is used. The `unit` specifies the granularity of the `value`. The actual value used is converted to seconds. Specifying a granularity lower than `SECONDS` is considered an error, even when the computed value will result in an even amount of seconds. For example:@TransactionTimeout(value = 10, unit = TimeUnit.SECONDS) [[specification-of-transaction-timeout-in-the-deployment-descriptor]] === Specification of Transaction Timeout in the Deployment Descriptor The `trans-timeout` element is used to define the transaction timeout for business, home, component, and message-listener interface methods; no-interface view methods; web service endpoint methods; and timeout callback methods. The `trans-timeout` element resides in the `urn:trans-timeout` namespace and is part of the standard `container-transaction` element as defined in the jboss namespace. For the rules when a `container-transaction` is applicable please refer to EJB 3.1 FR 13.3.7.2.1. [[example-of-trans-timeout]] ==== Example of trans-timeout jboss-ejb3.xml [source, xml] ---- BeanWithTimeoutValue * Local 10 Seconds ---- [[timer-service]] == Timer service The service is responsible to call the registered timeout methods of the different session beans. [NOTE] A persistent timer will be identified by the name of the EAR, the name of the sub-deployment JAR and the Bean's name. + If one of those names are changed (e.g. EAR name contain a version) the timer entry became orphaned and the timer event will not longer be fired. [[single-event-timer]] === Single event timer The timer is will be started once at the specified time. In case of a server restart the timeout method of a persistent timer will only be called directly if the specified time is elapsed. + If the timer is not persistent (since EJB3.1 see 18.2.3) it will be not longer available if JBoss is restarted or the application is redeployed. [[recurring-timer]] === Recurring timer The timer will be started at the specified first occurrence and after that point at each time if the interval is elapsed. + If the timer will be started during the last execution is not finished the execution will be suppressed with a warning to avoid concurrent execution. In case of server downtime for a persistent timer, the timeout method will be called only once if one, or more than one, interval is elapsed. + If the timer is not persistent (since EJB3.1 see 18.2.3) it will not longer be active after the server is restarted or the application is redeployed. [[calendar-timer]] === Calendar timer The timer will be started if the schedule expression match. It will be automatically deactivated and removed if there will be no next expiration possible, i.e. If you set a specific year. For example: [source, java] ---- @Schedule( ... dayOfMonth="1", month="1", year="2012") + // start once at 01-01-2012 00:00:00 ---- [[programmatic-calendar-timer]] ==== Programmatic calendar timer If the timer is persistent it will be fetched at server start and the missed timeouts are called concurrent. + If a persistent timer contains an end date it will be executed once nevertheless how many times the execution was missed. Also a retry will be suppressed if the timeout method throw an Exception. + In case of such expired timer access to the given Timer object might throw a NoMoreTimeoutExcption or NoSuchObjectException. If the timer is non persistent it will not longer be active after the server is restarted or the application is redeployed. *TODO*: clarify whether this should happen concurrently/blocked or even fired only once like a recurring timer! [[annotated-calendar-timer]] ==== Annotated calendar timer If the timer is non persistent it will not activated for missed events during the server is down. In case of server start the timer is scheduled based on the @Schedule annotation. If the timer is persistent (default if not deactivated by annotation) all missed events are fetched at server start and the annotated timeout method is called concurrent. *TODO*: clarify whether this should happen concurrently/blocked or even fired only once like a recurring timer! :leveloffset: +1 include::ejb3/Container_interceptors.adoc[] include::ejb3/EJB3_Clustered_Database_Timers.adoc[] include::ejb3/EJB_IIOP_Guide.adoc[] include::ejb3/EJB_over_HTTP.adoc[] include::ejb3/jboss-ejb3.xml_Reference.adoc[] include::ejb3/Message_Driven_Beans_Controlled_Delivery.adoc[] include::ejb3/Securing_EJBs.adoc[] :leveloffset: -1