|
| |
| Sun Java System Application Server Standard and Enterprise Edition 7 2004Q2 Developer's Guide to Enterprise JavaBeans Technology | |
Chapter 8
Assembling and Deploying Enterprise BeansThis section describes how enterprise beans are assembled and deployed in the Sun Java System Application Server environment and provides information on the elements and subelements used to create the EJB XML files.
This section contains the following topics:
An alphabetical list of all EJB-related elements is contained in Elements Listings.
EJB StructureThe EJB Java ARchive (JAR) file is the standard format for assembling enterprise beans. This file contains the bean classes (home, remote, local, and implementation), all the utility classes, and the deployment descriptors (ejb-jar.xml and sun-ejb-jar.xml).
An EJB JAR file produced by a developer contains one or more enterprise beans and typically does not contain assembly instructions. An EJB JAR file produced by an assembler contains one or more enterprise beans plus application assembly instructions describing how the enterprise beans are combined into a single application deployment unit.
An EJB JAR file can stand alone without being part of an Enterprise ARchive (EAR) file, or be part of an EAR file.
Sample application files are located in install_root/samples/.
Creating Deployment DescriptorsA J2EE module is a collection of one or more J2EE components of the same container type with two deployment descriptors of that type. One descriptor is J2EE standard, the other is specific to Sun Java System Application Server. For enterprise beans, two deployment descriptor files apply:
A Sun Java System Application Server-specific file used if the deployed bean uses container-managed persistence.
Note
For information on the XML file associated with container-managed persistence, refer to Elements in the sun-cmp-mappings.xml File.
The easiest way to create the deployment descriptor files is to deploy an EJB module using the Administration interface or Sun ONE Studio 5 IDE. For more information, see the Sun Java System Application Server Developer’s Guide. For example EJB XML files, see Sample EJB XML Files.
After you have created these files, you can edit them using the Sun ONE Studio 5 IDE or a combination of an editor and command line utilities such as Ant to reassemble and redeploy the updated deployment descriptor information.
The J2EE standard deployment descriptors are described in the 1.3 J2EE Specification. For more information on EJB deployment descriptors, see Chapter 22 in the Enterprise JavaBeans Specification, v2.0. Our sample applications develop some ANT targets that help in assembly and deployment. Refer to the ANT information in the Sun Java System Application Server Developer’s Guide.
Deploying Enterprise BeansWhen you deploy or undeploy an enterprise bean, you do not need to restart the server. When you redeploy an enterprise bean, you do not need to restart the server unless you are changing the bean’s deployment settings.
Note
Stubs and skeletons are generated during deployment. You can retrieve the client JAR file with the stubs and skeletons for use with a rich client.
This section addresses the following topics:
For more detailed information about deployment, see the Sun Java System Application Server Developer’s Guide.
Using the Administration Interface
You can use the Administration interface to deploy modules and applications to both local and remote Application Server sites. To use this tool, follow these steps:
- Open the Applications component under your server instance.
- Go to the Enterprise Apps or EJB Modules page.
- Click on the Deploy button. (You can also undeploy, enable, or disable an application or module from this page.)
- Enter the full path to the module or application directory or archive file (or click on Browse to find it), then click on the OK button.
- Enter the module or application name.
- Assign the application or web module to one or more virtual servers by checking the boxes next to the virtual server names.
- You can also redeploy the module or application if it already exists (called forced deployment) by checking the appropriate box. This is optional.
- You can run the verifier to check your deployment descriptor files. This is optional. For details about the verifier, see the Developer’s Guide.
- To enable SFSB checkpointing, make sure Availability Enabled is set to either true or Specified by Container (if availability is enabled for the EJB container).
- Other fields are displayed depending on the type of module. Check appropriate boxes and enter appropriate values. Required fields are marked with asterisks (*).
- Click on the OK button.
Using the Command-Line Interface
To deploy an enterprise bean using the command line:
- Edit the deployment descriptor files (ejb-jar.xml and sun-ejb-jar.xml) by hand.
- Execute an Ant build command (such as build jar) to reassemble the JAR module.
- Use the asadmin deploy command to deploy a JAR module, or the asadmin deploydir command to deploy a module in an open directory structure. The syntax is as follows, with defaults shown for optional parameters that have them:
asadmin deploy --user admin_user [--password admin_password] [--passwordfile password_file] [--host localhost] [--port 4848] [--secure | -s] [--virtualservers virtual_servers] [--type application|ejb|web|connector] [--contextroot contextroot] [--force=true] [--precompilejsp=false] [--verify=false] [--name component_name] [--upload=true] [--availabilityenabled] [--retrieve local_dirpath] [--instance instance_name] filepath
asadmin deploydir --user admin_user [--password admin_password] [--passwordfile password_file] [--host localhost] [--port 4848] [--secure | -s] [--virtualservers virtual_servers] [--type application|ejb|web|connector] [--contextroot contextroot] [--force=true] [--precompilejsp=false] [--verify=false] [--name component_name] [--availabilityenabled] [--instance instance_name] dirpath
To enable SFSB checkpointing, make sure -- availabilityenabled is either set to true or not specified (if availability is enabled for the EJB container).
Note
The --availabilityenabled setting is in the Sun Java System Application Server Enterprise Edition only.
After using either of these commands for redeployment, you must restart the server for any deployment setting changes to take effect.
For example, the following command deploys an EJB JAR module:
Using the Sun ONE Studio 5 IDE
You can use Sun ONE Studio 5 IDE to assemble and deploy enterprise beans. For information about using Sun ONE Studio 5, see the Sun ONE Studio 5, Enterprise Edition tutorial.
Reloading Enterprise Beans
If you make code changes to an enterprise bean and dynamic reloading is enabled, you do not need to redeploy the enterprise bean or restart the server. You can simply drop the changed files into the application’s deployed directory (such as, instance-dir/applications) and the changes will be picked up.
To enable dynamic reloading with the Administration interface:
- In the Administration interface, select your server instance
- Select Applications.
The Application Properties page is displayed.
- Check the Reload Enabled box to enable dynamic reloading.
- Enter a number of seconds in the Reload Poll Interval field to set the interval at which applications and modules are checked for code changes and dynamically reloaded.
- Click Save.
For details, see the Sun Java System Application Server Administration Guide.
In addition, to load new servlet files, reload EJB related changes, or reload deployment descriptor changes, you must do the following:
- Explicitly update the .reload file’s timestamp (touch .reload in UNIX) each time you make changes to the bean or deployment descriptor.
The reload monitor thread periodically looks at the timestamp of the .reload files to detect any changes. This interval is, by default, two seconds and can be modified by changing the value of dynamic-reload-poll-interval-in-seconds in the server.xml file.
Deploying to a Cluster (Enterprise Edition)
If a server instance is part of a cluster, you should deploy the same modules and applications to each instance in the cluster using the cladmin command. For details, see the Sun Java System Application Server Administration Guide.
The sun-ejb-jar_2_0-0.dtd File StructureThe sun-ejb-jar_2_0-0.dtd file defines the structure of the sun-ejb-jar.xml file, including the elements it can contain and the subelements and attributes these elements can have. The sub-ejb-jar_2_0-0.dtd file is located in the install-dir/lib/dtds directory.
Note
Do not edit the sun-ejb-jar_2_0-0.dtd file; its contents change only with new versions of the Sun Java System Application Server.
For general information about DTD files and XML, see the XML specification at:
Each element defined in a DTD file (which may be present in the corresponding XML file) can contain the following:
An alphabetical list of all EJB-related elements is contained in Elements Listings.
Subelements
Elements can contain subelements. For example, the following file fragment defines the cmp-resource element:
<!ELEMENT cmp-resource (jndi-name, default-resource-principal?)>
This ELEMENT tag specifies that a resource element called cmp-resource can contain subelements called jndi-name and default-resource-principal, with the question mark (?) indicating that there can be zero or one of the default-resource-principal subelement.
Each subelement can be suffixed with an optional character to determine the number of times it can occur.
The following table shows how optional suffix characters of subelements determine the requirement rules, or number of allowed occurrences, for the subelements.
If an element cannot contain other elements, you see EMPTY or (#PCDATA) instead of a list of element names in parentheses.
Data
Some elements contain character data instead of subelements. These elements have definitions of the following format:
<!ELEMENT element-name (#PCDATA)>
For example:
<!ELEMENT description (#PCDATA)>
In the Sun Java System Application Server XML files, white space is treated as part of the data in a data element. Therefore, there should be no extra white space before or after the data delimited by a data element. For example:
<description>class name of session manager</description>
<password>secret</password>
Attributes
Elements can contain attributes (name, value pairs). Attributes are defined in attributes lists using the ATTLIST tag. For example:
<!ATTLIST ejb availability-enabled %boolean; "false">
Attribute declarations specify the type of the attribute. For example, %boolean is a predefined enumeration. Wherever possible, explicit defaults for optional attributes (such as "false") are listed.
Elements in the sun-ejb-jar.xml FileAn alphabetical list of all EJB-related elements is contained in Elements Listings.
Note
For information on the DTD and XML file associated with container-managed persistence mapping, refer to Elements in the sun-cmp-mappings.xml File.
This section describes the XML elements in the sun-ejb-jar_2_0-0.dtd file. For your convenience, the elements are grouped as follows:
General Elements
General elements are as follows:
ejb
Defines runtime properties for a single enterprise bean within the application. The subelements listed below apply to particular enterprise beans as follows:
- All types of beans—ejb-name, ejb-ref, resource-ref, resource-env-ref, cmp, ior-security-config, gen-classes, jndi-name
- Stateless session beans and message-driven beans—bean-pool
- Stateful session beans and entity beans—bean-cache
- Entity beans (BMP)—is-read-only-bean, refresh-period-in-seconds, commit-option, bean-cache
- Message-driven bean—mdb-connection-factory, jms-durable-subscription-name, jms-max-messages-load, bean-pool
Subelements
The following table describes subelements for the ejb element.
Attributes
The following table describes attributes for the ejb element.
Table 8-3 ejb Attributes
Attribute
Default
Description
availability-enabled
Enabled or disabled setting of EJB container
(optional) If set to true, SFSB state persistence is enabled for this SFSB. For details, see “Enabling SFSB Checkpointing” on page 55.
Example
<ejb>
ejb-name>CustomerEJB</ejb-name>
<jndi-name>customer</jndi-name>
<resource-ref>
<res-ref-name>jdbc/SimpleBank</res-ref-name>
<jndi-name>jdbc/PointBase</jndi-name>
</resource-ref>
<is-read-only-bean>false</is-read-only-bean>
<commit-option>B</commit-option>
<bean-pool>
<steady-pool-size>10</steady-pool-size>
<resize-quantity>10</resize-quantity>
<max-pool-size>100</max-pool-size>
<pool-idle-timeout-in-seconds>
600
</pool-idle-timeout-in-seconds>
</bean-pool>
<bean-cache>
<max-cache-size>100</max-cache-size>
<resize-quantity>10</resize-quantity>
<removal-timeout-in-seconds>3600</removal-timeout-in-seconds>
<victim-selection-policy>LRU</victim-selection-policy>
</bean-cache>
</ejb>ejb-name
Matches the display name of the enterprise bean to which it refers. This name is assigned by the EJB JAR file producer to name the enterprise bean in the EJB JAR file's deployment descriptor. The name must be unique among the names of the enterprise beans in the same EJB JAR file.
There is no architected relationship between the ejb-name in the deployment descriptor and the JNDI name that the deployer will assign to the EJB's home.
Subelements
none
Example
<ejb-name>EmployeeService</ejb-name>
enterprise-beans
Specifies all the runtime properties for an EJB JAR file in the application.
Subelements
The following table describes subelements for the enterprise-bean element.
Example
<enterprise-beans>
<ejb>
ejb-name>CustomerEJB</ejb-name>
<jndi-name>customer</jndi-name>
<resource-ref>
<res-ref-name>jdbc/SimpleBank</res-ref-name>
‘ <jndi-name>jdbc/PointBase</jndi-name>
</resource-ref>
<is-read-only-bean>false</is-read-only-bean>
<commit-option>B</commit-option>
<bean-pool>
<steady-pool-size>10</steady-pool-size>
<resize-quantity>10</resize-quantity>
<max-pool-size>100</max-pool-size>
<pool-idle-timeout-in-seconds>
600
</pool-idle-timeout-in-seconds>
</bean-pool>
<bean-cache>
<max-cache-size>100</max-cache-size>
<resize-quantity>10</resize-quantity>
<removal-timeout-in-seconds>3600</removal-timeout-in-seconds>
<victim-selection-policy>LRU</victim-selection-policy>
</bean-cache>
</ejb>
</enterprise-beansis-read-only-bean
A flag specifying that this bean is a read-only bean.
Subelements
none
Example
<is-read-only-bean>false</is-read-only-bean>
refresh-period-in-seconds
Specifies the rate at which a read-only-bean must be refreshed from the data source. If the value is less than or equal to zero, the bean is never refreshed; if the value is greater than zero, the bean instances are refreshed at specified intervals. This rate is just a hint to the container. Default is 600.
Subelements
none
sun-ejb-jar
Defines the Sun Java System Application Server-specific configuration for an EJB JAR file in the application. This is the root element; there can only be one sun-ejb-jar element in an sun-ejb-jar.xml file.
Refer to Sample sun-ejb-jar.xml File for example of this file.
Subelements
The following table describes subelements for the sun-ejb-jar element.
unique-id
Specifies a unique system identifier. This data is automatically generated and updated at deployment/redeployment. Developers should not change these values after deployment.
Subelements
none
Role Mapping Elements
The role mapping element maps a role, as specified in the EJB JAR role-name entries, to a environment-specific user or group. If it maps to a user, it must be a concrete user which exists in the current realm who can log into the server using the current authentication method. If it maps to a group, the realm must support groups and it must be a concrete group which exists in the current realm. To be useful, there must be at least one user in that realm who belongs to that group.
Role mapping elements are as follows:
group-name
Specifies the group name.
Subelements
none
principal
Defines a node that specifies a user name on the platform.
Subelements
The following table describes subelements for the principal element.
Table 8-6 principal Subelements
Subelement
Required
Description
only one
Specifies the name of the user.
principal-name
Specifies the principal (user) name in an enterprise bean that has the run-as role specified.
Subelements
none
role-name
Specifies the role-name in the security-role element of the ejb-jar.xml file.
Subelements
none
Example
<role-name>employee</role-name>
security-role-mapping
Maps roles to users and groups.
Subelements
The following table describes subelements for the security-role-mapping element.
server-name
Specifies the name of the server where the application is being deployed.
Subelements
none
Reference Elements
Reference elements are as follows:
ejb-ref
Maps the absolute jndi-name name to the ejb-ref element in the corresponding J2EE XML file. The ejb-ref element is used for the declaration of a reference to an EJB’s home.
Applies to session beans or entity beans.
Subelements
The following table describes subelements for the ejb-ref element.
Table 8-8 ejb-ref Subelements
Subelement
Required
Description
only one
Specifies the ejb-ref-name in the corresponding J2EE EJB JAR file ejb-ref entry.
only one
Specifies the absolute jndi-name.
ejb-ref-name
Specifies the ejb-ref-name in the corresponding J2EE XML file ejb-ref entry. The name must be unique within the enterprise bean, and should be prefixed with ejb/.
Subelements
none
Example
<ejb-ref-name>ejb/Payroll</ejb-ref-name>
jndi-name
Specifies the absolute jndi-name.
Applies to all enterprise beans.
Subelements
none
Example
<jndi-name>jdbc/PointBase</jndi-name>
pass-by-reference
Specifies the passing method used by a servlet or enterprise bean calling a remote interface method in another bean that is co-located within the same process.
- If false (the default if this element is not present), this application uses pass-by-value semantics.
- If true, this application uses pass-by-reference semantics.
When a servlet or enterprise bean calls a remote interface method in another bean that is co-located within the same process, by default the Sun Java System Application Server makes copies of all the call parameters in order to preserve the pass-by-value semantics. This increases the call overhead and decreases performance.
However, if the calling method does not mutate the object being passed as a parameter, it is safe to pass the object itself without making a copy of it. To do this, set the pass-by-reference value to true.
To apply pass-by-reference semantics to an entire J2EE application containing multiple EJB modules, you can set the same element in the sun-application.xml file. If you want to use pass-by-reference at both the bean and application level, the bean level takes precedence. For information about the sun-application.xml file, see the Sun Java System Application Server Developer’s Guide.
Subelements
none
res-ref-name
Specifies the res-ref-name in the corresponding J2EE ejb-jar.xml file resource-ref entry. The res-ref-name element specifies the name of a resource manager connection factory reference. The name is a JNDI name relative to the java:comp/env context. The name must be unique within an enterprise bean.
Subelements
none
Example
<res-ref-name>jdbc/SimpleBank</res-ref-name>
resource-env-ref
Maps the resource-env-ref-name in the corresponding J2EE ejb-jar.xml file resource-env-ref entry to an absolute jndi-name in the resources element in the server.xml file. The resource-env-ref element contains a declaration of an enterprise bean's reference to an administered object associated with a resource in the bean's environment.
Used in entity, message-driven, and session beans.
Subelements
The following table describes subelements for the resource-env-ref element.
Example
<resource-env-ref>
<resource-env-ref-name>
jms/StockQueueName
</resource-env-ref-name>
<jndi-name>jms/StockQueue</jndi-name>
</resource-env-ref>resource-env-ref-name
Specifies the resource-ref-name in the corresponding J2EE ejb-jar.xml file resource-env-ref entry. The resource-env-ref-name element specifies the name of a resource environment reference; its value is the environment entry name used in the EJB code. The name is a JNDI name relative to the java:comp/env context and must be unique within an enterprise bean.
Subelements
none
Example
<resource-env-ref-name>jms/StockQueue</resource-env-ref-name>
resource-ref
Maps the res-ref-name in the corresponding J2EE ejb-jar.xml file resource-ref entry to the absolute jndi-name in the resources element in the server.XML file. The resource-ref element contains a declaration of an EJB’s reference to an external resource. Used in entity, message-driven, and session beans.
Subelements
The following table describes subelements for the resource-ref element.
Example
<resource-ref>
<res-ref-name>jdbc/EmployeeDBName</res-ref-name>
<jndi-name>jdbc/EmployeeDB</jndi-name>
</resource-ref>Messaging Elements
This section contains the following elements associated with messaging:
jms-durable-subscription-name
Specifies the durable subscription associated with a message-driven bean class. Only applies to the Java Message Service Topic Destination type, and only when the message-driven bean deployment descriptor subscription durability is Durable.
Subelements
none
jms-max-messages-load
Specifies the maximum number of messages to load into a Java Message Service session at one time for a message-driven bean to serve. The default is 1.
Subelements
none
mdb-connection-factory
Specifies the connection factory associated with a message-driven bean. Queue or Topic type must be consistent with the Java Message Service Destination type associated with the message-driven bean class.
Subelements
The following table describes subelements for the mdb-connection-factory element.
Security Elements
This section describes the elements that are associated with authentication, authorization, and general security. The following elements are included:
as-context
Specifies the authentication mechanism that will be used to authenticate the client. If specified, it will be USERNAME_PASSWORD.
Subelements
The following table describes subelements for the as-context element.
auth-method
Specifies the authentication method. The only supported value is USERNAME_PASSWORD.
Subelements
none
caller-propagation
Specifies if the target will accept propagated caller identities. The values are NONE, SUPPORTED, or REQUIRED.
Subelements
none
confidentiality
Specifies if the target supports privacy-protected messages. The values are NONE, SUPPORTED, or REQUIRED.
Subelements
none
default-resource-principal
Specifies the default sign-on (name/password) to the resource manager.
Subelements
The following table describes subelements for the default-resource-principal element.
establish-trust-in-client
Specifies if the target is capable of authenticating a client. The values are NONE, SUPPORTED, or REQUIRED.
Subelements
none
establish-trust-in-target
Specifies if the target is capable of authenticating to a client. The values are NONE, SUPPORTED, or REQUIRED.
Subelements
none
integrity
Specifies if the target supports integrity-protected messages. The values are NONE, SUPPORTED, or REQUIRED.
Subelements
none
ior-security-config
Specifies the security information for the input-output redirection (IOR).
Subelements
The following table describes subelements for the ior-security-config element.
name
Specifies an identity.
Subelements
none
password
Specifies the password that security needs to complete authentication.
Subelements
none
realm
Specifies the realm in which the user is authenticated.
Subelements
none
required
Specifies if the authentication method specified is required to be used for client authentication. If so, the EstablishTrustInClient bit will be set in the target_requires field of as-context. The value is either true or false.
Subelements
none
sas-context
Describes the sas-context fields.
Subelements
The following table describes subelements for the sas-context element.
Table 8-15 sas-context Subelements
Subelement
Required
Description
only one
Specifies if the target will accept propagated caller identities. The values are NONE, SUPPORTED, or REQUIRED.
transport-config
Specifies the security transport information.
Subelements
The following table describes subelements for the transport-config element.
Persistence Elements
This section describes the elements associated with container-managed persistence (CMP), the persistence manager, and the persistence vendor. For information on using these elements, refer to Using Container-Managed Persistence.
The following elements are included:
checkpointed-methods
Specifies a user-defined semicolon-separated list of method signatures. Used only for stateful session beans. These methods can be an SFSB’s non-transactional business methods or create() methods. At the end of invocation of each of these methods, the bean’s state is checkpointed. For details, see “Specifying SFSB Methods to Be Checkpointed” on page 59.
Subelements
none
cmp
Describes runtime information for a container-managed persistence (CMP) entity bean object for EJB1.1 and EJB2.0 beans. This is a pointer to a file that describes the mapping information of a bean.
Subelements
The following table describes subelements for the cmp element.
cmp-resource
Specifies the database to be used for storing container-managed persistence (CMP) beans in an EJB JAR file.
Subelements
The following table describes subelements for the cmp-resource element.
Table 8-18 cmp-resource Subelements
Subelement
Required
Description
only one
Specifies the absolute jndi-name.
zero or one
Specifies the default runtime bindings of a resource reference.
concrete-impl
Specifies the location of the persistence vendor’s specific concrete class name.
Subelements
none
finder
Describes the finders for container-managed persistence 1.1 with a method name and query.
Subelements
The following table describes subelements for the finder element.
is-one-one-cmp
Specifies the boolean specifics for container-managed persistence 1.1. Used to identify CMP 1.1 with old descriptors.
Subelements
none
mapping-properties
Specifies the location of the persistence vendor’s specific object-to-relational (O/R) database mapping file. Most persistence vendors use the concept of a project, which represents all the related beans and their dependent classes, and can be deployed as a single unit. There can be a vendor-specific XML file associated with the project.
Subelements
none
method-name
Specifies the method name for the query field. The method-name element contains a name of an EJB method or the asterisk (*) character. The asterisk is used when the element denotes all the methods of an EJB's component and home interfaces.
Examples
<method-name>create</method-name>
<method-name>*</method-name>
Subelements
none
one-one-finders
Describes the finders for container-managed persistence (CMP) 1.1.
Subelements
The following table describes subelements for the one-one-finders element.
Table 8-20 one-one-finders Subelements
Subelement
Required
Description
one or more
Describes the finders for container-managed persistence (CMP) 1.1 with a method name and query.
pc-class
Specifies the persistence vendor’s specific class.
Subelements
none
pm-class-generator
Specifies which vendor-specific concrete class generator is to be used. This is the name of the class specific to the vendor.
Subelements
none
pm-config
Specifies the vendor-specific configuration file to be used.
Subelements
none
pm-descriptor
Describes the properties of the persistence manager associated with an entity bean.
Subelements
The following table describes subelements for the pm-descriptor element.
pm-descriptors
Describes the persistence manager descriptors. One of them must be in use at a given time. This basically applies to Sun Java System Application Server pluggable persistence manager APIs.
Subelements
The following table describes subelements for the pm-descriptors element.
pm-identifier
Specifies the vendor who provided the persistence manager implementation. For example, this could be Sun Java System Application Server container-managed persistence or a third-party vendor.
Subelements
none
pm-inuse
Specifies whether this particular persistence manager must be used or not.
Subelements
The following table describes subelements for the pm-inuse element.
pm-mapping-factory
Specifies which vendor-specific mapping factory is to be used. This is the name of the class specific to the vendor.
Subelements
none
pm-version
Specifies which version of the persistence manager vendor product is to be used.
Subelements
none
query-filter
Specifies the query filter for the container-managed persistence 1.1 finder. Optional.
Subelements
none
query-params
Specifies the query parameters for the container-managed persistence 1.1 finder.
Subelements
none
query-variables
Specifies variables in query expression for the container-managed persistence 1.1 finder. Optional.
Subelements
none
Pooling and Caching Elements
This section describes the elements associated with cache, timeout, and the EJB pool. These elements are used to control memory usage and performance tuning. For more information, refer to the Sun Java System Application Server Performance Tuning Guide.
The following elements are discussed:
bean-cache
Specifies the entity bean cache properties. Used for entity beans and stateful session beans.
Subelements
The following table describes subelements for the bean-cache element.
Example
<bean-cache>
<max-cache-size>100</max-cache-size>
<cache-resize-quantity>10</cache-resize-quantity>
<removal-timeout-in-seconds>3600</removal-timeout-in-seconds>
<victim-selection-policy>LRU</victim-selection-policy>
<cache-idle-timeout-in-seconds>
600
</cache-idle-timeout-in-seconds>
<removal-timeout-in-seconds>5400</removal-timeout-in-seconds>
</bean-cache>bean-pool
Specifies the pool properties of stateless session beans, entity beans, and message-driven bean.
Subelements
The following table describes subelements for the bean-pool element.
Example
<bean-pool>
<steady-pool-size>10</steady-pool-size>
<resize-quantity>10</resize-quantity>
<max-pool-size>100</max-pool-size>
<pool-idle-timeout-in-seconds>600</pool-idle-timeout-in-seconds>
</bean-pool>cache-idle-timeout-in-seconds
Optionally specifies the maximum time that a bean can remain idle in the cache. After this amount of time, the container can passivate this bean. A value of 0 specifies that beans may never become candidates for passivation. Default is 600.
Applies to stateful session beans and entity beans.
Subelements
none
commit-option
Optionally specifies the commit option that will be used on transaction completion. Valid values for the Sun Java System Application Server are B or C. Default value is B.
Applies to entity beans.
Subelements
none
Example
<commit-option>B</commit-option>
is-cache-overflow-allowed
This element is deprecated and should not be used.
max-cache-size
Optionally specifies the maximum number of beans allowable in cache. A value of zero indicates an unbounded cache. In reality, there is no hard limit. The max-cache-size limit is just a hint to the cache implementation. Default is 512.
Applies to stateful session beans and entity beans.
Subelements
none
Example
max-cache-size>100</max-cache-size>
max-pool-size
Optionally specifies the maximum number of bean instances in the pool. Values are from 0 (1 for message-driven bean) to MAX_INTEGER. A value of 0 means the pool is unbounded. Default is 64.
Applies to all beans.
Subelements
none
Example
<max-pool-size>100</max-pool-size>
max-wait-time-in-millis
This element is deprecated and should not be used.
pool-idle-timeout-in-seconds
Optionally specifies the maximum time, in seconds, that a bean instance is allowed to remain idle in the pool. When this timeout expires, the bean instance in a pool becomes a candidate for passivation or deletion. This is a hint to the server. A value of 0 specifies that idle beans can remain in the pool indefinitely. Default value is 600.
Applies to stateless session beans, entity beans, and message-driven beans.
Note
For a stateless session bean or a message-driven bean, the bean can be removed (garbage collected) when the timeout expires.
Subelements
none
Example
<pool-idle-timeout-in-seconds>600</pool-idle-timeout-in-seconds>
removal-timeout-in-seconds
Optionally specifies the amount of time a bean instance can remain idle in the container before it is removed (timeout). A value of 0 specifies that the container does not remove inactive beans automatically. The default value is 5400.
If removal-timeout-in-seconds is less than or equal to cache-idle-timeout-in-seconds, beans are removed immediately without being passivated.
Applies to stateful session beans.
For related information, see cache-idle-timeout-in-seconds.
Subelements
none
Example
<removal-timeout-in-seconds>3600</removal-timeout-in-seconds>
resize-quantity
Optionally specifies the number of bean instances to be:
- Created, if a request arrives when the pool has less than steady-pool-size quantity of beans (applies to pools only for creation). If the pool has more than steady-pool-size minus resize-quantity of beans, then resize-quantity is still created.
- Removed, when the pool-idle-timeout-in-seconds timer expires and a cleaner thread removes any unused instances.
- For caches, when max-cache-size is reached, resize-quantity beans will be selected for passivation using victim-selection-policy. In addition, the cache-idle-timeout-in-seconds or cache-remove-timeout-in-seconds timers will passivate beans from the cache.
- For pools, when the max-pool-size is reached, resize-quantity beans will be selected for removal. In addition the pool-idle-timeout-in-seconds timer will remove beans until steady-pool-size is reached.
Values are from 0 to MAX_INTEGER. The pool is not resized below the steady-pool-size. Default is 16.
Applies to stateless session beans, entity beans, and message-driven beans.
For EJB pools, the default value can be the value of the ejb-container element pool-resize-quantity in the server.xml file. Default is 16.
For EJB caches, the default value can be the value of the ejb-container element cache-resize-quantity in the server.xml file. Default is 32.
For message-driven beans, the default can be the value of the mdb-container pool-resize-quantity element in the server.xml file. Default is 2.
Subelements
none
Example
<resize-quantity>10</resize-quantity>
steady-pool-size
Optionally specifies the initial and minimum number of bean instances that should be maintained in the pool. Default is 32.
Applies to stateless session beans and message-driven beans.
Subelements
none
Example
<steady-pool-size>10</steady-pool-size>
victim-selection-policy
Optionally specifies how stateful session beans are selected for passivation. Possible values are First In, First Out (FIFO), Least Recently Used (LRU), Not Recently Used (NRU). The default value is NRU, which is actually pseudo-LRU.
The victims are generally passivated into a backup store (typically a file system or database). This store is cleaned during startup, and also by a periodic background process that removes idle entries as specified by removal-timeout-in-seconds. The backup store is monitored by a background thread (or sweeper thread) to remove unwanted entries.
Applies to stateful session beans.
Subelements
none
Example
<victim-selection-policy>LRU</victim-selection-policy>
Class Elements
This section describes the elements associated with classes. The following elements are included:
gen-classes
Specifies all the generated class names for a bean.
Note
This is automatically generated by the server at deployment/redeployment time. It should not be specified by the developer or changed after deployment.
Subelements
The following table describes subelements for the gen-class element.
local-home-impl
Specifies the fully-qualified class name of the generated EJBLocalHome impl class.
Note
This is automatically generated by the server at deployment/redeployment time. It should not be specified by the developer or changed after deployment.
Subelements
none
local-impl
Specifies the fully-qualified class name of the generated EJBLocalObject impl class.
Note
This is automatically generated by the server at deployment/redeployment time. It should not be specified by the developer or changed after deployment.
Subelements
none
remote-home-impl
Specifies the fully-qualified class name of the generated EJBHome impl class.
Note
This is automatically generated by the server at deployment/redeployment time. It should not be specified by the developer or changed after deployment.
Subelements
none
remote-impl
Specifies the fully-qualified class name of the generated EJBObject impl class.
Note
This is automatically generated by the server at deployment/redeployment time. It should not be specified by the developer or changed after deployment.
Subelements
none
Sample EJB XML FilesThis section includes the following sample files:
For information on the elements associated with enterprise beans, refer to Elements in the sun-ejb-jar.xml File and the Sun Java System Application Server Developer’s Guide.
Sample ejb-jar.xml File
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ejb-jar PUBLIC '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN' 'http://java.sun.com/dtd/ejb-jar_2_0.dtd'>
<ejb-jar>
<description>no description</description>
<display-name>CustomerJAR</display-name>
<enterprise-beans>
<entity>
<description>no description</description>
<display-name>CustomerEJB</display-name>
<ejb-name>CustomerEJB</ejb-name>
<home>samples.SimpleBankBMP.ejb.CustomerHome</home>
<remote>samples.SimpleBankBMP.ejb.Customer</remote>
<ejb-class>samples.SimpleBankBMP.ejb.CustomerEJB</ejb-class>
<persistence-type>Bean</persistence-type>
<prim-key-class>java.lang.String</prim-key-class>
<reentrant>False</reentrant>
<security-identity>
<description></description>
<use-caller-identity></use-caller-identity>
</security-identity>
<resource-ref>
<res-ref-name>jdbc/SimpleBank</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>Container</res-auth>
<res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>
</entity>
</enterprise-beans
<assembly-descriptor>
<container-transaction>
<method>
<ejb-name>CustomerEJB</ejb-name>
<method-name>*</method-name>
</method>
<trans-attribute>NotSupported</trans-attribute>
</container-transaction>
</assembly-descriptor>
</ejb-jar>Sample sun-ejb-jar.xml File
For information on these elements, refer to Elements in the sun-ejb-jar.xml File.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sun-ejb-jar PUBLIC '-//Sun Microsystems, Inc.//DTD Sun ONE Application Server 7.1 EJB 2.0//EN' 'http://www.sun.com/software/sunone/appserver/dtds/sun-ejb-jar_2_0-0.dtd'>
<sun-ejb-jar>
<display-name>First Module</display-name>
<enterprise-beans>
<ejb>
<ejb-name>CustomerEJB</ejb-name>
<jndi-name>customer</jndi-name>
<resource-ref>
<res-ref-name>jdbc/SimpleBank</res-ref-name>
‘ <jndi-name>jdbc/PointBase</jndi-name>
</resource-ref>
<is-read-only-bean>false</is-read-only-bean>
<commit-option>B</commit-option>
<bean-pool>
<steady-pool-size>10</steady-pool-size>
<resize-quantity>10</resize-quantity>
<max-pool-size>100</max-pool-size>
<pool-idle-timeout-in-seconds>600</pool-idle-timeout-in-seconds>
</bean-pool>
<bean-cache>
<max-cache-size>100</max-cache-size>
<resize-quantity>10</resize-quantity>
<removal-timeout-in-seconds>3600</removal-timeout-in-seconds>
<victim-selection-policy>LRU</victim-selection-policy>
</bean-cache>
</ejb>
</enterprise-beans>
</sun-ejb-jar>