Java Tutorial - Java Scipt :
Creating an EJB Deployment Descriptor
Every EJB needs to have an entry in a deployment descriptor. This is the first EJB in our package, so we will create a complete deployment descriptor here and then edit it as we move forward. We will build this file up from fragments so we can explain things as we go along. The deployment descriptor for an EJB is named ejb-jar.xml and must appear in the META-INF directory of the .jar file that contains the EJB. We will create and edit the file in the /etc directory and put it into the META-INF directory when we build the .jar file. The
opening lines of the file are shown in the following code:
<?xml version=”1.0” encoding=”UTF-8”?>
<!DOCTYPE ejb-jar PUBLIC
‘-//Sun Microsystems, Inc.//DTD Enterprise
‘http://java.sun.com/dtd/ejb-jar_2_0.dtd’>
The first line is standard for most XML documents and provides the XML version and the document encoding information. The second line provides the reference for the DTD or data type definition for the document. The first quoted string after PUBLIC is the public ID. This is specific to the version of the DTD. The next quoted string is a URL that describes where a copy of the DTD can be found. Often, it is handy to replace the DTD URL with a URL for local copy of the DTD. If you are using an XML editor, it is useful to have the DTDs because the editor can assist with identifying errors as you create the document. All EJB deployment descriptors start with the <ejb-jar> element, as shown in the following fragment:
<ejb-jar>
<display-name>chapter13</display-name>
<enterprise-beans>
<!-- Define the Entity Beans here -->
The display name is optional but is recommended for those environments that provide a management interface for the container. The <enterprise-beans> tag starts the section for describing the beans that will be deployed with this file. The <entity> tag (shown in the following fragment below) starts the definition of our entity bean. There is one entity tag for each entity bean being deployed:
<entity>
<display-name>UserEJB</display-name>
<ejb-name>UserEJB</ejb-name>
<home>com.oldfriends.entity.UserRemoteHome</home>
<remote>com.oldfriends.entity.UserRemote</remote>
<local-home>com.oldfriends.entity.UserLocalHome</local-home>
<local>com.oldfriends.entity.UserLocal</local>
<ejb-class>com.oldfriends.entity.UserEjb</ejb-class>
The display name is again optional but useful to have. The <home>, <remote>, <local-home>, and <local> tags provide the fully qualified class names for the matching interfaces. The <ejb-class> tag provides the fully qualified class name for the class that implements the entity bean. The next piece of our deployment descriptor follows:
<persistence-type>Container</persistence-type>
<prim-key-class>java.lang.String</prim-key-class>
<reentrant>False</reentrant>
The <persistence-type> describes who has the responsibility for storing the bean and must be either Container or Bean. The <prim-key-class> provides the fully qualified class name of the class that represents the primary key in
the database. Note that if the key column in the database were an integer, you would want to use java.lang.Integer because the Java int type is not a class and cannot be used. reentrant describes whether the bean code is suitable for reentrant calls; a reentrant is a call on a method before a previous call to the same method has completed. This is normally set to False
The values for all elements are case sensitive. For example the values True and False must be represented with the uppercase first letter, and the Container value in the <persistence-type> element must start with
an uppercase C.
The next fragment of the deployment descriptor (shown below) provides information required for container-managed persistence:
<cmp-version>2.x</cmp-version>
<abstract-schema-name>User</abstract-schema-name>
<cmp-field>
<field-name>userid</field-name>
</cmp-field>
<cmp-field>
<field-name>email</field-name>
</cmp-field>
<cmp-field>
<field-name>firstName</field-name>
</cmp-field>
<cmp-field>
<field-name>gradYear</field-name>
</cmp-field>
<cmp-field>
<field-name>lastName</field-name>
</cmp-field>
<cmp-field>
<field-name>loginId</field-name>
</cmp-field>
<cmp-field>
<field-name>maidenName</field-name>
</cmp-field>
<cmp-field>
<field-name>mi</field-name>
</cmp-field>
<cmp-field>
<field-name>password</field-name>
</cmp-field>
The <cmp-version> tag describes the version of container-managed persistence we will be supporting. Our bean is written for the CMP 2.0 version of the specification, as should be the case for all new entity beans. <abstract-schemaname> is required and provides a reference to the schema that will be used in EJB QL statements. For a CMP bean, every attribute that needs to be managed by the container must be listed within <cmp-field> tags, as shown Next, we have to identify which of the fields defined above represents the primary key. This is done with the <primkey-field> as follows:
<primkey-field>userid</primkey-field>
Our entity bean supports two custom queries beyond the standard find ByPrimaryKey method. In CMP 2.0, the container implements these methods, but we have to provide it with the queries. The queries provided to the container are not standard SQL as you might expect but are instead a specialized variant called EJB QL. The first query shown below implements the findByLoginId method exposed in the home and LocalHome interfaces.
<query>
<query-method>
<method-name>findByLoginId</method-name>
<method-params>
<method-param>java.lang.String</method-param>
</method-params>
</query-method>
<ejb-ql>
<![CDATA[SELECT OBJECT(u) FROM User u WHERE u.loginId=?1]]>
</ejb-ql>
</query>
The value of the <method-name> tag must correspond to the method in the home interfaces. Each <method-param> tag provides the fully qualified class name for the arguments for the query. Our query accepts a single java .lang.String argument. The query itself appears in the <ejb-ql> element.
The query must appear within a CDATA element so that the query does confuse the XML parser and get mistaken for XML markup.
The query in this case is: SELECT OBJECT(u) FROM User u WHERE u.loginId=?1 The ?1 will be replaced with the string described in the <method-param> tag when the query is executed. The word User after FROM in FROM User is the <abstract-schema-name> described previously. The following code shows the second query for findByEmail:
<query>
<query-method>
<method-name>findByEmail</method-name>
<method-params>
<method-param>java.lang.String</method-param>
</method-params>
</query-method>
<ejb-ql>
<![CDATA[SELECT OBJECT(u) FROM User u WHERE u.email=?1]]>
</ejb-ql>
</query>
The final fragment, which closes the open tags, completes the ejb-jar file for now:
</entity>
</enterprise-beans>
</ejb-jar>
But wait, there’s more. JBoss has some JBoss-specific deployment information that it needs. The next section gives you a look at these files.
