Skip to content

Latest commit

 

History

History
271 lines (196 loc) · 8.7 KB

EJB3_Reference_Guide.adoc

File metadata and controls

271 lines (196 loc) · 8.7 KB
Raw

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

Each Message Driven Bean must be connected to a resource adapter.

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:

@MessageDriven(messageListenerInterface = PostmanPat.class)
@ResourceAdapter("ejb3-rar.rar")

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

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:

@RunAs("admin")
@RunAsPrincipal("MyBean")

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

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:

@SecurityDomain("other")

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

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

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

jboss-ejb3.xml

<jboss:ejb-jar xmlns:jboss="http://www.jboss.com/xml/ns/javaee"
               xmlns="http://java.sun.com/xml/ns/javaee"
               xmlns:tx="urn:trans-timeout"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee http://www.jboss.org/j2ee/schema/jboss-ejb3-2_0.xsd
http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/ejb-jar_3_1.xsd
urn:trans-timeout http://www.jboss.org/j2ee/schema/trans-timeout-1_0.xsd"
               version="3.1"
               impl-version="2.0">
    <assembly-descriptor>
        <container-transaction>
            <method>
                <ejb-name>BeanWithTimeoutValue</ejb-name>
                <method-name>*</method-name>
                <method-intf>Local</method-intf>
            </method>
            <tx:trans-timeout>
                <tx:timeout>10</tx:timeout>
                <tx:unit>Seconds</tx:unit>
            </tx:trans-timeout>
        </container-transaction>
    </assembly-descriptor>
</jboss:ejb-jar>

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

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

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

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:

@Schedule( ... dayOfMonth="1", month="1", year="2012") +
// start once at 01-01-2012 00:00:00

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

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!