Generating persistent.xml for Container-Managed Entity Beans 

Purpose

This process describes the automatic generation of the J2EE Engine-specific persistent.xml used to define the Object/Relational mapping of container-managed entity beans, which will be deployed on the J2EE Engine. It highlights some specifics and describes the usage of this function of the J2EE Engine.

persistent.xml specifies the mappings between your container-managed entity beans and the database tables, the database used by your application if your application is database-dependent (most applications are supposed to be database-independent), the SQL database-specific statements for finder methods, the database relationships, and so on.

Process Flow

The J2EE Engine provides several ways of generating persistent.xml – SAP NetWeaver Developer Studio, Deploy Tool and a shell command.

SAP NetWeaver Developer Studio

When you use SAP NetWeaver Developer Studio to develop your container-managed entity beans, the system automatically generates persistent.xml. When you specify the Object/Relational mapping (in the Development Manual) of your beans to database tables and columns, you must enter the values of the persistent.xml elements in the corresponding fields. You can browse the database tables if you have already defined them in the Java Dictionary (in the Development Manual), and choose which database tables and table columns you want to map your beans and their persistent fields to.

Deploy Tool

The Deploy Tool generates persistent.xml for your EJB application during assembling and/or deployment. This deployment descriptor contains the default O/R mapping according to the O/R mapping rules (in the Development Manual) for the J2EE Engine. You can change the default values of the persistent.xml elements in the corresponding fields in the Deploy Tool.

The Deploy Tool generates default mapping only if persistent.xml is not provided along with the application, that is, if the Deploy Tool generates persistent.xml. Otherwise, if the application contains persistent.xml and the mapping is already described in it, you can modify the data source name, the database vendor, the names of the database table and the help table, the names of column and foreign key columns, and the read-only state of the bean.

For more information, see Deploy Tool (in the Development Manual).

Console Administrator

You can manually generate persistent.xml, containing the default O/R mapping by using the GENERATE_PERSISTENT shell command from the EJB group of shell commands. If an old version of persistent.xml exists in the EAR file, this command will display a notification message and will not replace the old version. If you want to use the version generated by this shell command, you must first delete the old persistent.xml from your application EAR and then execute the shell command.

Recommendations

If you use this process to generate persistent.xml, note the following recommendations:

·        Specify the name of the data source used by your application

If you do not specify the data source name, the system will throw an exception.

·        Specify the name of the database vendor used by your application if the queries of the finder or select statements are database-dependent.

If you do not specify the name, the system will mark the database as unknown. That is, the <database-vendor> element will be omitted in persistent.xml. In this case, there are two options:

¡        If all EJB QL queries in your application can be parsed to SQL statements that are database-independent, your application will work as intended, despite the fact that you have omitted this property

¡        If some of the EJB QL queries in your application are parsed to SQL statements that are database-dependent and

§         if you have created the data source that your application will use before application deployment, the system will resolve the database type from the Connection object and your application will work as intended

§         if you have not created the data source that your application will use before application deployment, the system will throw an exception and the application will not be deployed

For more information about creating data sources, see Creating a DataSource with JDBC 1.x Driver or Creating a DataSource with JDBC 2.0 Driver (in the Development Manual).

Result

This process creates persistent.xml for each JAR file that is packed in the application’s EAR file and which contains container-managed entity beans. persistent.xml is stored in the corresponding META-INF directory of the JAR file.

 

See also:

persistent.dtd (in the Development Manual)

Creating and Editing the Deployment Descriptors (in the Development Manual)