Entity Commands and Primary Key Generation

Figure 11.15. The jbosscmp-jdbc.xml entity-commands element model.

[View full size image]

Each entity-command element specifies an entity-generation implementation. The name attribute specifies a name that allows the command defined in an entity-commands section to be referenced in the defaults and entity elements. The class attribute specifies the implementation of the org.jboss.ejb.plugins.cmp.jdbc. JDBCCreateEntityCommand that supports the key generation. Database-vendor-specific commands typically subclass org.jboss.ejb.plugins.cmp.jdbc. JDBCIdentityColumnCreateCommand if the database generates the primary key as a side effect of doing an insertion, or they subclass org.jboss.ejb.plugins.cmp.jdbc. JDBCInsertPKCreateCommand if the command must insert the generated key.

The optional attribute element(s) allows for the specification of arbitrary name/value property pairs that will be available to the entity command implementation class. The attribute element has a required name attribute that specifies the name property, and the attribute element content is the value of the property. The attribute values are accessible through the org.jboss.ejb.plugins.cmp.jdbc.metadata. JDBCEntityCommandMetaData.getAttribute(String) method.

Existing Entity Commands

The following are the current entity-command definitions found in the standardjbosscmp-jdbc.xml descriptor:

• default (org.jboss.ejb.plugins.cmp.jdbc.JDBCCreateEntityCommand) JDBCCreateEntityCommand is the default entity creation because it is the entity-command referenced in the standardjbosscmp-jdbc.xml default element. This entity-command executes an INSERT INTO query, using the assigned primary key value.

• no-select-before-insert (org.jboss.ejb.plugins.cmp.jdbc.JDBCCreateEntityCommand) This is a variation on default that skips selecting before insert by specifying the attribute name="SQLExceptionProcessor", which points to the jboss.jdbc:service= SQLExceptionProcessor service. The SQLExceptionProcessor service provides a Boolean isDuplicateKey(SQLException e) operation that allows for determining whether there is any unique constraint violation.

• pk-sql (org.jboss.ejb.plugins.cmp.jdbc.JDBCPkSqlCreateCommand) JDBCPkSqlCreateCommand executes an INSERT INTO query statement that is provided by the pk-sql attribute to obtain the next primary key value. Its primary target usage is for databases with sequence support.

• mysql-get-generated-keys (org.jboss.ejb.plugins.cmp.jdbc.mysql.JDBCMySQLCreateCommand) JDBCMySQLCreateCommand executes an INSERT INTO query by using the getGeneratedKeys method from the MySQL native java.sql.Statement interface implementation to fetch the generated key.

• oracle-sequence (org.jboss.ejb.plugins.cmp.jdbc.keygen.JDBCOracleCreateCommand) JDBCOracleCreateCommand is a create command for use with Oracle that uses a sequence in conjunction with a RETURNING clause to generate keys in a single statement. It has a required sequence element that specifies the name of the sequence column.

• hsqldb-fetch-key (org.jboss.ejb.plugins.cmp.jdbc.hsqldb.JDBCHsqldbCreateCommand) JDBCHsqldbCreateCommand executes an INSERT INTO query after executing a CALL IDENTITY() statement to fetch the generated key.

• sybase-fetch-key (org.jboss.ejb.plugins.cmp.jdbc.sybase.JDBCSybaseCreateCommand) JDBCSybaseCreateCommand executes an INSERT INTO query after executing a SELECT @@IDENTITY statement to fetch the generated key.

• mssql-fetch-key (org.jboss.ejb.plugins.cmp.jdbc.keygen.JDBCSQLServerCreateCommand) JDBCSQLServerCreateCommand for Microsoft SQL Server uses the value from an IDENTITY columns. By default, it uses SELECT SCOPE_IDENTITY() to reduce the impact of triggers. You can override it with the pk-sql attribute (for example, for version 7).

• informix-serial (org.jboss.ejb.plugins.cmp.jdbc.informix.JDBCInformixCreateCommand) The JDBCInformixCreateCommand executes an INSERT INTO query after using the getSerial method from Informix native java.sql.Statement interface implementation to fetch the generated key.

• postgresql-fetch-seq (org.jboss.ejb.plugins.cmp.jdbc.keygen.JDBCPostgreSQLCreateCommand) JDBCPostgreSQLCreateCommand for PostgreSQL fetches the current value of the sequence. You can use the optional sequence attribute to change the name of the sequence, and the default is table_pkColumn_seq.

• key-generator (org.jboss.ejb.plugins.cmp.jdbc.JDBCKeyGeneratorCreateCommand) JDBCKeyGeneratorCreateCommand executes an INSERT INTO query after obtaining a value for the primary key from the key generator referenced by the key-generator-factory. The key-generator-factory attribute must provide the name of a JNDI binding of the org.jboss.ejb.plugins. keygenerator.KeyGeneratorFactory implementation.

• get-generated-keys (org.jboss.ejb.plugins.cmp.jdbc.jdbc3.JDBCGetGeneratedKeysCreateCommand) JDBCGetGeneratedKeysCreateCommand executes an INSERT INTO query, using a statement that is built by using the JDBC3 prepareStatement(String, Statement.RETURN_GENERATED_KEYS) that has the capability to retrieve the autogenerated key. You obtain the generated key by calling the PreparedStatement.getGeneratedKeys method. Because this requires JDBC3 support, it is available only in JDK1.4.1+, with a supporting JDBC driver.

The following is a sample configuration that uses the hsqldb-fetch-key entity-command with the generated key mapped to a known primary key cmp-field:

<jbosscmp-jdbc>
  <enterprise-beans>
    <entity>
      <ejb-name>LocationEJB</ejb-name>
      <pk-constraint>false</pk-constraint>
      <table-name>location</table-name>

      <cmp-field>
        <field-name>locationID</field-name>
        <column-name>id</column-name>
        <auto-increment/>
      </cmp-field>
      <!-- ... -->
      <entity-command name="hsqldb-fetch-key"/>

    </entity>
  </enterprise-beans>
</jbosscmp-jdbc>

The following is an alternative example that uses an unknown primary key without an explicit cmp-field:

<jbosscmp-jdbc>
    <enterprise-beans>
        <entity>
            <ejb-name>LocationEJB</ejb-name>
            <pk-constraint>false</pk-constraint>
            <table-name>location</table-name>
            <unknown-pk>
                <unknown-pk-class>java.lang.Integer</unknown-pk-class>
                <field-name>locationID</field-name>
                <column-name>id</column-name>
                <jdbc-type>INTEGER</jdbc-type>
                <sql-type>INTEGER</sql-type>
                <auto-increment/>
            </unknown-pk>
            <!--...-->
            <entity-command name="hsqldb-fetch-key"/>
        </entity>
    </enterprise-beans>
</jbosscmp-jdbc>