Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java System Application Server Standard and Enterprise Edition 7 2004Q2 Developer's Guide to Enterprise JavaBeans Technology 

Chapter 8
Assembling and Deploying Enterprise Beans

This 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.


Note

For general assembly and deployment information, see the Sun Java System Application Server Developer’s Guide.You should already be familiar with that deployment material before proceeding with EJB assembly.


This section contains the following topics:

An alphabetical list of all EJB-related elements is contained in Elements Listings.


EJB Structure

The 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 Descriptors

A 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:

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.


Note

You can create the deployment descriptor manually if you prefer.


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 Beans

When 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:

  1. Open the Applications component under your server instance.
  2. Go to the Enterprise Apps or EJB Modules page.
  3. Click on the Deploy button. (You can also undeploy, enable, or disable an application or module from this page.)
  4. 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.
  5. Enter the module or application name.
  6. Assign the application or web module to one or more virtual servers by checking the boxes next to the virtual server names.
  7. You can also redeploy the module or application if it already exists (called forced deployment) by checking the appropriate box. This is optional.
  8. You can run the verifier to check your deployment descriptor files. This is optional. For details about the verifier, see the Developer’s Guide.
  9. 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).
  10. Other fields are displayed depending on the type of module. Check appropriate boxes and enter appropriate values. Required fields are marked with asterisks (*).
  11. Click on the OK button.
  12. Restart the server if you are redeploying and have changed settings in Step 9 or Step 10.

  13. Note

    The Availability Enabled setting is in the Sun Java System Application Server Enterprise Edition only.


Using the Command-Line Interface

To deploy an enterprise bean using the command line:

  1. Edit the deployment descriptor files (ejb-jar.xml and sun-ejb-jar.xml) by hand.
  2. Execute an Ant build command (such as build jar) to reassemble the JAR module.
  3. 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:
  4. 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.


Note

In Sun ONE Studio 5, deploying a web application is referred to as executing it.


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:

  1. In the Administration interface, select your server instance
  2. Select Applications.
  3. The Application Properties page is displayed.

  4. Check the Reload Enabled box to enable dynamic reloading.
  5. 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.
  6. 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:

  1. Create an empty file named .reload at the root of the deployed application:
  2. instance_dir/applications/j2ee-apps/app_name/.reload

  1. Explicitly update the .reload file’s timestamp (touch .reload in UNIX) each time you make changes to the bean or deployment descriptor.
  2. 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 Structure

The 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:

http://www.w3.org/TR/REC-xml

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.

Table 8-1  Requirement Rules for Subelement Suffixes 

Suffix

Number of Occurrences

element*

Can contain zero or more of this subelement.

?element

Can contain zero or one of this subelement.

element+

Must contain one or more of this subelement.

element (no suffix)

Must contain only one of this subelement.

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 File

An 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:

Subelements

The following table describes subelements for the ejb element.

Table 8-2  ejb Subelements 

Subelement

Required

Description

ejb-name

only one

Matches the display name of the bean to which it refers.

jndi-name

zero or more

Specifies the absolute jndi-name. In the case of message-driven beans, this is the JNDI name of the Java Message Service Queue or Topic destination resource object associated with the message-driven bean class. Whether it is Queue or Topic type depends on the destination type in the message-driven deployment descriptor message-driven-destination. If no message-driven-destination deployment descriptor is specified, this defaults to Queue type.

ejb-ref

zero or more

Maps the absolute JNDI name to the ejb-ref element in the corresponding J2EE XML file.

resource-ref

zero or more

Maps the absolute JNDI name to the resource-ref in the corresponding J2EE XML file.

resource-env-ref

zero or more

Maps the absolute JNDI name to the resource-env-ref in the corresponding J2EE XML file.

pass-by-reference

zero or one

When a servlet or EJB calls another bean that is co-located within the same process, the Sun Java System Application Server does not automatically perform marshalling of all call parameters.

cmp

zero or one

Specifies runtime information for a container-managed persistence (CMP) EntityBean object for EJB1.1 and EJB2.0 beans. This is a pointer to a file that describes the mapping information of a bean.

principal

zero or one

Specifies the principal (user) name in an enterprise bean that has the run-as role specified.

mdb-connection-factory

zero or one

Specifies the connection factory associated with a message-driven bean.

jms-durable-subscription-name

zero or one

Contains data that specifies the durable subscription associated with a message-driven bean.

jms-max-messages-load

zero or one

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.

ior-security-config

zero or one

Specifies the security information for the IOR.

is-read-only-bean

zero or one

Flag specifying this bean is a read-only bean.

refresh-period-in-seconds

zero or one

Specifies the rate at which a read-only-bean must be refreshed from the data source. If this is less than or equal to zero, the bean is never refreshed; if greater than zero, the bean instances are refreshed at the specified interval. This rate is just a hint to the container. Default is 600.

commit-option

zero or one

Contains data that has valid values of A, B, or C. Default value is B.

gen-classes

zero or one

Specifies all the generated class names for a bean.

bean-pool

zero or one bean-pool

Specifies the bean pool properties. Used for stateless session beans, entity beans, and message-driven bean pools.

bean-cache

zero or one bean-pool

Specifies the bean cache properties. Used only for stateful session beans and entity beans

checkpointed-methods

zero or one

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 about checkpointing, see .

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.

Table 8-4  enterprise-beans Subelements 

Subelement

Required

Description

name

zero or one

Specifies the name string.

unique-id

zero or one

Specifies a unique system identifier. This data is automatically generated and updated at deployment/redeployment.

ejb

zero or more

Defines runtime properties for a single enterprise bean within the application.

pm-descriptors

zero or one

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.

cmp-resource

zero or one

Specifies the database to be used for storing container-managed persistence (CMP) beans in an EJB JAR file.

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-beans

is-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.

Table 8-5  sun-ejb-jar Subelements 

Subelement

Required

Description

security-role-mapping

zero or more

Maps a role in the corresponding J2EE XML file to a user or group.

enterprise-beans

only one

Describes all the runtime properties for an EJB JAR file in the application.

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

name

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.

Table 8-7  security-role-mapping Subelements 

Subelement

Required

Description

role-name

only one

Specifies the role-name from the ejb-jar.xml file being mapped.

principal-name

requires at least one principal-name or group-name

Specifies the principal (user) name in a bean that has the run-as role specified.

group-name

requires at least one principal-name or group-name

Specifies the group name.

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

ejb-ref-name

only one

Specifies the ejb-ref-name in the corresponding J2EE EJB JAR file ejb-ref entry.

jndi-name

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.

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.

Table 8-9   resource-env-ref Subelements 

Subelement

Required

Description

resource-env-ref-name

only one

Specifies the resource-env-ref-name in the corresponding J2EE ejb-jar.xml file resource-env-ref entry.

jndi-name

only one

Specifies the absolute jndi-name.

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.


Note

Connections acquired from JMS connection factories are not shareable in the current release of the Sun Java System Application Server. The res-sharing-scope element in the ejb-jar.xml file resource-ref element is ignored for JMS connection factories.

When resource-ref specifies a JMS connection factory for the Sun Java System Message Queue, the default-resource-principal (name/password) must exist in the Sun Java System Message Queue user repository. Refer to the Security Management chapter in the Sun Java System Message Queue Administrator's Guide for information on how to manage the Sun Java System Message Queue user repository.


Subelements

The following table describes subelements for the resource-ref element.

Table 8-10  resource-ref Subelements 

Subelement

Required

Description

res-ref-name

only one

Specifies the res-ref-name in the corresponding J2EE ejb-jar.xml file resource-ref entry.

jndi-name

only one

Specifies the absolute jndi-name.

default-resource-principal

zero or one

Specifies the default sign-on (name/password) to the resource manager.

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.

Table 8-11   mdb-connection-factory Subelements 

Subelement

Required

Description

jndi-name

only one

Specifies the absolute jndi-name.

default-resource-principal

zero or one

Specifies the default sign-on (name/password) to the resource manager.

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.

Table 8-12   as-context Subelements 

Subelement

Required

Description

auth-method

only one

Specifies the authentication method. The only supported value is USERNAME_PASSWORD.

realm

only one

Specifies the realm in which the user is authenticated.

required

only one

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.

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.

Table 8-13   default-resource-principal Subelements 

Subelement

Required

Description

name

only one

Specifies the default resource principal name used to sign on to a resource manager.

password

only on

Specifies password of the default resource principal.

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.

Table 8-14   ior-security-config Subelements 

Subelement

Required

Description

transport-config

zero or one

Specifies the security information for transport.

as-context

zero or one

Describes the authentication mechanism that will be used to authenticate the client. If specified, it will be USERNAME_PASSWORD.

sas-context

zero or one

Describes the sas-context fields.

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

caller-propagation

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.

Table 8-16   transport-config Subelements 

Subelement

Required

Description

integrity

only one

Specifies if the target supports integrity-protected messages. The values are NONE, SUPPORTED, or REQUIRED.

confidentiality

only one

Specifies if the target supports privacy-protected messages. The values are NONE, SUPPORTED, or REQUIRED.

establish-trust-in-target

only one

Specifies if the target is capable of authenticating to a client. The values are NONE, SUPPORTED, or REQUIRED.

establish-trust-in-client

only one

Specifies if the target is capable of authenticating a client. The values are NONE, SUPPORTED, or REQUIRED.

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.

Table 8-17   cmp Subelements 

Subelement

Required

Description

mapping-properties

only one

Contains data that specifies the location of the persistence vendor’s specific object-to-relational (O/R) database mapping file.

concrete-impl

only one

Contains data that specifies the location of the persistence vendor’s specific concrete class name.

pc-class

zero or one

Contains data that specifies the persistence vendor’s specific class.

is-one-one-cmp

zero or one

Contains the boolean specifics for container-managed persistence (CMP) 1.1. Used to identify CMP 1.1 with old descriptors.

one-one-finders

zero or one

Describes the finders for container-managed persistence (CMP) 1.1.

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

jndi-name

only one

Specifies the absolute jndi-name.

default-resource-principall

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.

Table 8-19   finder Subelements 

Subelement

Required

Description

method-name

only one

Specifies the method name for the query field.

query-params

only one

Optional data that specifies the query parameters for the container-managed persistence (CMP) 1.1 finder.

query-filter

only one

Specifies the query filter for the container-managed persistence (CMP) 1.1 finder.

query-variables

only one

Optional data that specifies variables in query expression for the container-managed persistence 1.1 finder.

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

finder

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.

Table 8-21  pm-descriptor Subelements 

Subelement

Required

Description

pm-identifier

only one

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.

pm-version

only one

Specifies which version of the persistence manager vendor product is to be used.

pm-config

zero or one

Specifies the vendor-specific configuration file to be used.

pm-config

zero or one

Specifies which vendor-specific concrete class generator is to be used. This is the name of the class specific to the vendor.

pm-mapping-factory

zero or one

Specifies which vendor-specific mapping factory is to be used. This is the name of the class specific to the vendor.

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.

Table 8-22  pm-descriptors Subelements 

Subelement

Required

Description

pm-descriptor

one or more

Describes the properties of the persistence manager associated with an entity bean.

pm-inuse

only one

Specifies whether this particular persistence manager must be used or not.

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.

Table 8-23  pm-insue Subelements 

Subelement

Required

Description

pm-identifier

only one

Contains data that 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.

pm-version

only one

Contains data that specifies which version of the persistence manager vendor product is to be used.

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.

Table 8-24   bean-cache Subelements 

Subelement

Required

Description

max-cache-size

zero or one

Specifies the maximum number of beans allowable in cache.

is-cache-overflow-allowed

zero or one

Deprecated.

cache-idle-timeout-in-seconds

zero or one

Specifies the maximum time that a stateful session bean or entity bean is allowed to be idle in cache before being passivated. Default value is 10 minutes (600 seconds).

removal-timeout-in-seconds

zero or one

Specifies the amount of time a bean remains before being removed. If removal-timeout-in-seconds is less than idle-timeout, the bean is removed without being passivated.

resize-quantity

zero or one

Specifies the number of beans to be created if the pool is empty (subject to the max-pool-size limit). Values are from 0 to MAX_INTEGER.

victim-selection-policy

zero or one

Specifies the algorithm that must be used by the container to pick victims. Applies only to stateful session beans.

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.

Table 8-25   bean-pool Subelements 

Subelement

Required

Description

steady-pool-size

zero or one

Specifies the initial and minimum number of beans maintained in the pool. Default is 32.

resize-quantity

zero or one

Specifies the number of beans to be created if the pool is empty (subject to the max-pool-size limit). Values are from 0 to MAX_INTEGER.

max-pool-size

zero or one

Specifies the maximum number of beans in the pool. Values are from 0 to MAX_INTEGER. Default is to server.xml or 60.

max-wait-time-in-millis

zero or one

Deprecated.

pool-idle-timeout-in-seconds

zero or one

Specifies the maximum time that a bean is allowed to be idle in the pool. After this time, the bean is removed. This is a hint to the server. Default time is 600 seconds (10 minutes).

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.


Note

Commit option A is not supported for the Sun Java System Application Server 7.1 release.


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:

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.


Note

If steady-pool-size is set to a value greater than 0, the beans are created when the server starts. If a bean relies on caching information during the setInitialContext method that is not available at server startup (such as a user's security role), then the bean should throw EJBException during the setInitialContext. The container handles this exception and does not instantiate the beans. If the bean swollows this exception, then steady-pool-size should be set to 0 in the sun-ejb-jar.xml file.


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.


Note

The user cannot plug in his own victim selection algorithm.


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.

Table 8-26   gen-classes Subelements 

Subelement

Required

Description

remote-impl

zero or one

Specifies the fully-qualified class name of the generated EJBObject impl class.

local-impl

zero or one

Specifies the fully-qualified class name of the generated EJBLocalObject impl class.

remote-home-impl

zero or one

Specifies the fully-qualified class name of the generated EJBHome impl class.

local-home-impl

zero or one

Specifies the fully-qualified class name of the generated EJBLocalHome impl class.

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 Files

This 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>



Previous      Contents      Index      Next     


Copyright 2004 Sun Microsystems, Inc. All rights reserved.