A EJB Metadata Annotations Reference
This appendix includes the following sections:
Overview of EJB 3.x Annotations
The WebLogic Server EJB 3.2 programming model uses the Java EE 7 metadata annotations feature in which you create an annotated EJB 3.2 bean file, and then compile the class with standard Java compiler, which can then be packaged into a target module for deployment. At runtime, WebLogic Server parses the annotations and applies the required behavioral aspects to the bean file.
The following sections provide reference information for the metadata annotations you can specify in the EJB bean file. Some of the annotations are in the javax.ejb package, and are thus specific to EJBs; others are more common and are used by other Java EE 7 components, and are thus in more generic packages, such as javax.annotation.
Note:
If you are continuing to use deployment descriptors in your EJB implementation, refer to EJB Deployment Descriptors in Developing Enterprise JavaBeans, Version 2.1, for Oracle WebLogic Server.
Annotations for Stateless, Stateful, and Message-Driven Beans
This section provides reference information for the following annotations:
javax.ejb.AccessTimeout
The following sections describe the annotation in more detail.
Description
Target: Method, Type
Specifies the amount of time in a given time unit that a concurrent access attempt should block before timing out.
This annotation may be applied to a stateful session bean or to a singleton session bean that uses container managed concurrency.
By default, clients are allowed to make concurrent calls to a stateful session object and the container is required to serialize such concurrent requests. The AccessTimeout annotation is used to specify the amount of time a stateful session bean request should block in the case that the bean instance is already processing a different request. Use of the AccessTimeout annotation with a value of 0 specifies to the container that concurrent client requests to a stateful session bean are prohibited.
The AccessTimeout annotation can be specified on a business method or a bean class. If it is specified on a class, it applies to all business methods of that class. If it is specified on both a class and on a business method of the class, the method-level annotation takes precedence for the given method.
Access time-outs for a singleton session bean only apply to methods eligible for concurrency locks. The AccessTimeout annotation can be specified on the singleton session bean class or on an eligible method of the class. If AccessTimeout is specified on both a class and on a method of that class, the method-level annotation takes precedence for the given method.
For details, see Optionally Program the EJB Timer Service..
Attributes
The following table summarizes the attributes.
Table A-1 Attributes of the javax.ejb.AccessTimeout Annotation
| Name | Description | Data Type | Required? |
|---|---|---|---|
|
value |
Specifies the amount of time in a given time unit that a concurrent access attempt should block before timing out.
Values less than -1 are not valid. |
Long |
No |
|
unit |
Specifies the units used for the specified value. The default value for this attribute is |
TimeUnit |
No |
javax.ejb.ActivationConfigProperty
The following sections describe the annotation in more detail.
Note:
Based on the Enterprise JavaBean specification, the javax.ejb.ActivationConfigProperty annotation is used for MDBs only. This annotation is not used for session or entity beans.
Description
Target: Any
Specifies properties used to configure a message-driven bean in its operational environment. This may include information about message acknowledgement modes, message selectors, expected destination or endpoint types, and so on. The ActivationConfigProperty is used only for message-driven beans only; it is not used for session beans or entity beans.
This annotation is used only as a value to the activationConfig attribute of the @javax.ejb.MessageDriven annotation. For more information about this annotation, see Using EJB 3.2 Compliant MDBs and Deployment Elements and Annotations for MDBs in Developing Message-Driven Beans
for Oracle WebLogic Server.
Attributes
The following table summarizes the attributes.
Table A-2 Attributes of the javax.ejb.ActivationConfigProperty Annotation
| Name | Description | Data Type | Required? |
|---|---|---|---|
|
propertyName |
Specifies the name of the activation property. |
String |
Yes |
|
propertyValue |
Specifies the value of the activation property. |
String |
Yes |
javax.ejb.AfterBegin
The following sections describe the annotation in more detail.
Description
Target: Method
Designate a stateful session bean method to receive the after begin session synchronization callback.
The after begin callback notifies a stateful session bean instance that a new transaction has started and that the subsequent business methods on the instance will be invoked in the context of the transaction.
This method executes in the proper transaction context. A bean must have at most one AfterBegin method. The signature of this method must observe the following rules:
-
The method must not be declared as
finalorstatic. -
The method may have any access type.
-
The return type must be
void. -
The method must take no arguments.
This method executes with no transaction context.
A stateful session bean class may use either the SessionSynchronization interface or the session synchronization annotations, but not both.
javax.ejb.AfterCompletion
The following sections describe the annotation in more detail.
Description
Target: Method
Designate a stateful session bean method to receive the after completion session synchronization callback.
The after completion callback notifies a stateful session bean instance that a transaction commit protocol has completed. A completion status of true indicates that the transaction has committed. A status of false indicates that a rollback has occurred.
A bean must have at most one AfterCompletion method. The signature of this method must observe the following rules:
-
The method must not be declared as
finalorstatic. -
The method may have any access type.
-
The return type must be
void. -
The method must take a single argument of type
boolean.
This method executes with no transaction context.
A stateful session bean class may use either the SessionSynchronization interface or the session synchronization annotations, but not both.
javax.ejb.ApplicationException
The following sections describe the annotation in more detail.
Description
Target: Class
Specifies that an exception is an application exception and that it should be reported to the client application directly, or unwrapped.
This annotation can be applied to both checked and unchecked exceptions.
Attributes
The following table summarizes the attributes.
Table A-3 Attributes of the javax.ejb.ApplicationException Annotation
| Name | Description | Data Type | Required? |
|---|---|---|---|
|
rollback |
Specifies whether the EJB container should rollback the transaction, if the bean is currently being invoked inside of one, if the exception is thrown. Valid values for this attribute are |
boolean |
No |
javax.ejb.Asynchronous
The following sections describe the annotation in more detail.
Description
Target: Method, Type
Used to mark a session bean method as an asynchronous method or to designate all business methods of a session bean class as asynchronous, where control is returned to the client by the enterprise bean container before the method is invoked on the session bean instance. Asynchronous methods are typically used for long-running operations, for processor-intensive tasks, for background tasks, to increase application throughput, or to improve application response time if the method invocation result isn't required immediately.
Clients calling asynchronous methods, immediately have control returned to them by the enterprise bean container. This allows the client to perform other tasks while the method invocation completes. If the method returns a result, the result is an implementation of the return type void or java.util.concurrent.Future<V> interface, where V is the result value type. The Future<V> interface defines methods the client may use to check if the computation is completed, wait for the invocation to complete, retrieve the final result, and cancel the invocation.
Asynchronous method invocation semantics only apply to the no-interface, local business, and remote business client views. Methods exposed through the EJB 2.x local, EJB 2.x remote, and Web service client views must not be designated as asynchronous.
javax.ejb.BeforeCompletion
The following sections describe the annotation in more detail.
Description
Target: Method
Designate a stateful session bean method to receive the before completion session synchronization callback.
The before completion callback notifies a stateful session bean instance that a transaction is about to be committed.
This method executes in the proper transaction context.
Note:
The instance may still cause the container to rollback the transaction by invoking the setRollbackOnly() method on the session context or by throwing an exception. A bean must have at most one BeforeCompletion method.
The signature of this method must observe the following rules:
-
The method must not be declared as
finalorstatic. -
The method may have any access type.
-
The return type must be
void. -
The method must take no arguments.
This method executes with no transaction context.
A stateful session bean class may use either the SessionSynchronization interface or the session synchronization annotations, but not both.
javax.ejb.ConcurrencyManagement
The following sections describe the annotation in more detail.
Description
Target: Type
Declares a singleton session bean's concurrency management type.
If this annotation is not specified, the singleton bean is assumed to have container managed concurrency.
This annotation may be applied to stateful session beans, but doing so has no impact on the semantics of concurrency management for such beans. The concurrency management type for bean-managed concurrency (BEAN) does not apply to stateful session beans.
Attributes
The following table summarizes the attributes.
Table A-4 Attributes of the javax.ejb.ConcurrencyManagement Annotation
| Name | Description | Data Type | Required? |
|---|---|---|---|
|
value |
Specifies the concurrency management type used by the bean class. Valid values for this attribute are:
The default value for this attribute is |
String |
No. |
javax.ejb.DependsOn
The following sections describe the annotation in more detail.
Description
Target: Type
Used to express an initialization dependency between singleton components.
The container ensures that all singleton beans with which a singleton has a DependsOn relationship have been initialized before the singleton's PostConstruct method is called.
During application shutdown the container ensures that all singleton beans on with which the singleton has a DependsOn relationship are still available during the singleton's PreDestroy method.
Attributes
The following table summarizes the attributes.
Table A-5 Attributes of the javax.ejb.DependsOn Annotation
| Name | Description | Data Type | Required? |
|---|---|---|---|
|
value |
Specifies ejb-names of singleton components whose initialization must occur before this singleton. The order in which these names are listed is not significant. |
String |
No. |
javax.ejb.EJB
The following sections describe the annotation in more detail.
Description
Target: Class, Method, Field
Specifies a dependency or reference to an EJB business or home interface.
You annotate a bean's instance variable with the @EJB annotation to specify a dependence on another EJB. WebLogic Server automatically initializes the annotated variable with the reference to the EJB on which it depends; this is also called dependency injection. This initialization occurs before any of the bean's business methods are invoked and after the bean's EJBContext is set.
You can also annotate a setter method in the bean class; in this case WebLogic Server uses the setter method itself when performing dependency injection. This is an alternative to instance variable dependency injection.
If you apply the annotation to a class, the annotation declares the EJB that the bean will look up at runtime.
Whether using variable or setter method injection, WebLogic Server determines the name of the referenced EJB by either the name or data type of the annotated instance variable or setter method parameter. If there is any ambiguity, you should use the beanName or mappedName attributes of the @EJB annotation to explicitly name the dependent EJB.
Attributes
The following table summarizes the attributes.
Table A-6 Attributes of the javax.ejb.EJB Annotation
| Name | Description | Data Type | Required? |
|---|---|---|---|
|
name |
Specifies the name by which the referenced EJB is to be looked up in the environment. This name must be unique within the deployment unit, which consists of the class and its superclass. |
String |
No |
|
beanInterface |
Specifies the interface type of the referenced EJB (either a business or home interface). Default value for this attribute is |
Class |
No |
|
beanName |
Specifies the name of the referenced EJB. This attribute corresponds to the This attribute is most useful when multiple session beans in an EJB JAR file implement the same interface, because the name of each bean must be unique. |
String |
No |
|
mappedName |
Specifies the global JNDI name of the referenced EJB. For example:
specifies that the referenced EJB has a global JNDI name of Note: EJBs that use mapped names may not be portable. |
String |
No |
|
description |
Describes the EJB reference. |
String |
No |
javax.ejb.Init
The following sections describe the annotation in more detail.
Description
Target: Method
Specifies the correspondence of a method in the bean class with a createMETHOD method for an adapted EJB 2.1 EJBHome or EJBLocalHome client view.
This annotation is used only in conjunction with stateful session beans, or those that have been annotated with the @javax.ejb.Stateful class-level annotation,
The return type of a method annotated with the @javax.ejb.Init annotation must be void, and its parameter types must be exactly the same as those of the referenced createMETHOD method or methods.
The @Init annotation is required only for stateful session beans that provide a Remote-Home or LocalHome interface. You must specify the name of the adapted create method of the Home or LocalHome interface, using the value attribute, if there is any ambiguity.
Attributes
The following table summarizes the attributes.
Table A-8 Attributes of the javax.ejb.Init Annotation
| Name | Description | Data Type | Required? |
|---|---|---|---|
|
value |
Specifies the name of the corresponding This attribute is required only when the |
String |
No |
javax.ejb.Local
The following sections describe the annotation in more detail.
Description
Target: Class
Specifies the local interface or interfaces of a session bean. The local interface exposes business logic to local clients—those running in the same application as the EJB. It defines the business methods a local client can call.
You are required to specify this annotation if your bean class implements more than a single interface, not including the following:
-
java.io.Serializable -
java.io.Externalizable -
javax.ejb.*
This annotation applies only to stateless or stateful session beans.
Attributes
The following table summarizes the attributes.
Table A-9 Attributes of the javax.ejb.Local
| Name | Description | Data Type | Required? |
|---|---|---|---|
|
value |
Specifies the list of local interfaces as an array of classes. You are required to specify this attribute only if your bean class implements more than a single interface, not including the following:
|
Class[] |
No |
javax.ejb.LocalHome
The following sections describe the annotation in more detail.
Description
Target: Class
Specifies the local home interface of the bean class.
The local home interface provides methods that local clients—those running in the same application as the EJB—can use to create, remove, and in the case of an entity bean, find instances of the bean. The local home interface also has home methods—business logic that is not specific to a particular bean instance.
This attribute applies only to stateless and stateful session beans.
You typically specify this attribute only if you are going to provide an adapted EJB 2.1 component view of the EJB 3.x bean. You can also use this annotation with bean classes that have been written to the EJB 2.1 APIs.
javax.ejb.Lock
The following sections describe the annotation in more detail.
Description
Target: Type, Method
Declares a concurrency lock for a singleton session bean with container managed concurrency.
This annotation may be specified on the bean class, the business methods of the bean class or both. Specifying the annotation on a business method overrides the value specified at class level, if any.
If this annotation is not used, a value of Lock(WRITE) is assumed.
Attributes
The following table summarizes the attributes.
Table A-11 Attributes of the javax.ejb.LockType Annotation
| Name | Description | Data Type | Required? |
|---|---|---|---|
|
value |
Specifies the concurrency lock used by the singleton session bean with container managed concurrency. Valid values for this attribute are:
Default value is |
String |
No. |
javax.ejb.MessageDriven
The following sections describe the annotation in more detail.
Attributes
The following table summarizes the attributes.
Table A-12 Attributes of the javax.ejb.MessageDriven Annotation
| Name | Description | Data Type | Required? |
|---|---|---|---|
|
name |
Specifies the name of the message-driven bean. If you do not specify this attribute, the default value is the unqualified name of the bean class. |
String |
No |
|
messageListenerInterface |
Specifies the message-listener interface of the bean class. You must specify this attribute if the bean class does not explicitly implement the message-listener interface, or if the bean class implements more than one interface other than The default value for this attribute is |
Class |
No |
|
activationConfig |
Specifies the configuration of the message-driven bean in its operational environment. This may include information about message acknowledgement modes, message selectors, expected destination or endpoint types, and so on. You specify activation configuration information using an Array of |
ActivationConfigProperty[] |
No |
|
mappedName |
Specifies the product-specific name to which the message-driven bean should be mapped. You can also use this attribute to specify the JNDI name of the message destination of this message-driven bean. For example:
specifies that this message-driven bean is associated with a JMS queue, whose JNDI name is Note: If you specify this attribute, the message-driven bean may not be portable. |
String |
No |
|
description |
Specifies a description of the message-driven bean. |
String |
No |
javax.ejb.PostActivate
The following sections describe the annotation in more detail.
Description
Target: Method
Specifies the life cycle callback method that signals that the EJB container has just reactivated the bean instance.
This annotation applies only to stateful session beans. Because the EJB container automatically maintains the conversational state of a stateful session bean instance when it is passivated, you do not need to specify this annotation for most stateful session beans. You only need to use this annotation, along with its partner @PrePassivate, if you want to allow your stateful session bean to maintain the open resources that need to be closed prior to a bean instance's passivation and then reopened during the bean instance's activation.
Only one method in the bean class can be annotated with this annotation. If you annotate more than one method with this annotations, the EJB will not deploy.
The method annotated with @PostActivate must follow these requirements:
-
The return type of the method must be
void. -
The method must not throw a checked exception.
-
The method may be
public,protected,package privateorprivate. -
The method must not be
static. -
The method must not be
final.
This annotation does not have any attributes.
javax.ejb.PrePassivate
The following sections describe the annotation in more detail.
Description
Target: Method
Specifies the life cycle callback method that signals that the EJB container is about to passivate the bean instance.
This annotation applies only to stateful session beans. Because the EJB container automatically maintains the conversational state of a stateful session bean instance when it is passivated, you do not need to specify this annotation for most stateful session beans. You only need to use this annotation, along with its partner @PostActivate, if you want to allow your stateful session bean to maintain the open resources that need to be closed prior to a bean instance's passivation and then reopened during the bean instance's activation.
Only one method in the bean class can be annotated with this annotation. If you annotate more than one method with this annotations, the EJB will not deploy.
The method annotated with @PrePassivate must follow these requirements:
-
The return type of the method must be
void. -
The method must not throw a checked exception.
-
The method may be
public,protected,package privateorprivate. -
The method must not be
static. -
The method must not be
final.
This annotation does not have any attributes.
javax.ejb.Remote
The following sections describe the annotation in more detail.
Description
Target: Class
Specifies the remote interface or interfaces of a session bean. The remote interface exposes business logic to remote clients—clients running in a separate application from the EJB. It defines the business methods a remote client can call.
This annotation applies only to stateless or stateful session beans.
Attributes
The following table summarizes the attributes.
Table A-13 Attributes of the javax.ejb.Remote Annotation
| Name | Description | Data Type | Required? |
|---|---|---|---|
|
value |
Specifies the list of remote interfaces as an array of classes. You are required to specify this attribute only if your bean class implements more than a single interface, not including the following:
|
Class[] |
No |
javax.ejb.RemoteHome
The following sections describe the annotation in more detail.
Description
Target: Class
Specifies the remote home interface of the bean class.
The remote home interface provides methods that remote clients—those running in a separate application from the EJB—can use to create, remove, and find instances of the bean.
This attribute applies only to stateless and stateful session beans.
You typically specify this attribute only if you are going to provide an adapted EJB 2.1 component view of the EJB 3.x bean. You can also use this annotation with bean classes that have been written to the EJB 2.1 APIs.
javax.ejb.Remove
The following sections describe the annotation in more detail.
Description
Target: Method
Use the @javax.ejb.Remove annotation to denote a remove method of a stateful session bean.
When the method completes, the EJB container will invoke the method annotated with the @javax.annotation.PreDestroy annotation, if any, and then destroy the stateful session bean.
Attributes
The following table summarizes the attributes.
Table A-15 Attributes of the javax.ejb.Remove Annotation
| Name | Description | Data Type | Required? |
|---|---|---|---|
|
retainIfException |
Specifies that the container should not remove the stateful session bean if the annotated method terminates abnormally with an application exception. Valid values are |
boolean |
No |
javax.ejb.Schedule
The following sections describe the annotation in more detail.
Description
Target: Class
Schedule a timer for automatic creation with a timeout schedule based on a CRON-like time expression. The annotated method is used as the timeout callback method.
All elements of this annotation are optional. If none are specified a persistent timer will be created with callbacks occurring every day at midnight in the default time zone associated with the container in which the application is executing.
There are seven elements that constitute a schedule specification which are listed below. In addition, the timezone element may be used to specify a non-default time zone in whose context the schedule specification is to be evaluated; the persistent element may be used to specify a non-persistent timer, and the info element may be used to specify additional information that may be retrieved when the timer callback occurs.
Calendar-based Schedule Elements
The elements that specify the calendar-based schedule itself are as follows:
-
second– one or more seconds within a minute.Allowable values: [0,59]
-
minute– one or more minutes within an hour.Allowable values: [0,59]
-
hour– one or more hours within a day.Allowable values: [0,23]
-
dayOfMonth– one or more days within a month.Allowable values:]
-
1,31]
-
-7, -1
-
"Last"
-
{"1st", "2nd", "3rd", "4th", "5th", "Last"} {"Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"}
"Last" means the last day of the month.
-x (where x is in the range [-7, -1]) means x day(s) before the last day of the month
"1st","2nd", etc. applied to a day of the week identifies a single occurrence of that day within the month.
-
-
month– one or more months within a year.Allowable values:]
-
[1,12]
-
{"Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", Dec"}
-
-
dayOfWeek– one or more days within a week.Allowable values:]
-
[0,7]
-
{"Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"}
"0" and "7" both refer to Sunday
-
-
year– a particular calendar year.Allowable values: a four-digit calendar year
Forms of Supported Element Values
Each element supports values expressed in one of the following forms:
-
Single Value – Constrains the attribute to only one of its possible values.
Example: second = "10" Example: month = "Sep"
-
Wild Card –
"*"Represents all allowable values for a given attribute.Example: second = "*" Example: dayOfWeek = "*"
-
List – Constrains the attribute to two or more allowable values or ranges, with a comma used as a separator character within the string. Each item in the list must be a single value or range. List items cannot be lists, wild cards, or increments. Duplicate values are ignored.
Example: second = "10,20,30" Example: dayOfWeek = "Mon,Wed,Fri" Example: minute = "0-10,30,40"
-
Range – Constrains the attribute to an inclusive range of values, with a dash separating both ends of the range. Each side of the range must be a single attribute value. Members of a range cannot be lists, wild cards, ranges, or increments. If
xis larger thanyin a range"x-y", the range is equivalent to"x-max, min-y", wheremaxis the largest value of the corresponding attribute andminis the smallest. The range"x-x", where both range values are the same, evaluates to the single valuex. The day of the week range"0-7"is equivalent to"*".Example: second = "1-10" Example: dayOfWeek = "Fri-Mon" Example: dayOfMonth = "27-3" (Equivalent to "27-Last , 1-3"
-
Increments – The forward slash constrains an attribute based on a starting point and an interval, and is used to specify every
Nseconds, minutes, or hours within the minute, hour, or day, respectively. For the expressionx/y, the attribute is constrained to every yth value within the set of allowable values beginning at timex. Thexvalue is inclusive. The wild card character (*) can be used in the x position, and is equivalent to0. The use of increments is only supported within thesecond,minute, andhourelements. For thesecondandminuteelements,xandymust each be in the range[0,59]. For thehourelement,xandymust each be in the range[0,23].Example: minute = "?/5" (Every five minutes within the hour)
This is equivalent to: minute = "0,5,10,15,20,25,30,35,40,45,50,55"
Example: second = "30/10" (Every 10 seconds within the minute, starting at second 30)
This is equivalent to: second = "30,40,50"
Note that the set of matching increment values stops once the maximum value for that attribute is exceeded. It does not "roll over" past the boundary.
Example : ( minute = "?/14", hour="1,2")
This is equivalent to: (minute = "0,14,28,42,56", hour = "1,2") (Every 14 minutes within the hour, for the hours of 1 and 2 a.m.)
Additional Rules for Schedule Specification Elements
The following additional rules apply to the schedule specification elements.
-
If the
dayOfMonthelement has a non-wildcard value and thedayOfWeekelement has a non-wildcard value, then any day matching either thedayOfMonthvalue or thedayOfWeekvalue will be considered to apply. -
Whitespace is ignored, except for string constants and numeric values.
-
All string constants (e.g., "Sun", "Jan", "1st", etc.) are case insensitive.
Schedule-based timer times are evaluated in the context of the default time zone associated with the container in which the application is executing. A schedule-based timer may optionally override this default and associate itself with a specific time zone. If the schedule-based timer is associated with a specific time zone, all its times are evaluated in the context of that time zone, regardless of the default time zone in which the container is executing.
The timeout callback method to which the Schedule annotation is applied must have one of the following signatures, where <METHOD> designates the method name:
void <METHOD>() void <METHOD>(Timer timer)
A timeout callback method can have public, private, protected, or package level access. A timeout callback method must not be declared as final or static. Timeout callback methods must not throw application exceptions.
Attributes
The following table summarizes the attributes.
Table A-16 Attributes of the javax.ejb.Schedule Annotation
| Name | Description | Data Type | Required? |
|---|---|---|---|
|
dayofMonth |
Specifies one or more days within a month. Default value is |
String |
No |
|
dayofWeek |
Specifies one or more days within a week. Default value is |
String |
No |
|
hour |
Specifies one or more hours within a day. Default value is |
String |
No |
|
info |
Specifies an information string that is associated with the timer. Default value is |
String |
No |
|
minute |
Specifies one or more minutes within a hour. Default value is |
String |
No |
|
month |
Specifies one or more months within a year. Default value is |
String |
No |
|
persistent |
Specifies whether the timer that is created is persistent. Valid values for this attribute are |
Boolean |
No |
|
second |
Specifies one or more seconds with in a minute. Default value is |
String |
No |
|
timezone |
Specifies the time zone within which the schedule is evaluated. Time zones are specified as an ID string. The set of required time zone IDs is defined by the Default value: If a timezone is not specified, the schedule is evaluated in the context of the default timezone associated with the container in which the application is executing. |
String |
No |
|
year |
Specifies one or more years. Default value is |
String |
No |
javax.ejb.Schedules
The following sections describe the annotation in more detail.
Description
Target: Method
Applied to a timer callback method to schedule multiple calendar-based timers for the method. The method to which the Schedules annotation is applied must have one of the following signatures, where <METHOD> designates the method name:
void <METHOD>() void <METHOD>(Timer timer)
javax.ejb.Singleton
The following sections describe the annotation in more detail.
Attributes
The following table summarizes the attributes.
Table A-18 Attributes of the javax.ejb.Singleton Annotation
| Name | Description | Data Type | Required? |
|---|---|---|---|
|
name |
Specifies the name of the singleton session bean. If you do not specify this attribute, the default value is the unqualified name of the bean class. |
String |
No |
|
mappedName |
Specifies the product-specific name to which the singleton session bean should be mapped. You can also use this attribute to specify the JNDI name of this singleton session bean. WebLogic Server uses the value of the
where For example, if you specify Note: If you specify this attribute, the singleton session bean may not be portable. |
String |
No |
|
description |
Describes the singleton session bean. |
String |
No. |
javax.ejb.StatefulTimeout
The following sections describe the annotation in more detail.
Description
Target: Type
Specifies the amount of time a stateful session bean can be idle (not receive any client invocations) before it is eligible for removal by the container.
Attributes
The following table summarizes the attributes.
Table A-19 Attributes of the javax.ejb.StatefulTimeout Annotation
| Name | Description | Data Type | Required? |
|---|---|---|---|
|
value |
Specifies the amount of time the stateful session bean can be idle.
Values less than -1 are not valid. |
Long |
No |
|
unit |
Specifies the units used for the specified value. The default value for this attribute is |
TimeUnit |
No |
javax.ejb.Stateless
The following sections describe the annotation in more detail.
Attributes
The following table summarizes the attributes.
Table A-20 Attributes of the javax.ejb.Stateless Annotation
| Name | Description | Data Type | Required? |
|---|---|---|---|
|
name |
Specifies the name of the stateless session bean. If you do not specify this attribute, the default value is the unqualified name of the bean class. |
String |
No |
|
mappedName |
Specifies the product-specific name to which the stateless session bean should be mapped. You can also use this attribute to specify the JNDI name of this stateless session bean. WebLogic Server uses the value of the
where For example, if you specify Note: If you specify this attribute, the stateless session bean may not be portable. |
String |
No |
|
description |
Describes the stateless session bean. |
String |
No. |
javax.ejb.Timeout
The following sections describe the annotation in more detail.
Description
Target: Method
Specifies the timeout method of the bean class.
This annotation makes it easy to program an EJB timer service in your bean class. The EJB timer service is an EJB-container provided service that allows you to create timers that schedule callbacks to occur when a timer object expires.
Previous to EJB 3.x, your bean class was required to implement javax.ejb.TimedObject if you wanted to program the timer service. Additionally, your bean class had to include a method with the exact name ejbTimeout. These requirements are relaxed in Version 3.x of EJB. You no longer are required to implement the javax.ejb.TimedObject interface, and you can name your timeout method anything you want, as long as you annotate it with the @Timeout annotation. You can, however, continue to use the pre-3.x way of programming the timer service if you want.
For details, see Optionally Program the EJB Timer Service.
This annotation does not have any attributes.
javax.ejb.TransactionAttribute
The following sections describe the annotation in more detail.
Description
Target: Class, Method
Specifies whether the EJB container invokes an EJB business method within a transaction context.
Note:
If you specify this annotation, you are also required to use the @TransactionManagement annotation to specify container-managed transaction demarcation.
You can specify this annotation on either the bean class, or a particular method of the class that is also a method of the business interface. If specified at the bean class, the annotation applies to all applicable business interface methods of the class. If specified for a particular method, the annotation applies to that method only. If the annotation is specified at both the class and the method level, the method value overrides if the two disagree.
If you do not specify the @TransactionAttribute annotation in your bean class, and the bean uses container managed transaction demarcation, the semantics of the REQUIRED transaction attribute are assumed.
Attributes
The following table summarizes the attributes.
Table A-21 Attributes of the javax.ejb.TransactionAttribute Annotation
| Name | Description | Data Type | Required? |
|---|---|---|---|
|
value |
Specifies how the EJB container manages the transaction boundaries when invoking a business method. For details about these values, see the description of the trans-attribute element in the Container-Managed Transaction Elements table in Developing Enterprise JavaBeans, Version 2.1, for Oracle WebLogic Server. Valid values for this attribute are:
Default value is |
String |
No. |
javax.ejb.TransactionManagement
The following sections describe the annotation in more detail.
Description
Target: Class
Specifies the transaction management demarcation type of the session bean or message-driven bean.
A transaction is a unit of work that changes application state—whether on disk, in memory or in a database—that, once started, is completed entirely, or not at all. Transactions can be demarcated—started, and ended with a commit or rollback—by the EJB container, by bean code, or by client code. This annotation specifies whether the EJB container or the user-written bean code manages the demarcation of a transaction.
If you do not specify this annotation in your bean class, it is assumed that the bean has container-managed transaction demarcation.
For additional information about transactions, see Transaction Design and Management Options in Developing Enterprise JavaBeans, Version 2.1, for Oracle WebLogic Server.
Attributes
The following table summarizes the attributes.
Table A-22 Attributes of the javax.ejb.TransactionManagement Annotation
| Name | Description | Data Type | Required? |
|---|---|---|---|
|
value |
Specifies the transaction management demarcation type used by the bean class. Valid values for this attribute are:
Default value is |
String |
No. |
Annotations Used to Configure Interceptors
This section provides reference information for the annotations described in the following sections:
javax.interceptor.AroundInvoke
The following sections describe the annotation in more detail.
Description
Target: Method
Specifies the business method interceptor for either a bean class or an interceptor class.
You can annotate only one method in the bean class or interceptor class with the @AroundInvoke annotation; the method cannot be a business method of the bean class.
This annotation does not have any attributes.
javax.interceptor.ExcludeClassInterceptors
The following sections describe the annotation in more detail.
javax.interceptor.ExcludeDefaultInterceptors
The following sections describe the annotation in more detail.
Description
Target: Class, Method
Specifies that any defined default interceptors (which can be specified only in the EJB deployment descriptors, and not with annotations) should not be invoked.
If defined at the class-level, the default interceptors are never invoked for any of the bean's business methods. If defined at the method-level, the default interceptors are never invoked for the particular business method, but they are invoked for all other business methods that do not have the @ExludeDefaultInterceptors annotation.
This annotation does not include any attributes.
javax.interceptor.Interceptors
The following sections describe the annotation in more detail.
Description
Target: Class, Method
Specifies the interceptor classes that are associated with the bean class or method. An interceptor class is a class—distinct from the bean class itself—whose methods are invoked in response to business method invocations and/or life cycle events on the bean.
The interceptor class can include both an business interceptor method (annotated with the @javax.interceptor.AroundInvoke annotation) and life cycle callback methods (annotated with the @javax.annotation.PostConstruct, @javax.annotation.PreDestroy, @javax.ejb.PostActivate, and @javax.ejb.PrePassivate annotations).
Any number of interceptor classes may be defined for a bean class. If more than one interceptor class is defined, they are invoked in the order they are specified in the annotation.
If the annotation is specified at the class-level, the interceptors apply to all business methods of the EJB. If specified at the method-level, the interceptors apply to just that method. You can specify the same interceptor class to more than one method of the bean class. By default, method-level interceptors are invoked after all applicable interceptors (default interceptors, class-level interceptors, and so on).
Attributes
The following table summarizes the attributes.
Table A-23 Attributes of the javax.interceptor.Interceptors Annotation
| Name | Description | Data Type | Required? |
|---|---|---|---|
|
value |
Specifies the array of interceptor classes. If there is more than one interceptor class in the array, the order in which they are listed defines the order in which they are invoked. |
Class[] |
Yes |
Annotations Used to Interact With Entity Beans
This section provides reference information about the annotations described in the following sections:
javax.persistence.PersistenceContext
The following sections describe the annotation in more detail.
Description
Target: Class, Method, Field
Specifies a dependency on a container-managed EntityManager persistence context.
You use this annotation to interact with a 3.x entity bean, typically by performing dependency injection into an EntityManager instance.
The EntityManager interface defines the methods that are used to interact with the persistence context. A persistence context is a set of entity instances; an entity is a lightweight persistent domain object. The EntityManager API is used to create and remove persistent entity instances, to find entities by their primary key, and to query over entities.
Attributes
The following table summarizes the attributes.
Table A-24 Attributes of the javax.persistence.PersistenceContextAnnotation
| Name | Description | Data Type | Required? |
|---|---|---|---|
|
name |
Specifies the name by which the You only need to specify this attribute if you use a JNDI lookup to obtain an |
String |
No |
|
unitName |
Specifies the name of the persistence unit. If you specify a value for this attribute that is the same as the name of a persistence unit in the Note: The You must specify this attribute if there is more than one persistence unit within the referencing scope. |
String |
No |
|
type |
Specifies whether the lifetime of the persistence context is scoped to a transaction or whether it extends beyond that of a single transaction. Valid values for this attribute are:
Default value is |
|
No |
javax.persistence.PersistenceContexts
The following sections describe the annotation in more detail.
javax.persistence.PersistenceUnit
The following sections describe the annotation in more detail.
Description
Target: Class, Method, Field
Specifies a dependency on an EntityManagerFactory object.
You use this annotation to interact with a 3.x entity bean, typically by performing dependency injection into an EntityManagerFactory instance. You can then use the EntityManagerFactory to create one or more EntityManager instances. This annotation is similar to the @PersistenceContext annotation, except that it gives you more control over the life of the EntityManager because you create and destroy it yourself, rather than let the EJB container do it for you.
The EntityManager interface defines the methods that are used to interact with the persistence context. A persistence context is a set of entity instances; an entity is a lightweight persistent domain object. The EntityManager API is used to create and remove persistent entity instances, to find entities by their primary key, and to query over entities.
Attributes
The following table summarizes the attributes.
Table A-26 Attributes of the javax.persistence.PersistenceUnit Annotation
| Name | Description | Data Type | Required? |
|---|---|---|---|
|
name |
Specifies the name by which the You are not required to specify this attribute if you use dependency injection, only if you also use JNDI to look up information. |
String |
No |
|
unitName |
Refers to the name of the persistence unit as defined in the If you set this attribute, the EJB container automatically deploys the referenced persistence unit and sets its JNDI name to its persistence unit name. Similarly, if you do not specify this attribute, but the name of the variable into which you are injecting the persistence context information is the same as the name of a persistence unit in the You are required to specify this attribute only if there is more than one persistence unit in the referencing scope. |
String |
No |
Standard JDK Annotations Used By EJB 3.x
This section provides reference information about the annotations described in the following sections:
javax.annotation.PostConstruct
The following sections describe the annotation in more detail.
Description
Target: Method
Specifies the life cycle callback method that the EJB container should execute before the first business method invocation and after dependency injection is done to perform any initialization.
You may specify a @PostConstruct method in any bean class that includes dependency injection.
Only one method in the bean class can be annotated with this annotation. If you annotate more than one method with this annotations, the EJB will not deploy.
The method annotated with @PostConstruct must follow these requirements:
-
The return type of the method must be
void. -
The method must not throw a checked exception.
-
The method may be
public,protected,package privateorprivate. -
The method must not be
static. -
The method must not be
final.
This annotation does not have any attributes.
javax.annotation.PreDestroy
The following sections describe the annotation in more detail.
Description
Target: Method
Specifies the life cycle callback method that signals that the bean class instance is about to be destroyed by the EJB container. You typically apply this annotation to methods that release resources that the bean class has been holding.
Only one method in the bean class can be annotated with this annotation. If you annotate more than one method with this annotations, the EJB will not deploy.
The method annotated with @PreDestroy must follow these requirements:
-
The return type of the method must be
void. -
The method must not throw a checked exception.
-
The method may be
public,protected,package privateorprivate. -
The method must not be
static. -
The method must not be
final.
This annotation does not have any attributes.
javax.annotation.Resource
The following sections describe the annotation in more detail.
Description
Target: Class, Method, Field
Specifies a dependence on an external resource, such as a JDBC data source or a JMS destination or connection factory.
If you specify the annotation on a field or method, the EJB container injects an instance of the requested resource into the bean when the bean is initialized. If you apply the annotation to a class, the annotation declares a resource that the bean will look up at runtime.
Attributes
The following table summarizes the attributes.
Table A-28 Attributes of the javax.annotation.Resource Annotation
| Name | Description | Data Type | Required? |
|---|---|---|---|
|
name |
Specifies the name of the resource reference. If you apply the |
String |
No |
|
type |
Specifies the Java data type of the resource. If you apply the |
Class |
No |
|
authenticationType |
Specifies the authentication type to use for the resource. You specify this attribute only for resources representing a connection factory of any supported type. Valid values for this attribute are:
Default value is |
AuthenticationType |
No |
|
shareable |
Indicates whether a resource can be shared between this EJB and other EJBs. You specify this attribute only for resources representing a connection factory of any supported type or ORB object instances. Valid values for this attribute are |
boolean |
No |
|
mappedName |
Specifies the global JNDI name of the dependent resource. For example:
specifies that the JNDI name of the dependent resources is |
String |
No |
|
description |
Specifies a description of the resource. |
String |
No |
Standard Security-Related JDK Annotations Used by EJB 3.x
This section provides reference information about the annotations described in the following sections:
javax.annotation.security.DeclareRoles
The following sections describe the annotation in more detail.
Description
Target: Class
Defines the security roles that will be used in the EJB.
You typically use this annotation to define roles that can be tested from within the methods of the annotated class, such as using the isUserInRole method. You can also use the annotation to explicitly declare roles that are implicitly declared if you use the @RolesAllowed annotation on the class or a method of the class.
You create security roles in WebLogic Server using the WebLogic Server Administration Console. See Manage Security Roles in the Oracle WebLogic Server Administration Console Online Help.
javax.annotation.security.RolesAllowed
The following sections describe the annotation in more detail.
Description
Target: Class, Method
Specifies the list of security roles that are allowed to access methods in the EJB.
If you specify it at the class-level, then it applies to all methods in the bean class. If you specify it at the method-level, then it only applies to that method. If you specify the annotation at both the class- and method-level, the method value overrides the class value.
You create security roles in WebLogic Server using the WebLogic Server Administration Console. See Manage Security Roles in the Oracle WebLogic Server Administration Console Online Help.
javax.annotation.security.RunAs
The following sections describe the annotation in more detail.
Description
Target: Class
Specifies the security role which actually executes the EJB in the EJB container.
The security role must exist in the WebLogic Server security realm and map to a user or group. See Manage Security Roles in the Oracle WebLogic Server Administration Console Online Help.
WebLogic Annotations
This section provides reference information for the WebLogic annotations described in the following sections:
-
weblogic.javaee.TransactionTimeoutSeconds
Note:
The annotations descried in this section are overridden if the comparable configuration is defined in the
weblogic-ejb-jar.xmldeployment descriptor. See weblogic-ejb-jar.xml Deployment Descriptor Reference in Developing Enterprise JavaBeans, Version 2.1, for Oracle WebLogic Server.
weblogic.javaee.AllowRemoveDuringTransaction
The following sections describe the annotation in more detail.
Description
Target: Class (Stateful session EJBs only)
Flag that specifies whether an instance can be removed during a transaction.
Note:
This annotation is overridden by the allow-remove-during-transaction element in the weblogic-ejb-jar.xml deployment descriptor. See weblogic-ejb-jar.xml Deployment Descriptor Reference in Developing Enterprise JavaBeans,
Version 2.1, for Oracle WebLogic Server.
weblogic.javaee.CallByReference
The following sections describe the annotation in more detail.
Description
Target: Class (Stateful or stateless sessions EJBs only)
Flag that specifies whether parameters are copied—or passed by reference—regardless of whether the EJB is called remotely or from within the same EAR.
Note:
Method parameters are always passed by value when an EJB is called remotely. This annotation is overridden by the enable-call-by-reference element in the weblogic-ejb-jar.xml deployment descriptor. See weblogic-ejb-jar.xml Deployment Descriptor Reference in Developing Enterprise JavaBeans,
Version 2.1, for Oracle WebLogic Server.
weblogic.javaee.DisableWarnings
The following sections describe the annotation in more detail.
Description
Target: Class
Specifies that WebLogic Server should disable the warning message whose ID is specified.
Note:
This annotation is overridden by the disable-warning element in the weblogic-ejb-jar.xml deployment descriptor. See weblogic-ejb-jar.xml Deployment Descriptor Reference in Developing Enterprise JavaBeans,
Version 2.1, for Oracle WebLogic Server.
Attributes
The following table summarizes the attributes.
Table A-33 Attributes of the weblogic.javaee.DisableWarnings
| Name | Description | Data Type | Required? |
|---|---|---|---|
|
WarningCode |
Specifies the warning code. Set this element to one of the following four values:
|
String |
Yes |
weblogic.javaee.EJBReference
The following sections describe the annotation in more detail.
Attribute
The following table summarizes the attributes.
Table A-34 Attribute of the weblogic.javaee.EJBReference Annotation
| Name | Description | Data Type | Required? |
|---|---|---|---|
|
name |
Specifies the name by which the referenced EJB is to be looked up in the environment. This name must be unique within the deployment unit, which consists of the class and its superclass. |
String |
Yes |
|
jndiName |
Specifies the JNDI name of an actual EJB, resource, or reference available in WebLogic Server. |
String |
Yes |
weblogic.javaee.Idempotent
The following sections describe the annotation in more detail.
Description
Target: Class
Specifies an EJB that is written in such a way that repeated calls to the same method with the same arguments has exactly the same effect as a single call. This allows the failover handler to retry a failed call without knowing whether the call actually compiled on the failed server. When you enable idempotent for a method, the EJB stub can automatically recover from any failure as long as it can reach another server hosting the EJB.
Note:
This annotation is overridden by the idempotent-method and retry-methods-on-rollback elements in the weblogic-ejb-jar.xml deployment descriptor. See weblogic-ejb-jar.xml Deployment Descriptor Reference in Developing Enterprise JavaBeans,
Version 2.1, for Oracle WebLogic Server.
Attributes
The following table summarizes the attributes.
Table A-35 Attributes of the weblogic.javaee.Idempotent
| Name | Description | Data Type | Required? |
|---|---|---|---|
|
retryOnRollbackCount |
Number of times to automatically retry container-managed transactions that have rolled back. This attribute defaults to 0. |
int |
No |
weblogic.javaee.JMSClientID
The following sections describe the annotation in more detail.
Description
Target: Method
Specifies a client ID for the MDB when it connects to a JMS destination. Required for durable subscriptions to JMS topics.
If you specify the connection factory that the MDB uses in weblogic.javaee.MessageDestinationConfiguration, the client ID can be defined in the ClientID element of the associated JMSConnectionFactory element in config.xml.
If JMSConnectionFactory in config.xml does not specify a ClientID, or if you use the default connection factory, (you do not specify weblogic.javaee.MessageDestinationConfiguration) the MDB uses the jms-client-id value as its client id.
Note:
This annotation is overridden by the jms-client-id element in the weblogic-ejb-jar.xml deployment descriptor. See weblogic-ejb-jar.xml Deployment Descriptor Reference in Developing Enterprise JavaBeans,
Version 2.1, for Oracle WebLogic Server.
Attributes
The following table summarizes the attributes.
Table A-36 Attributes of the weblogic.javaee.JMSClientID
| Name | Description | Data Type | Required? |
|---|---|---|---|
|
value |
Client ID. |
String |
No |
|
generateUniqueID |
Flag that indicates whether or not you want the EJB container to generate a unique client ID for every instance of an MDB. Enabling this flag makes it easier to deploy durable MDBs to multiple server instances in a WebLogic Server cluster. |
Class |
No |
weblogic.javaee.JNDIName
The following sections describe the annotation in more detail.
Description
Target: Class (Stateful or stateless session EJBs only)
Specifies a custom JNDI name that can be applied to a bean class for a certain client view. When applied to a bean class to indicate the JNDI name of a no-interface view, the className is optional.
Note:
This annotation is overridden by the jndi-binding element in the weblogic-ejb-jar.xml deployment descriptor. See weblogic-ejb-jar.xml Deployment Descriptor Reference in Developing Enterprise JavaBeans,
Version 2.1, for Oracle WebLogic Server.
weblogic.javaee.JNDINames
The following sections describe the annotation in more detail.
Description
Target: Class (Stateful or stateless session EJBs only)
Specifies the multiple, custom JNDI names that can be applied to an EJB.
weblogic.javaee.MessageDestinationConfiguration
The following sections describe the annotation in more detail.
Description
Target: Class (Message-driven EJBs only)
Specifies the JNDI name of the JMS Connection Factory that a message-driven EJB looks up to create its queues and topics.
Note:
This annotation is overridden by the connection-factory-jndi-name element in the weblogic-ejb-jar.xml deployment descriptor. See weblogic-ejb-jar.xml Deployment Descriptor Reference in Developing Enterprise JavaBeans,
Version 2.1, for Oracle WebLogic Server.
Attributes
The following table summarizes the attributes.
Table A-39 Attributes of the weblogic.javaee.MessageDestinationConfiguration
| Name | Description | Data Type | Required? |
|---|---|---|---|
|
connectionFactoryJNDIName |
Connection factory JNDI name. This attribute defaults to an empty string. |
String |
No |
|
initialContextFactory |
WebLogic initial context factory. This attribute defaults to |
Class |
No |
|
providerURL |
URL of the provider. This attribute defaults to |
String |
No |
weblogic.javaee.TransactionIsolation
The following sections describe the annotation in more detail.
Description
Target: Method
Method-level transaction isolation settings for an EJB.
Note:
This annotation is overridden by the trans-timeout-seconds element in the weblogic-ejb-jar.xml deployment descriptor. See weblogic-ejb-jar.xml Deployment Descriptor Reference in Developing Enterprise JavaBeans,
Version 2.1, for Oracle WebLogic Server.
Attributes
The following table summarizes the attributes.
Table A-40 Attributes of the weblogic.javaee.Idempotent
| Name | Description | Data Type | Required? |
|---|---|---|---|
|
IsolationLevel |
Isolation level. Valid values include:
This attribute defaults to DEFAULT. |
int |
No |