Using an Existing EJB Control

This topic describes how to use an existing EJB control in your web service.

To learn about controls, see the Controls Overview.

To learn about EJB controls, see EJB Control: Using Enterprise Java Beans from a Web Service.

To learn how to create a EJB control, see Creating a New EJB Control .

# Using an Existing EJB Control

All controls follow a consistent model. Therefore, most aspects of using an existing EJB control are identical to using any other existing control.

To learn about using an existing control, see Using an Existing Control.

## EJB Interfaces Required

In order for WebLogic Workshop to provide code completion and otherwise successfully represent the target EJB, the EJB's client interfaces must be available to WebLogic Workshop. You make the EJB's client interfaces available by placing the EJB's client JAR file or the EJB JAR file in the WEB-INF/lib directory of your WebLogic Workshop project.

If you copy an existing EJB control from one WebLogic Workshop project to another, you must also copy the associated JAR file(s) containing the EJB's client interfaces.

## Invoking EJB Methods

You invoke methods on the target EJB by invoking the method of the same signature on the EJB control. If the EJB interfaces are available to the WebLogic Workshop visual development environment as described in the preceding section, the Source View will provide code completion for EJB method names and method parameter lists.

To see all methods available for an EJB control, type the name of the EJB control instance followed by a period ("."). For example, "account." where account is the variable name of the control instance.

To see the arguments for a method, type the control instance name, period, the method name, then an opening parenthesis. For example, "account.withdraw(" where account is the variable name of the control instance.

### Invoking Secured EJB Methods

EJB interfaces or individual EJB methods may be secured using WebLogic Server security mechanisms. If you want to access methods of an EJB that have been secured, the JWS performing the access must also be secured. To learn more about securing WebLogic Workshop web services, see Overview: Security.

You may also want to refer to the WebLogic Server documentation on security, which you can find at BEA WebLogic Server Security on the BEA edocs.bea.com site.

## EJB Instance Selection

The EJB control automatically manages references to EJB instances and directs method invocations to the correct instance of the target EJB automatically. The following sections describe what happens when you invoke various EJB methods. What happens depends on whether the target EJB is a Session Bean or an Entity Bean.

## Session Beans

### The create Method

If the target EJB is a Session Bean, you do not need to invoke a create method of the EJB. The EJB control will automatically create and cache a reference to an appropriate instance of the EJB whenever one of the EJB's business methods is invoked.

Note that the create method for a Session Bean may not create a new instance of the bean; the server may return an existing instance from a pool.

### EJB Reference Caching

As described in the preceding paragraph, a reference to a EJB instance is created whenever one of the EJB's business methods is called. This reference is cached in the EJB control and is used for any subsequent calls to the EJB within the current web service method invocation. Remember that the EJB control is being used by a web service. For Session Beans, the lifetime of the reference is the lifetime of the web service method invocation in the reference was created.

Any explicit call to a Session Bean's create method will replace the previously cached reference (if any) with the newly created reference.

Note: The lifetime of the cached EJB reference within the EJB control depends on the type of the target EJB. If the target EJB is a Session Bean, the EJB reference's lifetime is the lifetime of the current web service method invocation.

### The remove Method

When you call the remove method on an EJB control that represents a Session Bean, the currently cached instance of the bean is released. The server may destroy the bean at that time, but the actual behavior is up to the server.

## Entity Beans

Instances of Entity Beans, unlike Session Beans, are associated with a particular collection of data. Typically this collection of data is a row in a database table. Therefore, the creation and selection of Entity beans works differently from Session beans.

### The create Method

To create an instance of an Entity Bean, you may invoke the EJB's create method explicitly. For Entity Beans, the create method creates a new row in the underlying database table (that is, a new persistent entity).

### The findByPrimaryKey or findXxx Methods

Entity Bean instances may also be referenced by calling the findByPrimaryKey method or another findXxx method provided by the EJB's designer.

### EJB Reference Caching

The EJB control caches a reference to Entity Bean instance being used in the current conversation. In the case of Entity Beans, this is the instance returned by the most recent call to create, findByPrimaryKey or findXxx. When you invoke subsequent methods on the EJB control, the EJB control will invoke that method on the bean instance to which the cached reference refers. If there is no EJB reference currently cached, the EJB control will attempt to invoke findByPrimaryKey with the last successful key used in a create or findByPrimaryKey call. If there is no previous key, the EJB control will throw an exception.

Note: The lifetime of the cached EJB reference within the EJB control depends on the type of the target EJB. If the target EJB is an Entity Bean, the EJB reference's lifetime is the lifetime of the web service conversation. For web service methods that are not conversational (ie. marked with @jws:conversation phase="none"), the lifetime of the conversation (and therefore the EJB reference) is the lifetime of the web service method invocation.

### Finder Methods that Return Multiple Records

A findXxx method may return an Enumeration or a Collection object. The EJB control does not cache this object. If you wish to cache the return value of a findXxx method, you should store the object in a member variable of your (conversational) web service.

To learn how to persist state with conversations, see Maintaining State with Conversations.

### The remove Method

When you call the remove method on an EJB control that represents an Entity Bean, the record represented by the cached EJB reference is removed from the underlying persistent storage (ie. the row is deleted from the database table).

Related Topics

Overview: Enterprise Java Beans (EJBs)

Creating a New EJB Control

Maintaining State with Conversations