Facilities Guide

CHAPTER 2

J2EE Archive Deployment

This chapter describes the requirements for deploying J2EE-compatible archive files to a Novell exteNd Application Server. It covers these topics:

Using exteNd Director This chapter describes deployment using the application server deployment tools. To learn about developing, packaging, and deploying with Novell exteNd Director, see the exteNd Director help.

Deploying archives

To deploy a J2EE archive to the application server, you'll:

Step	Action	Archive type	Where to go for more information
1	Package the application in an archive file	Client application, EJB, EAR, and WAR	Sun establishes the requirements for each application type. For more information about writing or packaging J2EE applications, see the published specifications on the Sun Java Web site at: http://java.sun.com/j2ee/docs.html
1	Package the application in an archive file	RAR	For information about writing and packaging a RAR, see the J2EE Connector architecture specification, available from the Sun Java Web site at: http://jcp.org/jsr/detail/016.jsp
2	Write a deployment plan	Client application	See Client JAR deployment plan DTD NOTE: A deployment plan is only required if the application references EJBs, environment entries, or other external resources (such as databases). If the application does not include external references, a deployment plan is not required.
		EJB	See Deployment Plan DTDs
		EAR
		RAR
		WAR
3	Deploy the archive	Client application	See DeployCAR
		EJB	See DeployEJB
		EAR	See DeployEAR
		RAR	See DeployRAR
		WAR	See DeployWAR

EJB deployment tips

This section describes some features specifically related to deploying EJB archives including:

Updating EJB 1.1 Finder methods

If you have existing EJB 1.1 beans, you'll have to update the deployment plan to use the correct DTD. For more information on EJB deployment plans, see EJB JAR deployment plan DTD.

You can use the Novell exteNd Director Deployment Plan Editor to convert the deployment plan for you. For more information on using the Deployment Plan Editor to convert deployment plans, see the exteNd Director help.

When you use exteNd Director to update the deployment plan for CMP entity beans, Finder method definitions are converted from whereClause elements to sqlWhereClause elements.

The Deployment Plan Editor converts the EJB 1.1 Finder methods to simple expressions that include the WHERE clause of a SQL statement and one or more input parameters. It converts the first input parameter from the finder is converted to ?1, the second to ?2, and so on.

For example:

  <sqlWhereClause>
     WHERE COL1=?1
  </sqlWhereClause>

If you do not specify WHERE in the sqlWhereClause element, the container prepends it for you. So

  <sqlWhereClause>
     WHERE PRICE>1
  </sqlWhereClause>

and

  <sqlWhereClause>
     PRICE>1
  </sqlWhereClause>

are both valid.

To specify a findAll() method, just supply an empty string for the sqlWhereClause element.

For more information on upgrading, see the exteNd Director help.

Tips for completing the EJB deployment plan

This section describes some tips and examples for completing the EJB deployment plan. It includes these sections:

Supporting autoincrement

The container supports autoincrement through the deployment plan's autoInc element. When autoInc is marked for a cmp-field, the database column that it maps to must support autoincrement, as follows:

Database	Requirement
Oracle	You must provide a sequence name through autoIncSequenceName element
Sybase, Microsoft, and IBM DB2	The column has to be an identity column
Informix	The column has to be a SERIAL type
IBM Cloudscape	The column type has to be autoincrement type

Mapping CMP entity beans to a table

You map a CMP entity bean to one (and only one) table. You use the beanPersistenceInfo element of the deployment plan to map a bean to a table.

Suppose that you had a deployment descriptor with an entry for an entity bean, like this:

  <entity>
      <ejb-name>BEAN_NAME</ejb-name>
      . . . 
  </entity>

The corresponding entry in the deployment plan would be in the beanPersistenceInfo node. It would look something like this:

  <beanPersistenceInfo>
      <beanName>BEAN_NAME</beanName>
      <dataSourceName>DATABASE_OR_POOL_NAME</dataSourceName>
      <sqlHandler>SQL_HANDLER</sqlHandler>
      <isolationLevel>ISOLATION_LEVEL</isolationLevel>
      <table>
          <name>DB_TABLE</name>
          . . . 
      </table>
  </beanPersistenceInfo>

Notes about the deployment plan:

The beanName element of the beanPersistenceInfo node must match the ejb-name element in the deployment descriptor (in this example, BEAN_NAME).
The dataSourceName element is the name of the database or connection pool where the table (in this example, DB_TABLE) resides.

The sqlHandler element of the deployment plan can be one of the following:

For this database or class	Valid sqlHandler element values
Oracle	Oracle
IBM Cloudscape	Cloudscape
Sybase Adaptive Server Anywhere	AdaptiveServerAnywhere
Sybase Adaptive Server Enterprise	AdaptiveServerEnterprise
Informix	Informix
Microsoft SQL Server	MicrosoftSQLServer
IBM DB2	DB2
MYSQL	MySQL
Class that implements com.sssw.shr.ejb2.api. AgiEJBSqlHandler	The fully qualified name of the class

NOTE: The sqlHandler element values are not case sensitive.

The isolationLevel element identifies the isolation level to be used. The container supports TRANSACTION_READ_COMMITTED or TRANSACTION_SERIALIZABLE. When TRANSACTION_ READ_COMMITTED isolation level is used, the container checks to make sure no values are changed by other users during a commit; if they are changed, the container throws a concurrency violation exception.

If you have multiple beans (mapped to different tables in the same database) using different isolation levels, you need multiple pools—except for Oracle databases (see just below).

Use TRANSACTION_SERIALIZABLE with caution, as the likelihood of deadlock increases.

Exceptions for Oracle For Oracle databases, all READ SQL statements for TRANSACTION_SERIALIZABLE are appended with FOR UPDATE to explicitly place a write lock on the row.

Mapping persistent fields

The persistent fields (the cmp-field elements) listed in the deployment descriptor must be mapped to a database column in the database table in the deployment plan. This enables the container to persist the fields appropriately. Suppose your deployment descriptor looked like this:

  <entity>
      <ejb-name>BEAN_NAME</ejb-name>
      <cmp-field>field1</cmp-field>
      <cmp-field>field2</cmp-field>
      <cmp-field>field3</cmp-field>
      . . . 
  </entity>

The cmp-field elements in the deployment descriptor would have a corresponding elements in the table node of the deployment plan—for example:

      <table>
          <name>DB_TABLE</name>
          <field>
              <cmpFieldName>field1</cmpFieldName>
              <columnName>COLUMN1</columnName>
          </field>
          <field>
              <cmpFieldName>field2</cmpFieldName>
              <columnName>COLUMN2</columnName>
          </field>
          . . . 
      </table>

Notes about the deployment plan:

The cmpFieldNames in the deployment plan must match the cmp-field elements in the deployment descriptor.
The columnName is an actual column name in the database. This field is case-sensitive and must exactly match the database column name returned by the JDBC getColumns() method. The container needs the correct name to locate the column.

Using TRANSACTION_READ_COMMITTED isolation levels

When you specify TRANSACTION_READ_COMMITTED for the isolation level, you may be able to specify some columns as deltaType columns in the deployment plan to improve performance.

The deltaType element specifies whether the column data is used to maintain a count or a total, such as total count or total sales. If you use this element, you should set up a database constraint to guard against overflow/underflow. For example, suppose you have a column that contains the quantity left for a specific product; many transactions may try to increase or decrease this quantity. Instead of generating SQL like this:

  UPDATE table SET quantity = ? WHERE col1=old_col1_value AND col2 = old_col2_value

and

  quantity = old_quantity

which will result in a concurrency violation if two users change them concurrently. The container generates SQL like this:

  UPDATE table SET quantity = quantity + ? WHERE col1=old_col1_value 
  AND col2 = old_col2_value

For this example, you would apply a constraint that does not allow the quantity to drop below zero, and the column should not allow NULL.

Using the deltaType element appropriately can greatly reduce the possibility of a CONCURRENCY_VIOLATION exception and improve performance. To use the deltaType element:

The column must represent a quantity—because the data type can only be a number type like an int, a short, a float, a double, a BigDecimal, and so on.
The field cannot be null.
It has no impact for TRANSACTION_SERIALIZABLE.

Mapping relationships

A relationship can exist between two entity beans that have CMP. This relationship is expressed via the relationships node of the deployment descriptor. The relationship is mapped to real tables via the relationsList node of the deployment plan.

Based on the contents of the deployment descriptor and the deployment plan, the container will be able to generate the appropriate SQL code to traverse the tables and get and set the appropriate values. To generate the SQL, the container needs to have the answers to these questions:

Does a relationship exist?
What beans are involved in the relationship?
What is the multiplicity of the relationship?
What is the direction of the relationship (bidirectional or unidirectional)? If unidirectional, which bean is the one that can access the other bean?
How do you navigate the relationship?
What are the foreign key/primary key relationships?
Does the relationship support cascade delete?

The container gets the all this information (except the foreign key mapping) from the deployment descriptor relationships node. The relationships node contains the elements shown here:

  <relationships>
      <ejb-relation>
          <ejb-relationship-role>
              <multiplicity></multiplicity>
              <relationship-role-source>
                  <ejb-name></ejb-name>
              </relationship-role-source>
              <cmr-field>
                  <cmr-field-name></cmr-field-name>
                  <cmr-field-type></cmr-field-type>
              </cmr-field>
          </ejb-relationship-role>
          <ejb-relationship-role>
              <multiplicity></multiplicity>
              <relationship-role-source>
                  <ejb-name></ejb-name>
              </relationship-role-source>
              <cmr-field>
                  <cmr-field-name></cmr-field-name>
                  <cmr-field-type></cmr-field-type>
              </cmr-field>
          </ejb-relationship-role>
      </ejb-relation>
      . . . 
  </relationships>

Notes about the relationship:

For each relationship there are exactly two ejb-relationship-role nodes.
The multiplicity element determines whether the relationship is one-to-one, one-to-many, many-to-one, or many-to-many.
For each cmr-field element in the deployment descriptor, there will be a corresponding set or get method in the bean class. So the cmr-field element (or lack of) determines the direction (unidirectional or bidirectional).
The <ejb-relation-name> element is optional (according to the EJB specification).
For a many-to-many relationship, a linkTable element (in the deployment plan) is required. The container allows the linkTable element to be used in a one-to-many relationship but does not recommend it.

Once you have the deployment descriptor, you can create a new deployment plan or complete an existing one.

How to express a one-to-one bidirectional relationship

This example illustrates how you would express a one-to-one bidirectional relationship for the CustomerEJB (which maps to the CUSTOMER table) and the AddressEJB (which maps to the ADDRESS table). The primary keys are CustomerID and AddressID respectively.

The deployment descriptor would look like this:

      <ejb-relation>
          <ejb-relationship-role>
              <multiplicity>One</multiplicity>
              <relationship-role-source>
                  <ejb-name>CustomerEJB</ejb-name>
              </relationship-role-source>
              <cmr-field>
                  <cmr-field-name>address</cmr-field-name>
              </cmr-field>
          </ejb-relationship-role>
          <ejb-relationship-role>
              <multiplicity>One</multiplicity>
              <relationship-role-source>
                  <ejb-name>AddressEJB</ejb-name>
              </relationship-role-source>
              <cmr-field>
                  <cmr-field-name>customer</cmr-field-name>
              </cmr-field>
          </ejb-relationship-role>
      </ejb-relation>

Notes about the deployment descriptor:

The multiplicity element in both ejb-relationship-roles is One to specify the one-to-one relationship.
Both ejb-relationship-role elements list cmr-field-names. This indicates that the relationship is bidirectional. The cmr-field-names do not actually represent columns or foreign keys in the related tables. You don't know the actual names of the target columns until deployment; the cmr-field-names are just entries that represent the direction of the relationship.

Suppose you are ready to deploy the EJB JAR and now need to create the deployment plan that would represent the CustomerEJB and AddressEJB EJBs. You might be mapping the CustomerEJB and AddressEJB to a target database where the CUSTOMER table contained a foreign key to the ADDRESS table; the foreign key field name is ADDRESS_ID. The relation node of your deployment plan would look like this:

      <relation>
          <relationRole>
              <beanName>CustomerEJB</beanName>
              <cmrFieldName>address</cmrFieldName>
              <columnNames>
                  <el>ADDRESS_ID</el>
              </columnNames>
          </relationRole>
          <relationRole>
              <beanName>AddressEJB</beanName>
              <cmrFieldName>customer</cmrFieldName>
          </relationRole>
      </relation>

Notes about the deployment plan:

The beanName in the deployment plan must exactly match the ejb-name element of the deployment descriptor.
The cmrFieldName of the deployment plan (or lack of this element) must exactly match the cmr-field-name of the deployment descriptor.
The deployment plan's columnName element is the column name of the foreign key in the table (CUSTOMER) to which it is mapped. This means that the container will construct SQL so that it can navigate from the customer to the associated address, and vice versa.
The cmrFieldName of the AddressEJB is not mapped to a column name. This is because the ADDRESS table does not (and should not) contain a foreign key to the CUSTOMER table.
The location of the foreign key does not determine the direction of the relationship.

If your database should be set up so that the ADDRESS table contained a foreign key CUSTOMER_ID, the deployment plan would look like this:

      <relation>
          <relationRole>
              <beanName>CustomerEJB</beanName>
              <cmrFieldName>address</cmrFieldName>
          </relationRole>
          <relationRole>
              <beanName>AddressEJB</beanName>
             <cmrFielName>customer</cmrFieldName>
              <columnNames>
                  <el>CUSTOMER_ID</el>
              </columnNames>
          </relationRole>
      </relation>

How to express a one-to-one unidirectional relationship

This example illustrates how you would express a one-to-one unidirectional relationship for CustomerEJB (which maps to the CUSTOMER table) and AddressEJB (which maps to the ADDRESS table). The primary keys are CustomerID and AddressID respectively.

The deployment descriptor would look like this:

      <ejb-relation>
          <ejb-relationship-role>
              <multiplicity>One</multiplicity>
              <relationship-role-source>
                  <ejb-name>CustomerEJB</ejb-name>
              </relationship-role-source>
              <cmr-field>
                  <cmr-field-name>address</cmr-field-name>
              </cmr-field>
          </ejb-relationship-role>
          <ejb-relationship-role>
              <multiplicity>One</multiplicity>
              <relationship-role-source>
                  <ejb-name>AddressEJB</ejb-name>
              </relationship-role-source>
          </ejb-relationship-role>
      </ejb-relation>

Notes about the deployment descriptor:

The multiplicity element in both ejb-relationship-roles is One to specify the one-to-one relationship.
The CustomerEJB includes a cmr-field-name element (in this case, address), but the AddressEJB does not. This specifies that the relationship is unidirectional—you can get to the AddressEJB from the CustomerEJB but not vice versa. (The CustomerEJB will include get and set methods for the ADDRESS EJB.)
The cmr-field-name address does not actually represent a column in the AddressEJB. When you create the deployment plan, you'll have to map the address cmr-field to the actual foreign key column.

This deployment plan shows how to map the cmr-field-name when the CUSTOMER table includes the foreign key ADDRESS_ID:

      <relation>
          <relationRole>
              <beanName>CustomerEJB</beanName>
              <cmrFieldName>address</cmrFieldName>
              <columnNames>
                  <el>ADDRESS_ID</el>
              </columnNames>
          </relationRole>
          <relationRole>
              <beanName>AddressEJB</beanName>
          </relationRole>
      </relation>

Notes about the deployment plan:

The beanName in the deployment plan must exactly match the ejb-name element of the deployment descriptor.
The cmrFieldName of the deployment plan must exactly match the cmr-field-name of the deployment descriptor (this also means that the deployment plan should not have a cmrFieldName when the deployment descriptor does not have a cmr-field-name).
The deployment plan's columnName element is the column name of the foreign key in the table (CUSTOMER) to which it is mapped. This specifies that the container will construct SQL so that it can navigate from the customer to the associated address.
The AddressEJB does not have a cmrFieldName or columnNames element, because the ADDRESS table does not (and should not) contain a foreign key to the CUSTOMER table.

Suppose your existing database used a different structure and the ADDRESS table had the foreign key CUSTOMER_ID. The deployment plan would look like this:

      <relation>
          <relationRole>
              <beanName>CustomerEJB</beanName>
              <cmrFieldName>address</cmrFieldName>
          </relationRole>
          <relationRole>
              <beanName>AddressEJB</beanName>
              <columnNames>
                  <el>CUSTOMER_ID</el>
              </columnNames>
          </relationRole>
      </relation>

Notes about the deployment plan:

The relationRole and cmrFieldNames exactly match the entries in the deployment descriptor as noted above—but this time the columnName is not included in this node of the relationRole element. This is because the foreign key is not in the CUSTOMER table (it's in the ADDRESS table).
The relationship is still unidirectional, because only one cmrFieldName element is present.
You specify the foreign key in the table in which it belongs. The foreign key has nothing to do with the direction of the relationship.

Expressing a one-to-many bidirectional relationship

This example uses:

The OrderEJB (which maps to the ORDER table)

AND
The LineItemEJB (which maps to the LINEITEM table)

For each OrderEJB there can be many LineItems. You can navigate from the ORDER table to the LINEITEM table and back.

The deployment descriptor looks like this:

      <ejb-relation>
          <ejb-relationship-role>
              <multiplicity>One</multiplicity>
              <relationship-role-source>
                  <ejb-name>OrderEJB</ejb-name>
              </relationship-role-source>
              <cmr-field>
                  <cmr-field-name>lineItems</cmr-field-name>
                  <cmr-field-type>java.util.Collection</cmr-field-type>
              </cmr-field>
          </ejb-relationship-role>
          <ejb-relationship-role>
              <multiplicity>Many</multiplicity>
              <relationship-role-source>
                  <ejb-name>LineItemEJB</ejb-name>
              </relationship-role-source>
              <cmr-field>
                  <cmr-field-name>order</cmr-field-name>
              </cmr-field>
          </ejb-relationship-role>
      </ejb-relation>

Notes about the deployment descriptor:

The OrderEJB includes a cmr-field-name element (in this case, lineitems), and the LineItemEJB also has a cmr-field-name element (in this case, order). This specifies that the relationship is bidirectional.
The data type of the lineitems cmr-field-name element includes a data type specification (a java.util.Collection), because more than one item can be returned.

Suppose you are writing a deployment descriptor for the situation where:

The OrderEJB bean maps to the ORDERS table (whose primary key is ORDERID)
The LineItemEJB bean maps to the LINEITEM table (whose primary key is LINEITEMID)
The LINEITEM table has a foreign key ORDER_ID

In this case the deployment plan would look like this:

      <relation>
          <relationRole>
              <beanName>OrderEJB</beanName>
              <cmrFieldName>lineItems</cmrFieldName>
          </relationRole>
          <relationRole>
              <beanName>LineItemEJB</beanName>
              <cmrFieldName>order</cmrFieldName>
              <columnNames>
                  <el>ORDER_ID</el>
              </columnNames>
          </relationRole>
      </relation>

Notes about the deployment plan:

As always, the beanName has to be the same as the ejb-name of the deployment descriptor, and the cmrFieldName has to be the same as the cmr-field-name of the deployment descriptor.
The LineItemEJB contains a columnName element that maps to the foreign key.
In a one-to-one relationship, the location of the foreign key may be in either table. In a one-to-many relationship, the foreign key always resides on the Many side. The location of the foreign key does not determine the direction of the relationship.

Expressing a one-to-many unidirectional relationship

This example illustrates how to express a one-to-many unidirectional relationship. This example uses the ProductEJB (which maps to the PRODUCT table) and the LineItemEJB (which maps to the LINEITEM table). For each ProductEJB there can be many LineItemEJBs. You can navigate from the LINEITEM table to the PRODUCT table but not back.

The deployment descriptor looks like this:

      <ejb-relation>
          <ejb-relationship-role>
              <multiplicity>One</multiplicity>
              <relationship-role-source>
                  <ejb-name>ProductEJB</ejb-name>
              </relationship-role-source>
          </ejb-relationship-role>
          <ejb-relationship-role>
              <multiplicity>Many</multiplicity>
              <relationship-role-source>
                  <ejb-name>LineItemEJB</ejb-name>
              </relationship-role-source>
              <cmr-field>
                  <cmr-field-name>product</cmr-field-name>
              </cmr-field>
          </ejb-relationship-role>
      </ejb-relation>

The multiplicity element for the ProductEJB is One and for the LineItemEJB is Many—specifying that one ProductEJB can have many related LineItemEJBs.
The LineItemEJB includes a cmr-field-name element (in this case, products), but the ProductEJB does not have one. This indicates that the relationship goes in a single direction from LineItem to Product.

Suppose that you are writing a deployment plan for the deployment descriptor above where:

The ProductEJB bean maps to the PRODUCT table (whose primary key is PRODUCTID)
The LineItemEJB bean maps to the LINEITEM table (whose primary key is LINEITEMID)
The LINEITEM table has a foreign key PRODUCT_ID

In this case the deployment plan would look like this:

      <relation>
          <relationRole>
              <beanName>ProductEJB</beanName>
          </relationRole>
          <relationRole>
              <beanName>LineItemEJB</beanName>
              <cmrFieldName>product</cmrFieldName>
              <columnNames>
                  <el>PRODUCT_ID</el>
              </columnNames>
          </relationRole>
      </relation>

Notes about the deployment plan:

As always, the beanName must be the same as the ejb-name of the deployment descriptor, and the cmrFieldName must be the same as the cmr-field-name of the deployment descriptor.
The LineItemEJB contains a columnNames element that maps to the foreign key.

Using a link table

It is possible to use a link table (but not recommended). For example, the link table might be PROD_LINEITEM, which has the PRODUCT_ID and LINEITEM_ID, mapped to PRODUCTID and LINEITEMID respectively.

In this case the deployment plan would look like this:

      <relation>
          <linkTable>PROD_LINEITEM</linkTable>
          <relationRole>
              <beanName>ProductEJB</beanName>
              <columnNames>
                  <el>PRODUCT_ID</el>
              </columnNames>
          </relationRole>
          <relationRole>
              <beanName>LineItemEJB</beanName>
              <cmrFieldName>product</cmrFieldName>
              <columnNames>
                  <el>LINEITEM_ID</el>
              </columnNames>
          </relationRole>
      </relation>

How to express a many-to-many unidirectional relationship

This example illustrates how you would express a many-to-many unidirectional relationship for the OrderEJB (which maps to the ORDER table) and the ProductEJB (which maps to the PRODUCT table). The primary keys are OrderID and ProductID respectively. Many-to-many relationships always use a linkTable.

The deployment descriptor would look like this:

      <ejb-relation>
          <ejb-relationship-role>
              <multiplicity>Many</multiplicity>
              <relationship-role-source>
                  <ejb-name>OrderEJB</ejb-name>
              </relationship-role-source>
              <cmr-field>
                  <cmr-field-name>products</cmr-field-name>
                  <cmr-field-type>java.util.Collection</cmr-field-type>
              </cmr-field>
          </ejb-relationship-role>
          <ejb-relationship-role>
              <multiplicity>Many</multiplicity>
              <relationship-role-source>
                  <ejb-name>ProductEJB</ejb-name>
              </relationship-role-source>
          </ejb-relationship-role>
      </ejb-relation>

Notes about the deployment descriptor:

The multiplicity element for both ejb-relationship-roles is Many.

Suppose you had to write a deployment plan where:

The ProductEJB bean maps to the PRODUCT table (whose primary key is PRODUCTID)
The OrderEJB bean maps to the ORDERS table (whose primary key is ORDERID)
The link table is PROD_ORDER. The PROD_ORDER table's primary keys are PRODUCT_ID and ORDER_ID (which are also foreign keys to the PRODUCT and ORDER tables).

In this case your deployment plan would look like this:

      <relation>
          <linkTable>PROD_ORDER</linkTable>
          <relationRole>
              <beanName>OrderEJB</beanName>
              <cmrFieldName>products</cmrFieldName>
              <columnNames>
                  <el>ORDER_ID</el>
              </columnNames>
          </relationRole>
          <relationRole>
              <beanName>ProductEJB</beanName>
              <columnNames>
                  <el>PRODUCT_ID</el>
              </columnNames>
          </relationRole>
      </relation>

Notes about the deployment plan:

As always, the beanName must be the same as the ejb-name of the deployment descriptor, and the cmrFieldName must be the same as the cmr-field-name of the deployment descriptor.
The relation node would include the linkTable element that specifies the actual name of the database table.
The relation roles for both OrderEJB and ProductEJB include foreign key mappings (via the columnNames element) to the linkTable.

General restrictions on relationship mapping

Keep in the following in mind:

You can use a single column as both a cmp-field and a cmr-field; but when the single column is both a cmp-field and a cmr-field, the cmp-field should be read-only. Calling a set method on the cmp-field results in an Exception in this case.
You cannot use the same database column for more than one cmp-field or cmr-field.
The way to change a relationship is through its cmr-field (not the cmp-field).

Mapping a primary key

You specify the primary key for the entity bean using the primkey-field and/or the prim-key-class elements. (According to the EJB specification, the prim-key-class element is required, but the primkey-field is optional.)

For single-field primary keys, the primkey-field has to be one of the cmp-fields.

If the primary key is a multifield key:

Use the prim-key-class to specify the primary key.
All of the prim-key-class's fields must be public.
The prim-key-class's field names must correspond to the field names of the entity bean class.

A class is an unknown primary key (see the EJB 2.0 specification section 10.8.3) if the primkey-field element is missing and the prim-key-class element is a java.lang.Object. For unknown primary keys, the EJB container generates a unique key. The deployment plan primaryKey element is used to support the unknown primary key as follows:

You must specify a primaryKeyClass element for the primaryKey element.

The container supports java.lang.String, java.lang.Integer, or java.lang.Long for primaryKeyClass.
- If the primaryKeyClass is java.lang.String, the autoInc element is ignored, and the column has to be able to store a 32-byte length of String data.
- If primaryKeyClass is java.lang.Integer or java.lang.Long, then the autoInc element is required (and has to map to a column that supports autoincrement)—so that an autoincrement column can be used to generate unique primary keys.
- In general, performance is better with autoincrement columns. The following shows what a primary key class entry in the deployment plan might look like:
```
      <primaryKey>
          <primaryKeyClass>java.lang.Integer</primaryKeyClass>
          <columnName>AUTO_INC_COL</columnName>
          </autoInc>
      </primaryKey>
```

Mapping for message-driven beans

Message-driven beans use a JMS server to transmit and consume messages. For the container to locate the JMS server, you must specify at least the destinationName element and the ConnectionFactoryName element—for example:

      <message>
          <destinationName>
             corbaname:iiop:JMSServer:53506#queue/queueName
          </destinationName>
          <connectionFactoryName>
             corbaname:iiop:JMSServer:53506#queue/xaConnectionFactory
          </connectionFactoryName>
      </message>

NOTE: The specified ConnectionFactory must support global transactions.

IOR configurations for EJB security

This section describes the information you must supply in the deployment plan to support secure invocations of the EJB. You supply the information via the iorSecurityConfig element of the deployment plan. The iorSecurityConfig node is part of the entity and session elements.

Interoperable Object References

Every object that is remotely accessible using CORBA is referred to via an Interoperable Object Reference (IOR). The IOR is a remote reference to an object; it can be stored (in the CORBA or JNDI naming service, for example) and subsequently converted to a stub that can be used to call the remote object. So the IOR must contain all information that the client ORB needs to construct a stub for the remote object and to issue remote method calls on the stub. The information includes:

Information item	Description
One or more addresses (host IP address and TCP port number) at which the remote object can be called	The Novell exteNd ORB will be listening at this address.
The object identifier assigned to the remote object by the server ORB when the object was created	The ORB uses this to find the object.
The object's type (the list of remote interfaces the object implements)	The client uses this to determine what kind of stub to create.
Security information for the object	The client uses this information to determine whether a secure (encrypted) connection should be used for calls to the object, and whether a client certficate, user name and password, or other caller ID and credential information should be passed to the object on each call. This is the information specified by the <iorSecurityConfig> element at deployment time (as described in detail in Contents of the IOR security configuration just below).
Transactional information for the object	The client uses this to decide whether to propagate two-phase commit transaction information to the object.

When the client looks up a remote CORBA object (such as an EJB) in the naming service (such as via JNDI), what's returned is the IOR for the object. The client calls PortableRemoteObject.narrow() to convert the IOR into a stub. When the client attempts to call a method on the stub, the client's ORB uses the information obtained from the IOR to decide the following: what type of connection (encrypted or plain) to create; what server address and port number to connect to; and whether or not to encode and send client identity, credentials, and transaction information on the call. The server in turn verifies that the information supplied matches what the IOR demands and then dispatches the call to the remote object.

Contents of the IOR security configuration

The IOR security configuration as supplied in the iorSecurityConfig element has three sections:

Section	What it defines
Transport configuration	Whether an encrypted communications channel is to be used; if so, it defines the encryption parameters and certificate information required
Authentication context configuration	What kind of authentication mechanism (such as user name and password) should be supplied on calls to this object, and whether anonymous calls to the object are allowed
Security attributes context configuration	Whether or not caller identity propagation is supported for this object

Transport configuration

The transport configuration, as supplied in the transportConfig element, tells the client whether to use an encrypted communication channel (SSL or TLS) for calls to the object—and if so, which encryption algorithms should be used and whether the client must supply a client certificate for authentication purposes.

The contents of the <transportConfig> element are four attributes:

Attribute	Description
Integrity	Specifies whether the object supports or requires encryption that at least guarantees message integrity (that can detect message corruption). If set to REQUIRED, the caller must use SSL (or TLS) and will choose an appropriate cipher suite If set to SUPPORTED, the caller may use SSL (see below for information on how the client makes the decision)
Confidentiality	Specifies whether the object supports or requires encryption using an encryption algorithm that at least guarantees message confidentiality—that can prevent eavesdroppers from reading the message. If set to REQUIRED, the caller must use SSL (or TLS) and will choose an appropriate cipher suite If set to SUPPORTED, the caller may use SSL
establishTrustInClient	Specifies whether the object requires that the client authenticate using a client certificate (x.509). If set to REQUIRED, the client must supply a client certificate when setting up the SSL connection to this object; this also requires use of SSL (or TLS) If set to SUPPORTED, the client may supply a client certificate
establishTrustInServer	Specifies whether the object's server must be able to authenticate itself to the client. At present the only mechanism for a server to authenticate itself to the client is via the use of SSL (or TLS); so this flag is equivalent to controlling use of SSL. If set to REQUIRED, the client must use SSL (or TLS) on calls to this object If set to SUPPORTED, the client may use SSL

These flags interact; for example, the client must use SSL (or TLS) if any of the flags are set to REQUIRED. Similarly, it is legal to specify the use of SSL (by setting establishTrustInClient to REQUIRED) but not specify any particular cipher suites (by setting both integrity and confidentiality to none).

Client algorithm for choosing SSL If any of the four transportConfig flags is set to REQUIRED, the client must use SSL for calls to the object. If none is REQUIRED but at least one is SUPPORTED, the client must choose whether or not to use SSL. The client makes this decision based on the -AS_USE_SSL flag to SilverJ2EEClient. If the flag is set to true, the calls will use SSL; otherwise, they will not.

Cipher suites The sets of cipher suites that are used for message integrity and message protection may be explicitly specified in the deployment plan, using the integrityCipherSuites and confidentialityCipherSuites elements respectively. If supplied, each element is a String array of cipher suite names.

In this situation	This happens
If the integrityCipherSuites element is supplied	A cipher suite from the supplied list will be used for calls to any object that supports or requires integrity but does not support or require confidentiality
If the confidentialityCipherSuites element is supplied	A cipher suite from the supplied list will be used for calls to any object that supports or requires confidentiality
If either element is not supplied	The server will supply a default list of cipher suites for that category

Authentication context configuration The asContext element describes the authentication information that will be passed from the client to the server as part of each method call on the object. This information is separate from any client certificate that may be passed when the SSL connection is established. The asContext element has three subelements:

Subelement	Description
authMethod	The supported authentication method for callers. Possible values are: NONE—No caller authentication can be supplied on calls to this object USERNAME_PASSWORD—A user name and password string can be supplied on each call
realm	Supports a well-known realm named default. The default realm matches any server-supported realm. When the realm is specified as default, the user name and password are passed as qualified names, so that the server can distinguish LDAP user names from NT user names.
asContextRequired	A boolean indicating whether or not the caller must supply a user name and password. If true, the authMethod element must not be NONE, and the caller must supply a user name and password on each call to the object.

Subelement

Description

authMethod

The supported authentication method for callers. Possible values are:

NONE—No caller authentication can be supplied on calls to this object
USERNAME_PASSWORD—A user name and password string can be supplied on each call

realm

Supports a well-known realm named default. The default realm matches any server-supported realm.

When the realm is specified as default, the user name and password are passed as qualified names, so that the server can distinguish LDAP user names from NT user names.

asContextRequired

A boolean indicating whether or not the caller must supply a user name and password. If true, the authMethod element must not be NONE, and the caller must supply a user name and password on each call to the object.

Security attribute context configuration

The security attribute context configuration is specified in the <sasContext> element via callerPropagation, an attribute indicating whether or not this object supports caller identity propagation. Caller identity propagation is the ability for the client to propagate the caller's identity to the server without supplying any credentials, such as a password. This is useful only if the server trusts the client and the client has already verified the caller's identity—for example, if the caller is another application server owned by the organization that has already verified the client's password. Possible values are:

Value	Means
NONE	Caller propagation is not supported for this object
SUPPORTED	The caller may propagate an identity (subject to the server verifying that the caller is trusted)
REQUIRED	The caller must propagate an identity

The server determines whether the caller is trusted by the use of a list of trusted clients. The list of trusted clients can be set using the SMC.

Suppose that multiple identities are supplied on the call (for example, a client certificate and identity asserted via identity propagation). The identities are determined as follows:

If a client certificate was supplied, use it to obtain the caller's identity.
If an identity was asserted via caller propagation, use it as the caller's identity.
If a user name and password were passed on the call, use them to obtain the caller's identity.
Otherwise, treat the caller as Anonymous.

IOR configuration examples

Example 1 This example shows the IOR configuration for an object that:

Is to be called using SSL with message confidentiality preserved (encryption)

Supports passing caller identity via either client certificate or user name and password

  <iorConfig>
     <transportConfig>
       <integrity>NONE</integrity>
       <confidentiality>REQUIRED</confidentiality>
       <establishTrustInClient>SUPPORTED</establishTrustInClient>
       <establishTrustInServer>SUPPORTED</establishTrustInServer>
     </transportConfig>
    <asConfig>
       <authMethod>USERNAME_PASSWORD</authMethod>
       <realm>default</realm>
       <asContextRequired>FALSE</asContextRequired>
     </asConfig>
     <sasConfig>
       <callerPropagation>NONE</callerPropagation>
     </sasConfig>
  </iorConfig>

Example 2 This example shows the IOR configuration for an object that:

Is to be called without SSL

But requires caller authentication using user name and password

  <iorConfig>
     <transportConfig>
       <integrity>NONE</integrity>
       <confidentiality>NONE</confidentiality>
       <establishTrustInClient>NONE</establishTrustInClient>
       <establishTrustInServer>NONE</establishTrustInServer>
     </transportConfig>
     <asConfig>
       <authMethod>USERNAME_PASSWORD</authMethod>
       <realm>default</realm>
       <asContextRequired>TRUE</asContextRequired>
     </asConfig>
     <sasConfig>
       <callerPropagation>NONE</callerPropagation>
     </sasConfig>
  </iorConfig>

Example 3 This example shows the IOR configuration for an object that:

Is to be called using SSL, with message confidentiality protection

Passes a client certificate but supports caller propagation for server-to-server calls:

  <iorConfig>
     <transportConfig>
       <integrity>NONE</integrity>
       <confidentiality>REQUIRED</confidentiality>
       <establishTrustInClient>REQUIRED</establishTrustInClient>
       <establishTrustInServer>NONE</establishTrustInServer>
     </transportConfig>
     <asConfig>
       <authMethod>NONE</authMethod>
       <realm>default</realm>
       <asContextRequired>FALSE</asContextRequired>
     </asConfig>
     <sasConfig>
       <callerPropagation>SUPPORTED</callerPropagation>
     </sasConfig>
  </iorConfig>

Specifying classpath JARs on the server

The deployment plans for EJB 2.0, WAR 2.3, and EAR 1.3 support a classpathJars element that you can use to adjust the list of JAR files on your application's classpath. This lets you access user-supplied JARs that you've copied to the server.

You may have one or more commonly used JARs that you'd rather locate directly on the server than deploy in multiple applications. You can copy such JARs to your server's \userlib directory and then list them as needed in an archive's deployment plan via classpathJars and its userlibJars subelement.

For example:

  <classpathJars>
    <userlibJars>
      <el>MyJarA.jar</el>
      <el>MyJarB.jar</el>
    </userlibJars>
  </classpathJars>

This will enable the deployed archive to find classes in the listed userlib JARs at runtime.

For more information To learn about the syntax for the classpathJars element, see Deployment Plan DTDs.

Controlling thread usage for deployment

You can specify how many threads the deployer should use to upload objects to the server. By default, the deployer will use four threads for better performance.

Procedure To change the number of threads:

Edit the user.prefs file.

The user.prefs file is located in the server's \Resources\Preferences directory.
Add the following lines before the last endobj to set the number of threads (this example specifies that only one thread will be used):
```
     DEPLOYER
     /ThreadNumber 1
     endobj
```