Deploying an Entity Bean Using BMP

After you've defined a bean's home and component interfaces and developed a bean implementation class, the last step is to provide the deployment information for it. As you've seen throughout the chapter, this information controls a number of characteristics of a bean. Listing 6.14 shows a complete ejb-jar.xml deployment descriptor for the auction, item, and bidder entity beans.

Listing 6.14 ejb-jar.xml “XML Deployment Descriptor

 <?xml version="1.0"?>  <!DOCTYPE ejb-jar PUBLIC    '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN'    'http://java.sun.com/dtd/ejb-jar_2_0.dtd'>  <ejb-jar>    <enterprise-beans>      <entity>        <ejb-name>EnglishAuction</ejb-name>        <local-home>com.que.ejb20.auction.model.EnglishAuctionHome</local-home>        <local>com.que.ejb20.auction.model.EnglishAuction</local>        <ejb-class>com.que.ejb20.auction.model.EnglishAuctionBean</ejb-class>        <persistence-type>Bean</persistence-type>        <prim-key-class>java.lang.Integer</prim-key-class>        <reentrant>False</reentrant>        <ejb-local-ref>          <description>This EJB reference is used to locate an auction's item          </description>          <ejb-ref-name>ejb/Item</ejb-ref-name>          <ejb-ref-type>Entity</ejb-ref-type>          <local-home>com.que.ejb20.item.model.ItemHome</local-home>          <local>com.que.ejb20.item.model.Item</local>        </ejb-local-ref>        <resource-ref>          <description>Define a reference to a resource manager connection            factory for the auction database          </description>          <res-ref-name>jdbc/auctionSource</res-ref-name>          <res-type>javax.sql.DataSource</res-type>          <res-auth>Container</res-auth>        </resource-ref>      </entity>      <entity>        <ejb-name>Bidder</ejb-name>        <local-home>com.que.ejb20.auction.model.BidderHome</local-home>        <local>com.que.ejb20.auction.model.Bidder</local>        <ejb-class>com.que.ejb20.auction.model.BidderBean</ejb-class>        <persistence-type>Bean</persistence-type>        <prim-key-class>java.lang.Integer</prim-key-class>        <reentrant>False</reentrant>        <resource-ref>          <description>Define a reference to a resource manager connection            factory for the auction database          </description>          <res-ref-name>jdbc/auctionSource</res-ref-name>          <res-type>javax.sql.DataSource</res-type>          <res-auth>Container</res-auth>        </resource-ref>      </entity>      <entity>        <ejb-name>Item</ejb-name>        <local-home>com.que.ejb20.item.model.ItemHome</local-home>        <local>com.que.ejb20.item.model.Item</local>        <ejb-class>com.que.ejb20.item.model.ItemBean</ejb-class>        <persistence-type>Bean</persistence-type>        <prim-key-class>java.lang.Integer</prim-key-class>        <reentrant>False</reentrant>        <resource-ref>          <description>Define a reference to a resource manager connection            factory for the auction database          </description>          <res-ref-name>jdbc/auctionSource</res-ref-name>          <res-type>javax.sql.DataSource</res-type>          <res-auth>Container</res-auth>        </resource-ref>      </entity>    </enterprise-beans>    <assembly-descriptor>      <container-transaction>        <method>          <ejb-name>EnglishAuction</ejb-name>          <method-name>*</method-name>        </method>        <trans-attribute>Required</trans-attribute>      </container-transaction>      <container-transaction>        <method>          <ejb-name>Bidder</ejb-name>          <method-name>*</method-name>        </method>        <trans-attribute>Required</trans-attribute>      </container-transaction>      <container-transaction>        <method>          <ejb-name>Item</ejb-name>          <method-name>*</method-name>        </method>        <trans-attribute>Required</trans-attribute>      </container-transaction>    </assembly-descriptor>  </ejb-jar> 

You can refer to Chapter 15, "Deployment," for information on all the deployment descriptor options available to you. Basically, the descriptor in Listing 6.14 specifies that the auction entity uses BMP, supports only local clients , has an Integer primary key, needs a local reference to the item entity, uses the auction data source, and should have a transaction associated with all its method calls. Refer to Chapter 12 for a discussion of transaction attributes and their assignment.

Listing 6.15 contains the complete WebLogic deployment descriptor for the auction entity. As seen earlier in the chapter, it completes the definitions of the data source and EJB reference. It also defines the JNDI name for the entity bean.

Listing 6.15 weblogic-ejb-jar.xml “WebLogic Deployment Descriptor

 <?xml version="1.0"?>  <!DOCTYPE weblogic-ejb-jar PUBLIC    '-//BEA Systems, Inc.//DTD WebLogic 6.0.0 EJB//EN'    'http://www.bea.com/servers/wls600/dtd/weblogic-ejb-jar.dtd'>  <weblogic-ejb-jar>    <weblogic-enterprise-bean>      <ejb-name>EnglishAuction</ejb-name>      <entity-descriptor>        <entity-cache>          <max-beans-in-cache>100</max-beans-in-cache>        </entity-cache>      </entity-descriptor>      <reference-descriptor>        <resource-description>          <res-ref-name>jdbc/auctionSource</res-ref-name>          <jndi-name>auctionSource</jndi-name>        </resource-description>        <ejb-local-reference-description>          <ejb-ref-name>ejb/Item</ejb-ref-name>          <jndi-name>Item</jndi-name>        </ejb-local-reference-description>      </reference-descriptor>      <local-jndi-name>EnglishAuction</local-jndi-name>    </weblogic-enterprise-bean>    <weblogic-enterprise-bean>      <ejb-name>Bidder</ejb-name>      <entity-descriptor>        <entity-cache>          <max-beans-in-cache>100</max-beans-in-cache>        </entity-cache>      </entity-descriptor>      <reference-descriptor>        <resource-description>          <res-ref-name>jdbc/auctionSource</res-ref-name>          <jndi-name>auctionSource</jndi-name>        </resource-description>      </reference-descriptor>      <local-jndi-name>Bidder</local-jndi-name>    </weblogic-enterprise-bean>    <weblogic-enterprise-bean>      <ejb-name>Item</ejb-name>      <entity-descriptor>        <entity-cache>          <max-beans-in-cache>100</max-beans-in-cache>        </entity-cache>      </entity-descriptor>      <reference-descriptor>        <resource-description>          <res-ref-name>jdbc/auctionSource</res-ref-name>          <jndi-name>auctionSource</jndi-name>        </resource-description>      </reference-descriptor>      <local-jndi-name>Item</local-jndi-name>    </weblogic-enterprise-bean>  </weblogic-ejb-jar> 

Testing the EnglishAuction Entity Bean

Typically, the simplest way to test an entity bean is to write a Java application that accesses the bean and exercises its business methods. The problem with applying this approach to the auction entity bean is that a Java application can't serve as a local client. A quick workaround for this problem is to declare a remote interface and remote home for testing purposes. These interfaces appear in Listing 6.16 and Listing 6.17. They include a subset of the methods declared in their local counterparts.

Listing 6.16 EnglishAuctionRemote.java “A Remote Interface for the Auction Entity Bean

 package com.que.ejb20.auction.model;  /**   * Title:        EnglishAuctionRemote<p>   * Description: Remote interface used to test the EnglishAuction entity bean<p>   */  import javax.ejb.EJBObject;  import java.rmi.RemoteException;  import java.sql.Timestamp;  import com.que.ejb20.auction.exceptions.InvalidAuctionStatusException;  public interface EnglishAuctionRemote extends EJBObject {   public Integer getId() throws RemoteException;    public void setName(String newName) throws RemoteException;    public String getName() throws RemoteException;    public void setDescription(String newDescription) throws RemoteException;    public String getDescription() throws RemoteException;    public void setStartingBid(Double newStartingBid)      throws InvalidAuctionStatusException, RemoteException;    public Double getStartingBid() throws RemoteException;    public void setMinBidIncrement(Double newMinBidIncrement)      throws InvalidAuctionStatusException, RemoteException;    public Double getMinBidIncrement() throws RemoteException;    public void setReserveAmount(Double newReserveAmount)      throws InvalidAuctionStatusException, RemoteException;    public Double getReserveAmount() throws RemoteException;    public void setStartDateTime(Timestamp newStartDateTime)      throws InvalidAuctionStatusException, RemoteException;    public Timestamp getStartDateTime() throws RemoteException;    public void setScheduledEndDateTime(Timestamp newScheduledEndDateTime)      throws InvalidAuctionStatusException, RemoteException;    public Timestamp getScheduledEndDateTime() throws RemoteException;  } 

Listing 6.17 EnglishAuctionRemoteHome.java “A Remote Home Interface for the Auction Entity Bean

 package com.que.ejb20.auction.model;  /**   * Title:        EnglishAuctionRemoteHome<p>   * Description:  Remote home interface for testing the EnglishAuction entity   *               bean<p>   */  import java.rmi.RemoteException;  import java.util.Collection;  import javax.ejb.EJBHome;  import javax.ejb.CreateException;  import javax.ejb.FinderException;  public interface EnglishAuctionRemoteHome extends EJBHome {   public EnglishAuctionRemote create() throws CreateException, RemoteException;    public EnglishAuctionRemote createWithData(String name, String description)      throws CreateException, RemoteException;    public EnglishAuctionRemote findByPrimaryKey(Integer primaryKey)      throws FinderException, RemoteException;    public Collection getItemsBeingAuctioned() throws RemoteException;  } 

With these interfaces added, the deployment descriptors need to reflect them. The ejb- jar.xml file can be updated as follows to identify these new interfaces for the bean:

 <entity>    <ejb-name>EnglishAuction</ejb-name>    <home>com.que.ejb20.auction.model.EnglishAuctionRemoteHome</home>    <remote>com.que.ejb20.auction.model.EnglishAuctionRemote</remote>    <local-home>com.que.ejb20.auction.model.EnglishAuctionHome</local-home>    <local>com.que.ejb20.auction.model.EnglishAuction</local>    <ejb-class>com.que.ejb20.auction.model.EnglishAuctionBean</ejb-class>    <persistence-type>Bean</persistence-type>    <prim-key-class>java.lang.Integer</prim-key-class>    <reentrant>False</reentrant>  </entity> 

The corresponding change to the WebLogic deployment descriptor is simply the addition of a jndi-name :

 <weblogic-enterprise-bean>    <ejb-name>EnglishAuction</ejb-name>    ...    <jndi-name>EnglishAuctionRemote</jndi-name>    <local-jndi-name>EnglishAuction</local-jndi-name>  </weblogic-enterprise-bean> 

Deploying an enterprise bean requires creating an ejb-jar JAR file that includes the class files for the bean implementation and its home and component interfaces, along with the XML deployment descriptors. The deployment descriptors must be included in a META-INF subdirectory within the JAR. Refer to Chapter 15 and the documentation for your application server for more information on completing the deployment process.

Listing 6.18 illustrates a simple client application that could be used to create an auction and modify one of its attributes.

Listing 6.18 EntityBeanClient.java “A Sample Remote Client Application for the Auction Entity Bean

 package com.que.ejb20;  import javax.naming.Context;  import javax.naming.InitialContext;  import javax.naming.NamingException;  import javax.rmi.PortableRemoteObject;  import com.que.ejb20.auction.model.EnglishAuctionRemote;  import com.que.ejb20.auction.model.EnglishAuctionRemoteHome;  public class EntityBeanClient {   public void createAuction() {     try {       // pull initial context factory and provider info from jndi.properties        Context ctx = new InitialContext();        // obtain a reference to the auction remote home interface        Object home = ctx.lookup("EnglishAuctionRemote");        EnglishAuctionRemoteHome auctionHome = (EnglishAuctionRemoteHome)          PortableRemoteObject.narrow(home, EnglishAuctionRemoteHome.class);        // create a new auction        EnglishAuctionRemote auction = auctionHome.createWithData("My Auction",          "This is a test auction");        // call a business method on the remote interface        auction.setStartingBid(new Double(100.00));        System.out.println("Created auction: " + auction.getName() +          " with starting bid " + auction.getStartingBid());        ctx.close();      }      catch (NamingException ne) {       System.out.println(ne.getMessage());      }      catch (Exception e) {       e.printStackTrace();      }    }    public static void main(String[] args) {     EntityBeanClient auctionClient = new EntityBeanClient();      auctionClient.createAuction();    }  }