Sun Java System Application Server Platform Edition 9 Application Deployment Guide

E

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, ior-security-config, gen-classes, jndi-name, use-thread-pool-id, message-destination-ref, pass-by-reference, service-ref
Stateless session beans: bean-pool, webservice-endpoint
Entity beans: commit-option, bean-cache, bean-pool, cmp, is-read-only-bean, refresh-period-in-seconds, flush-at-end-of-method
Message-driven beans: mdb-resource-adapter, mdb-connection-factory, jms-durable-subscription-name, jms-max-messages-load, bean-pool

Superelements

enterprise-beans (sun-ejb-jar.xml)

Subelements

The following table describes subelements for the ejb element.

Table A–40 ejb Subelements


Element	Required	Description
ejb-name	only one	Matches the `ejb-name` in the corresponding `ejb-jar.xml` file.
jndi-name	zero or more	Specifies the absolute `jndi-name`.
ejb-ref	zero or more	Maps the absolute JNDI name to the `ejb-ref` element in the corresponding Java EE XML file.
resource-ref	zero or more	Maps the absolute JNDI name to the `resource-ref` in the corresponding Java EE XML file.
resource-env-ref	zero or more	Maps the absolute JNDI name to the `resource-env-ref` in the corresponding Java EE XML file.
service-ref	zero or more	Specifies runtime settings for a web service reference.
message-destination-ref	zero or more	Specifies the name of a physical message destination.
pass-by-reference	zero or one	Specifies the passing method used by an enterprise bean calling a remote interface method in another bean that is colocated within the same process.
cmp	zero or one	Specifies runtime information for a container-managed persistence (CMP) entity bean for EJB 1.1 and EJB 2.1 beans.
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	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	Specifies that this entity bean is read-only.
refresh-period-in-seconds	zero or one	Specifies the rate at which a read-only-bean must be refreshed from the data source.
commit-option	zero or one	Has valid values of B or C. Default value is B.
cmt-timeout-in-seconds	zero or one	Overrides the Transaction Timeout setting of the Transaction Service for an individual bean.
use-thread-pool-id	zero or one	Specifies the thread pool from which threads are selected for remote invocations of this bean.
gen-classes	zero or one	Specifies all the generated class names for a bean.
bean-pool	zero or one	Specifies the bean pool properties. Used for stateless session beans, entity beans, and message-driven beans.
bean-cache	zero or one	Specifies the bean cache properties. Used only for stateful session beans and entity beans.
mdb-resource-adapter	zero or one	Specifies runtime configuration information for a message-driven bean.
webservice-endpoint	zero or more	Specifies information about a web service endpoint.
flush-at-end-of-method	zero or one	Specifies the methods that force a database flush after execution. Used for entity beans.
checkpointed-methods	zero or one	Enterprise Edition only. Do not use.
checkpoint-at-end-of-method	zero or one	Enterprise Edition only. Do not use.

Attributes

The following table describes attributes for the ejb element.

Table A–41 ejb Attributes


Attribute	Default	Description
`availability-enabled`	`false`	(optional)Enterprise Edition only. Do not use.

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/__default</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

In the sun-ejb-jar.xml file, matches the ejb-name in the corresponding ejb-jar.xml file. 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 assigns to the EJB component’s home.

In the sun-cmp-mappings.xml file, specifies the ejb-name of the entity bean in the ejb-jar.xml file to which the container-managed persistence (CMP) bean corresponds.

Superelements

ejb, method (sun-ejb-jar.xml); entity-mapping (sun-cmp-mappings.xml)

Subelements

none - contains data

ejb-ref

Maps the ejb-ref-name in the corresponding Java EE deployment descriptor file ejb-ref entry to the absolute jndi-name of a resource.

The ejb-ref element is used for the declaration of a reference to an EJB’s home. Applies to session beans or entity beans.

Superelements

sun-web-app (sun-web.xml), ejb (sun-ejb-jar.xml), sun-application-client (sun-application-client.xml)

Subelements

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

Table A–42 ejb-ref Subelements


Element	Required	Description
ejb-ref-name	only one	Specifies the `ejb-ref-name` in the corresponding Java EE deployment descriptor file `ejb-ref` entry.
jndi-name	only one	Specifies the absolute `jndi-name` of a resource.

ejb-ref-name

Specifies the ejb-ref-name in the corresponding Java EE deployment descriptor file ejb-ref entry.

Superelements

ejb-ref (sun-web.xml, sun-ejb-jar.xml, sun-application-client.xml)

Subelements

none - contains data

eligible

Specifies whether the application client module is eligible to be Java Web Start enabled. Allowed values are true (the default) and false.

Superelements

java-web-start-access (sun-application-client.xml)

Subelements

none - contains data

endpoint-address-uri

Specifies the relative path combined with the web server root to form the fully qualified endpoint address for a web service endpoint. This is a required element for EJB endpoints and an optional element for servlet endpoints.

For servlet endpoints, this value is relative to the web application context root. For EJB endpoints, the URI is relative to root of the web server (the first portion of the URI is a context root). The context root portion must not conflict with the context root of any web application deployed to the same web server.

In all cases, this value must be a fixed pattern (no ”*’ allowed).

If the web service endpoint is a servlet that implements only a single endpoint and has only one url-pattern, it is not necessary to set this value, because the web container derives it from the web.xml file.

Superelements

webservice-endpoint (sun-web.xml, sun-ejb-jar.xml)

Subelements

none - contains data

Example

If the web server is listening at http://localhost:8080, the following endpoint-address-uri:

<endpoint-address-uri>StockQuoteService/StockQuotePort</endpoint-address-uri>

results in the following target endpoint address:

http://localhost:8080/StockQuoteService/StockQuotePort

enterprise-beans

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

Superelements

sun-ejb-jar (sun-ejb-jar.xml)

Subelements

The following table describes subelements for the enterprise-beans element.

Table A–43 enterprise-beans Subelements


Element	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. Do not specify or edit this value.
ejb	zero or more	Defines runtime properties for a single enterprise bean within the application.
pm-descriptors	zero or one	Deprecated.
cmp-resource	zero or one	Specifies the database to be used for storing container-managed persistence (CMP) beans in an EJB JAR file.
message-destination	zero or more	Specifies the name of a logical message destination.
webservice-description	zero or more	Specifies a name and optional publish location for a web service.

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/__default</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>

entity-mapping

Specifies the mapping a bean to database columns.

Superelements

sun-cmp-mapping (sun-cmp-mappings.xml)

Subelements

The following table describes subelements for the entity-mapping element.

Table A–44 entity-mapping Subelements


Element	Required	Description
ejb-name	only one	Specifies the name of the entity bean in the `ejb-jar.xml` file to which the CMP bean corresponds.
table-name	only one	Specifies the name of a database table. The table must be present in the database schema file.
cmp-field-mapping	one or more	Associates a field with one or more columns to which it maps.
cmr-field-mapping	zero or more	A container-managed relationship field has a name and one or more column pairs that define the relationship.
secondary-table	zero or more	Describes the relationship between a bean’s primary and secondary table.
consistency	zero or one	Specifies container behavior in guaranteeing transactional consistency of the data in the bean.

establish-trust-in-client

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

Superelements

transport-config (sun-ejb-jar.xml)

Subelements

none - contains data

establish-trust-in-target

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

Superelements

transport-config (sun-ejb-jar.xml)

Subelements

none - contains data