Java bean wrappers (access beans)

Java bean wrapper access beans allow either a session or entity bean to be used like a standard Java bean.

Like all access beans, a Java bean wrapper extends the superclass com.ibm.ivj.ejb.runtime.AbstractAccessBean.

To understand the underlying framework of Java bean wrappers, you need to be familiar with the framework characteristics described in the following sections:

The characteristics described in these sections not only comprise the essential framework of Java bean wrappers, they also comprise the basic framework on which the more complex copy helper access beans are based. Note: Java bean wrappers are not supported for beans in EJB 2.x modules that contain only a local client view.

Home interface mapping

Home interface methods that return a single instance of EJBObject are mapped to Java bean constructors. Home interface methods returning a collection of enterprise bean instances are mapped to methods that return the access bean types for the corresponding instances. All methods call the appropriate remote interface method.

A Java bean wrapper contains a no-arg constructor, which is simply a constructor that takes no arguments. The Java bean wrapper performs lazy initialization when the no-arg constructor is used. When the access bean is instantiated, it does not instantiate the enterprise bean. On a remote method call, the access bean instantiates the remote enterprise bean if it has not yet been instantiated.

When the Create an Access Bean wizard prompts you to map one of the create or finder methods defined in the home interface to the no-arg constructor of the access bean, the access bean will subsequently contain one init_xx property for each parameter of the create or finder method that was mapped to the no-arg constructor. When a key class is used in the create or finder methods for a container-managed persistence (CMP) enterprise bean, the key fields are used as the init_xx properties instead of the key class. A key field is normally declared as a simple type, which makes it easier for visual construction tools to use an access bean. When the no-arg constructor is used, the init_xx properties must be set first before any other calls to the access bean. The access bean may contain several multiple-arg constructors, each corresponding to one of the create or finder methods defined in the enterprise bean home interface.

Each finder method in the home interface that returns a collection of enterprise bean instances is mapped to a finder method in the access bean. You must first instantiate the access bean and then invoke the appropriate finder method to return a collection of access bean instances. To instantiate an enterprise bean, the access bean invokes a create or finder method defined in the enterprise bean home interface. If a no-arg constructor is used, the access bean only instantiates the actual enterprise bean when the first business method is called.

The access bean run time contains a class for handling enumerations of EJBObjects. For any home finder method that returns a java.util.Enumeration of EJBObjects, the corresponding access bean method returns a specialized Enumeration class whose nextElement() method instantiates the enterprise bean on the server side and returns an access bean instantiated using the corresponding EJBObject reference. The enterprise bean is only instantiated when nextElement() is called rather than when the finder method is called on the access bean. Also, you don't need to instantiate the access bean manually (based on the EJBObject reference). A finder that returns a Collection is supported, but there will be a persistence issue since the entire Collection is created with all of the access beans instantiated.

Remote interface mapping

Remote interface methods are mapped to Java bean methods. An enterprise bean remote method can also return an EJBObject. When this kind of method is generated in the access bean class, the return type is changed to the corresponding access bean type. This lets your client program deal with only the access bean type and inherit the benefits provided by the access bean.

JNDI mapping

A default JNDI name is generated into each access bean class. The code generator uses the JNDI name specified in the extensions editor, which by default is the home interface name. For Java bean wrappers (and copy helpers), you can change the JNDI name using setInit_JNDIName().

Generally, you don't need to change the JNDI name. However, if an enterprise bean is deployed into a different home, the administrator may add a prefix to the JNDI name to indicate the difference. To look up a home, an access bean obtains a name service context known as the rootContext, which you can construct if you know the name service URL and the name service type. Access beans provide two APIs to set the properties of the rootContext:

setInit_NameServiceTypeName()
setInit_NameServiceURLName()

However, if a client program is running in a WebSphere runtime environment, these two APIs are not needed because the rootContext is set automatically.

For setting the global JNDI URL name and type for Java bean wrappers (and copy helpers), two pairs of APIs are provided. The first pair of APIs is:

public void setInit_NameServiceTypeName(string_name)
public void setInit_NameServiceURLName(string_name)

These are instance methods, which modify the name service properties of the access bean they are called on. They are only used if the no-arg constructor of the access bean is used.

The second pair of APIs is:

public static final setGlobal_NameServiceTypeName(string_name)
public static final setGlobal_NameServiceURLName(string_name)

These are static methods applicable to Java bean wrappers (and copy helpers) used in the client program. Before instantiating a new access bean, call these methods so that the particular access bean uses the new name service type or URL when it instantiates the enterprise bean on the server side.

When multiple instances of an access bean use the same home (the same JNDI name and rootContext), the access bean class only looks up the corresponding enterprise bean home once. Each access bean class retains a class-level cache to improve the performance when instantiating an enterprise bean. During the lifetime of your client's VM, the access bean run time keeps a static cache of all home references indexed by the JNDI name, name service URL, and name service type. The client can issue a call to resetHomeCache() to reset the cache, which is useful if a particular home reference is no longer valid.

Access bean serialization

When access beans are serialized, certain access bean properties do not get serialized, such as remote interface references (EJBObject references), home interface references, and global JNDI information (name, name service URL, and name service type). However, for copy helper access beans, the cache of attributes is serialized.

Example

In the following example, the user program to create an employee is shown:

   EmployeeAccessBean aEmployee = new EmployeeAccessBean ()
   aEmployee.setInit_employeeNo ("100");
   aEmployee.setName ("IBM");
   aEmployee.setAddress ("1150 Eglinton Ave, Toronto");

 

Parent topic

Access beans