9.6.3 Mapping CMP2.x and the database

(a) Attribute file to be edited

EJB-JAR attribute file

(b) Acquiring the attribute file to be edited and setting the attributes

• Acquiring the attribute file

  Execute the following command to acquire an EJB-JAR attribute file:

  Execution format

  cjgetappprop [server-name] [-nameserver provider-URL] -name J2EE application-name -type ejb -resname EJB-JAR-display-name -c path-of-the-EJB-JAR-attribute-file

  Example of execution

  cjgetappprop MyServer -name adder -type ejb -resname adder -c C:\home\adder_ejb.xml

• Setting the attributes

  Execute the following command to apply the values of the EJB-JAR attribute file:

  Execution format

  cjsetappprop [server-name] [-nameserver provider-URL] -name J2EE application-name -type ejb -resname EJB-JAR-display-name -c path-of-EJB-JAR-attribute-file

  Example of execution

  cjsetappprop MyServer -name adder -type ejb -resname adder -c C:\home\adder_ejb.xml

Note:

You can acquire the EJB-JAR attribute file that is included in a running application, but you cannot apply the relation information that is defined.

(c) Attribute settings to be edited

The following table describes the property settings that define the relationship between two CMP2.x Entity Beans (<relationships> - <ejb-relation>):

Items	Mandatory	Corresponding tags
Description	O	<description>
Relation definition name	Y	<ejb-relation-name>
Enterprise Bean(EJB1) information	Y	<ejb1>
Enterprise Bean(EJB2) information	Y	<ejb2>

For details on the property settings, see 3.3.1 Specifications of the HITACHI EJB-JAR Property file in the uCosminexus Application Server Application and Resource Definition Reference Guide.

For the Enterprise Bean (EJB1) information (<ejb1>) and Enterprise Bean (EJB2) information (<ejb2>), specify the items for the relationship between the Enterprise Bean on the setting side and the Enterprise Bean on the other side respectively.

Items	Mandatory	Corresponding tags
Description	O	<description>
Role name of relationship	O	<ejb-relationship-role-name>
Multiplicity of setting side	Y	<multiplicity>
Setting of cascade delete	Y	<cascade-delete>
<ejb-name> of setting side	Y	<ejb-name>
Name of CMR field	Y	<cmr-field-name>
Type of CMR field	O	<cmr-field-type>

For details on the property settings, see 3.3.1 Specifications of the HITACHI EJB-JAR Property file in the uCosminexus Application Server Application and Resource Definition Reference Guide.

(a) Attribute file to be edited

For the attribute file to be edited, see (1) Attribute file to be edited in 9.6.2 Mapping CMP1.x and the database.

(b) Acquiring the attribute file to be edited and setting the attributes

For details on acquiring the attribute file to be edited and setting the attributes, see (2) Acquiring the attribute file to be edited and setting the attributes in 9.6.2 Mapping CMP1.x and the database.

(c) Attribute settings to be edited

The following table describes the property settings for mapping the fields of a CMP2.x Entity Bean with a table in the database (<cmp-map>):

Items	Mandatory	Corresponding tags
Display name of the resource adapter	Y	<datasource-name>
Catalog name of the database	O	<catalog-name>
Schema name of the database	O	<schema-name>
Table name of the database	Y	<table-name>
Permission or prohibition of writing to the database	Y	<read-only-access>
Transaction isolation level#1	O	<transaction-isolation>
Method of comparing the data by writing to the database	O	<concurrency-protection>
Information of mapping between the field and the table column#2	Y	<field-impl>

#1

The value of the transaction isolation level (<transaction-isolation>) that can be used differs based on the option supported in the database and the JDBC driver.

#2

Set a column of the database table for the primary key. This column is also used for mapping the fields of the same database table.

The value of the field name of an EntityBean (<field-name>) cannot be changed. Set a database column (<column-name>) for mapping the field name of the Entity Bean (<field-name>).

The information about mapping between the fields and the table column (<field-impl>) consists of the following items:

Items	Corresponding tags
Field name of the EntityBean	<field-name>
Column name of the table	<column-name>

For details on the property settings, see 3.5.1 Specifications of the HITACHI Entity Bean Property file in the uCosminexus Application Server Application and Resource Definition Reference Guide.

(d) Notes

• The function for mapping the CMP field of an Entity Bean to multiple tables in the database is not provided.

• When the user specified in the DB Connector definition to be used for mapping and the owner of the database table that forms the CMP mapping destination, are different, the user specified in the DB Connector definition needs the following permissions:

  For mapping: SELECT

  For execution: SELECT, INSERT, UPDATE, DELETE

• When the mapping of the CMP fields is not complete and the application is running, an SQL statement cannot be generated.

• A table of two Beans forming a CMR relationship must be in the database of the same database product.

(a) Overview of tables for CMR

In the EJB container, if there is a CMR relationship between the CMP2.x Entity Beans, a table is created in the database and it is used for maintaining the CMR status.

As shown in the following figure, the primary keys of two Entity Beans that are related are stored in the table for CMR:

Figure 9‒1: Table for CMR (in the case of a one-to-one and a two-way relationship)

(b) Generating and deleting the tables for CMR

If an application that contains CMR is started, a table is generated for CMR. The table is generated in the schema that has the Bean1 table. This table is deleted when the application is stopped. For creating, deleting, and operating the tables, you use the SQL statement that is generated after database mapping when the application is customized.

If the server is stopped while the application is running, the table for CMR remains in the database. If the server is restarted while the application is running, the existence of the table for CMR in the database is checked. The following table describes the process of generating the table for CMR when an application and server are started:

Table 9‒4: Process for generating the table for CMR when an application and server are started

Status	Does a table with the same name as that of the table to be created exist in the database?	If a table with the same name exists, are the number of columns, name, and the JDBC type the same?	Operations	Message ID that is output
When starting#1	No	Not applicable	Generate and use the table.	KDJE43007-I
	Yes	Same or not the same	Startup is suspended.#2	KDJE43003-E
When starting the J2EE server	No	Not applicable	Startup is suspended.#3	KDJE43008-E
	Yes	Same	When starting, assume that the table has been created for CMR and use it.	KDJE43006-I
		Not the same	Startup is suspended.#3	KDJE43008-E

#1

This is in case of default, especially when the option, at the start of the application that contains CRM, is not set. For details on starting options, see (e) Restoring the table for CMR when a failure occurs.

#2

The application fails to start if a table with the same name already exists in the database. If the existing table is not required, either delete the table manually by using the tool provided in the database products or re-execute the process of generating the SQL statement. If you choose to re-execute the process of generating the SQL statement, the table is given a name that is not repeated in the database schema, and the SQL statement is generated again (Generate the SQL statements for all the methods of all the EJBs in the EJB-JAR. If this process is not executed, the change in the table name may not be applied to all the SQL statements). After changing the table name, restart the application.

#3

The J2EE server is started when the target application is not running.

(c) Naming conventions for the tables for CMR

The name of the table for CMR is as follows:

• In the case of a two-way relationship

  [<ejb-name> of Bean1]_ [<cmr-field-name> of Bean1]_[<ejb-name> of Bean2]_[<cmr-field-name> of Bean2]

• In the case of a one-way relationship (one-way is considered to be from Bean1 to Bean2)

  [<ejb-name> of Bean1]_[<cmr-field-name> of Bean1]_[<ejb-name> of Bean2]

If the name decided by this method is of 29 characters or more, it will be truncated to 28 characters. If the name that is truncated to 28 characters matches with a table name already existing in the database or if it overlaps with the name of the table for another CMR in the same EJB-JAR, then it is differentiated by adding a number from 0 to 99 at the end.

(d) Precautions related to CMR

• The user needs the permission to execute the CREATE TABLE command in the schema in which the Bean1 table exists.

• The generation of the table for CMR may fail due to the restriction on the size of the primary key depending on the type of the database and OS. The primary key of the Entity Bean is saved in the table for CMR, as shown in Figure 9-1. Adjust the size of the primary key of the Entity Bean.

• When the application is stopped, the table for CMR is deleted, hence, the information on the relation that was established until then, is lost. The relation information is also lost when the table for CMR is deleted manually.

• If the numbers from 0 to 99 are all used up for naming the table for CMR, the table for CMR cannot be generated. In this case, delete the tables in the database that are not required so that you can use those names, or see (c) Naming conventions for the tables for CMR for other names.

• Map the primary key of the relation-forming Entity Bean to a type that can be considered as the primary key of database table.

• When an application that contains CMR is stopped, the table for CMR is deleted, however, there are cases when the deletion of the table for CMR fails due to occurrence of a failure such as inability to access the database. In this case, the table remains in the database, so when it is not required, delete it manually by using the tools provided in the database products.

(e) Restoring the table for CMR when a failure occurs

When an application that contains CMR is started, if a failure occurs while the J2EE server was stopped for maintenance and then restarted, the J2EE server may not restart with the running application that contains CMR. After resolving the error, even if you try to restart the application that contains CMR, then, as described in Table 9-4, the application cannot be started if there is a table in the database with the same name as that of the table to be created (in order to avoid sharing of tables between the applications).

If the process of generating an SQL statement is executed again, an SQL statement that uses a new table name for CMR, is generated, and you can start the application by using the new table for CMR. If you want to continue the relation that was being used before stopping the J2EE server, you must start the application by using the table that is remaining in the database.

The ejbserver.ejb.cmp20.cmr.use.existing_table key in the usrconf.properties file is an option for restoring the relationship information that was being used until the start up of the application failed. If true is specified in this key, you can start the application by using the table that already exists in the database. If nothing is specified or if false is specified in this key, execute the operations described in Table 9-4. The procedure for using the existing table by using this option is as follows:

1. Use the tools provided in the database products to confirm that the table for CMR that was used before the failure is still in the database.

2. Stop the J2EE server (Take measures against the cause of failure in starting the application while it is running)

3. Set ejbserver.ejb.cmp20.cmr.use.existing_table=true in the usrconf.properties file.

4. Start the J2EE server.

5. Restart the application containing CMR that had failed to start.

   Note:

   Do not re-execute the process of SQL statement generation. If you re-execute the process, an SQL statement is generated with a new table name and you will not be able to use the earlier table.

6. Stop the J2EE server.

7. Set ejbserver.ejb.cmp20.cmr.use.existing_table=false in the usrconf.properties file or return to the state where this option is not set.

8. Restart the J2EE server.