For each EJB type, WebLogic Server provides a generic class that contains Java callbacks, or listeners, that are required for most EJBs. The generic classes are in the weblogic.ejb package:

• GenericEnterpriseBean

• GenericEntityBean

• GenericMessageDrivenBean

• GenericSessionBean

You can implement a generic bean template in a class of your own by importing the generic class into the class you are writing. This example imports the GenericSessionBean class into HelloWorldEJB:

import weblogic.ejb.GenericSessionBean;
     ...     
public class HelloWorldEJB extends GenericSessionBean { 

The following sections provide guidelines for programming client access to an EJB.

Local clients obtain initial context using the getInitialContext method, similar to the following excerpt.

...
Context ctx = getInitialContexLt("t3://localhost:7001", "user1", "user1Password");
...
static Context getInitialContext(String url, String user, String password) { 
    Properties h = new Properties();
        "weblogic.jndi.WLInitialContextFactory");
    h.put(Context.PROVIDER_URL, url);
    h.put(Context.SECURITY_PRINCIPAL, user);
    h.put(Context.SECURITY_CREDENTIALS, password); 

    return new InitialContext(h);
}

A client can look up the entity bean's home interface in one of two ways:

• By following an EJB reference. This approach offers better performance than the alternative, looking up the home interface directly from the Java Naming and Directory Interface, and is a Oracle best practice. For instructions on using EJB references, see the following section, Using EJB Links.

• Directly from the Java Naming and Directory Interface (JNDI). The container binds the entity bean's home interface in the global, server-side JNDI name space. See Developing JNDI Applications for Oracle WebLogic Server.

• Using EJB Links
  

To enable an EJB to open an HttpURLConnection to an external HTTP server using the java.net.URL resource manager connection factory type, specify the URL, or specify an object bound in the JNDI tree that maps to a URL, using the resource-ref element in ejb-jar.xml and the res-ref-name element in weblogic-ejb-jar.xml.

1. In ejb-jar.xml, specify the URL in the <jndi-name> element of the resource-ref element.
2. In weblogic-ejb-jar.xml, specify the URL in the <jndi-name> element of the resource-description element:

   <resource-description>
       <res-ref-name>url/MyURL</res-ref-name>
       <jndi-name>http://www.rediff.com/</jndi-name>
   </resource-description>
   

   WebLogic Server creates a URL object with the jndi-name provided and binds the object to the java:comp/env.

1. In ejb-jar.xml, specify the name by which the URL is bound in JNDI in the <jndi-name> element of the resource-ref element.
2. In weblogic-ejb-jar.xml, specify the name by which the URL is bound in JNDI in the <jndi-name> element of the resource-description element:

   <resource-description>
       <res-ref-name>url/MyURL1</res-ref-name>
       <jndi-name>firstName</jndi-name>
   </resource-description>
   

   where firstName is the object bound to the JNDI tree that maps to the URL. This binding could be done in a startup class. When jndi-name is not a valid URL, WebLogic Server treats it as an object that maps to a URL and is already bound in the JNDI tree, and binds a LinkRef with that jndi-name.

Regardless of how you specified an HTTP resource—by its URL or a JNDI name that maps to the URL—you can access it from EJB code in this way:

URL url = (URL) context.lookup("java:comp/env/url/MyURL");
connection = (HttpURLConnection)url.openConnection();

You can control the attributes of the network connection an EJB uses for communications by configuring a custom network channel and assigning it to the EJB. For information about WebLogic Server network channels and associated configuration instructions see Configure Network Resources in Administering Server Environments for Oracle WebLogic Server. After you configure a custom channel, assign it to an EJB using the network-access-point element in weblogic-ejb-jar.xml.

Transaction design decisions are discussed in Transaction Design and Management Options. The following sections contain guidelines for programming transactions.

For information using transactions with entity beans, see Understanding ejbLoad() and ejbStore() Behavior.

Container-managed transactions are simpler to program than bean-managed transactions, because they leave the job of demarcation—starting and stopping the transaction—to the EJB container.

You configure the desired transaction behaviors in ejb-jar.xml and weblogic-ejb-jar.xml. For related information see Container-Managed Transactions Elements.

Key programming guidelines for container-managed transactions include:

• Preserve transaction boundaries—Do not invoke methods that interfere with the transaction boundaries set by the container. Do not use:

  • The commit, setAutoCommit, and rollback methods of java.sql.Connection

  • The getUserTransaction method of javax.ejb.EJBContext

  • Any method of javax.transaction.UserTransaction

• Roll back transactions explicitly—To cause the container to roll back a container-managed transaction explicitly, invoke the setRollbackOnly method of the EJBContext interface. (If the bean throws an application exception, typically an EJBException, the rollback is automatic.)

• Avoid serialization problems—Many data stores provide limited support for detecting serialization problems, even for a single user connection. In such cases, even with transaction-isolation in weblogic-ejb-jar.xml set to TransactionSerializable, exceptions or rollbacks in the EJB client might occur if contention occurs between clients for the same rows. To avoid such exceptions, you can:

  • Include code in your client application to catch SQL exceptions, and resolve them appropriately; for example, by restarting the transaction.

  • For Oracle databases, use the transaction isolation settings described in isolation-level.

1. Make sure your bean is a container-managed session or entity bean.

   You can configure automatic retry of container-managed transactions for container-managed session and entity beans only. You cannot configure automatic retry of container-managed transactions for message-driven beans because MDBs do not acknowledge receipt of a message they are processing when the transaction that brackets the receipt of the message is rolled back; messages are automatically retried until they are acknowledged. You also cannot configure automatic retry of container-managed transactions for timer beans because, when a timer bean's ejbTimeout method starts and is rolled back, the timeout is always retried.

2. Make sure the business methods for which you want to configure automatic retry of transactions are defined in the bean's remote or local interface or as home methods (local home business logic that is not specific to a particular bean instance) in the home interface; the methods must have one of the following container-managed transaction attributes:

   • RequiresNew. If a method's transaction attribute (trans-attribute element in ejb-jar.xml) is RequiresNew, a new transaction is always started prior to the invocation of the method and, if configured, automatic retry of transactions occurs if the transaction fails.

   • Required. If a method's transaction attribute (trans-attribute element in ejb-jar.xml) is Required, the method is retried with a new transaction only if the failed transaction was begun on behalf of the method.

   For more information on:

   • Programming interfaces, see Create EJB Classes and Interfaces.

   • The trans-attribute element in ejb-jar.xml, see trans-attribute in Container-Managed Transactions Elements.

3. Make sure the methods for which you want to enable automatic retry of transactions are safe to be re-invoked. A retry of a failed method must yield results that are identical to the results the previous attempt, had it been successful, would have yielded. In particular:

   • If invoking a method initiates a call chain, it must be safe to reinvoke the entire call chain when the method is retried.

   • All of the method's parameters must be safe for reuse; when a method is retried, it is retried with the same parameters that were used to invoke the failed attempt. In general, parameters that are primitives, immutable objects, or are references to read-only objects are safe for reuse. If a parameter is a reference to an object that is to be modified by the method, reinvoking the method must not negatively affect the result of the method call.

   • If the bean that contains the method that is being retried is a stateful session bean, the bean's conversational state must be safe to re-invoke. Since a stateful session bean's state is not transactional and is not restored during a transaction rollback, in order to use the automatic retry of transactions feature, you must first be sure the bean's state is still valid after a rollback.

4. Specify the methods for which you want the EJB container to automatically retry transactions and the number of retry attempts you want the EJB container to make in the retry-methods-on-rollback element in weblogic-ejb-jar.xml.

   The retry-count subelement to retry-methods-on-rollback can also be modified via the WebLogic Server Administration Console.

This section contains programming considerations for bean-managed transactions. For a summary of the distinguishing features of bean-level transactions and a discussion of related design considerations, see Bean-Level Transaction Management.

• Demarcate transaction boundaries—To define transaction boundaries in EJB or client code, you must obtain a UserTransaction object and begin a transaction before you obtain a Java Transaction Service (JTS) or JDBC database connection. To obtain the UserTransaction object, use this command:

  ctx.lookup("javax.transaction.UserTransaction");
  

  After obtaining the UserTransaction object, specify transaction boundaries with tx.begin(), tx.commit(), tx.rollback().

  If you start a transaction after obtaining a database connection, the connection has no relationship to the new transaction, and there are no semantics to "enlist" the connection in a subsequent transaction context. If a JTS connection is not associated with a transaction context, it operates similarly to a standard JDBC connection that has autocommit equal to true, and updates are automatically committed to the datastore.

  Once you create a database connection within a transaction context, that connection is reserved until the transaction commits or rolls back. To optimize performance and throughput, ensure that transactions complete quickly, so that the database connection can be released and made available to other client requests.

  Note:

  You can associate only a single database connection with an active transaction context.

• Setting transaction isolation level—For bean-managed transactions, you define isolation level in the bean code. Allowable isolation levels are defined on the java.sql.Connection interface. For information on isolation level behaviors, see isolation-level.

  See Example 4-3 for a code sample.

• Avoid restricted methods—Do not invoke the getRollbackOnly and setRollbackOnly methods of the EJBContext interface in bean-managed transactions. These methods should be used only in container-managed transactions. For bean-managed transactions, invoke the getStatus and rollback methods of the UserTransaction interface.

• Use one connection per active transaction context—You can associate only a single database connection with an active transaction context.

import javax.transaction.Transaction;
import java.sql.Connection
import weblogic.transaction.TxHelper:
import weblogic.transaction.Transaction;
import weblogic.transaction.TxConstants;
User Transaction tx = (UserTransaction)
ctx.lookup("javax.transaction.UserTransaction");
//Begin user transaction
    tx.begin();
//Set transaction isolation level to TransactionReadCommitted
Transaction tx = TxHelper.getTransaction();
    tx.setProperty (TxConstants.ISOLATION_LEVEL, new Integer
    (Connection.TransactionReadCommitted));
//perform transaction work 
    tx.commit();

This section describes two approaches for distributing a transaction across multiple beans, which may reside on multiple server instances.

• Calling multiple EJBs from a client's transaction context
  
• Using an EJB "Wrapper" to Encapsulate a Cross-EJB Transaction
  

You can configure two types of EJB timer services: clustered or local.

Clustered EJB timer services provide the following advantages:

• Better visibility.

  Timers are accessible from any node in a cluster. For example, the javax.ejb.TimerService.getTimers() method returns a complete list of all stateless session or message-driven bean timers in a cluster that were created for the EJB. If you pass the primary key of the entity bean to the getTimers() method, a list of timers for that entity bean are returned.

• Automatic load balancing and failover.

  Clustered EJB timer services take advantage of the load balancing and failover capabilities of the Job Scheduler.

For information about the configuring a clustered EJB timer service, see Configuring Clustered EJB Timers.

Local EJB timer services execute only on the server on which they are created and are visible only to the beans on that server. With a local EJB timer service, you do not have to configure a cluster, database, JDBC data source, or leasing service, as you do for clustered EJB timer services.

You cannot migrate a local EJB timer object from one server to another; timer objects can only be migrated as part of an entire server. If a server that contains EJB timers goes down for any reason, you must restart the server or migrate the entire server in order for the timers to execute.

Enterprise bean timers are of two types: programmatic timers and automatic timers.

• About the Enterprise Bean Programmatic Timers
  
• About the Enterprise Bean Automatic Timers
  

This section summarizes the Java programming interfaces defined in the EJB 2.1 Specification that you can use to program timers. For detailed information on these interfaces, refer to the EJB 2.1 Specification. This section also provides details about the WebLogic Server-specific timer-related interfaces.

WebLogic Server-specific interfaces you can use to program timers include:

• weblogic.management.runtime.EJBTimerRuntimeMBean—provides runtime information and administrative functionality for timers from a particular EJBHome. The weblogic.management.runtime.EJBTimerRuntimeMBean interface is shown in Example 4-4.

• weblogic.ejb.WLTimerService interface—extends the javax.ejb.TimerService interface to allow users to specify WebLogic Server-specific configuration information for a timer. The weblogic.ejb.WLTimerService interface is shown in Example 4-5; for information on the javax.ejb.TimerService, see the EJB 2.1 Specification.

  Note:

  The weblogic.ejb.WLTimerService interface is not supported by the clustered EJB timer service, as described in Configuring Clustered EJB Timers.

• weblogic.ejb.WLTimerInfo interface—used in the weblogic.ejb.WLTimerService interface to pass WebLogic Server-specific configuration information for a timer. The weblogic.ejb.WLTimerInfo method is shown in Example 4-6.

  Note:

  The weblogic.ejb.WLTimerService interface is not supported by the clustered EJB timer service, as described in Configuring Clustered EJB Timers.

• weblogic.ejb.WLTimer interface—extends the javax.ejb.Timer interface to provide additional information about the current state of the timer. The weblogic.ejb.WLTimer interface is shown in Example 4-7.

  Note:

  The weblogic.ejb.WLTimerService interface is not supported by the clustered EJB timer service, as described in Configuring Clustered EJB Timers.

public interface weblogic.management.runtime.EJBTimerRuntimeMBean {
  public int getTimeoutCount(); // get the number of successful timeout notifications that have been made
  public int getActiveTimerCount(); // get the number of active timers for this EJBHome
  public int getCancelledTimerCount(); // get the number of timers that have been cancelled for this EJBHome
  public int getDisabledTimerCount(); // get the number of timers temporarily disabled for this EJBHome
  public void activateDisabledTimers(); // activate any temporarily disabled timers
}

public interface WLTimerService extends TimerService {
  public Timer createTimer(Date initial, long duration, Serializable info,
    WLTimerInfo wlTimerInfo)
    throws IllegalArgumentException, IllegalStateException, EJBException;
  public Timer createTimer(Date expiration, Serializable info,
    WLTimerInfo wlTimerInfo)
    throws IllegalArgumentException, IllegalStateException, EJBException;
  public Timer createTimer(long initial, long duration, Serializable info
    WLTimerInfo wlTimerInfo)
    throws IllegalArgumentException, IllegalStateException, EJBException;
  public Timer createTimer(long duration, Serializable info,
    WLTimerInfo wlTimerInfo)
    throws IllegalArgumentException, IllegalStateException, EJBException;
}

public final interface WLTimerInfo {
  public static int REMOVE_TIMER_ACTION  = 1;
  public static int DISABLE_TIMER_ACTION = 2;
  public static int SKIP_TIMEOUT_ACTION  = 3;
  /**
   * Sets the maximum number of retry attempts that will be
   * performed for this timer.  If all retry attempts
   * are unsuccesful, the timeout failure action will
   * be executed.
   */
  public void setMaxRetryAttempts(int retries);
  public int getMaxRetryAttempts();
  /**
   * Sets the number of milliseconds that should elapse
   * before any retry attempts are made.
   */
  public void setRetryDelay(long millis);
  public long getRetryDelay();
  /**
   * Sets the maximum number of timeouts that can occur
   * for this timer.  After the specified number of
   * timeouts have occurred successfully, the timer
   * will be removed.
   */
  public void setMaxTimeouts(int max);
  public int getMaxTimeouts();
/**
   * Sets the action the container will take when ejbTimeout
   * and all retry attempts fail.  The REMOVE_TIMER_ACTION,
   * DISABLE_TIMER_ACTION, and SKIP_TIMEOUT_ACTION fields
   * of this interface define the possible values.
   */
  public void setTimeoutFailureAction(int action);
  public int getTimeoutFailureAction();
}

public interface WLTimer extends Timer {
  public int getRetryAttemptCount();
  public int getMaximumRetryAttempts();
  public int getCompletedTimeoutCount();
}

1. Ensure that you have configured the following:

   • A clustered domain. For more information, see Setting up WebLogic Clusters in Administering Clusters for Oracle WebLogic Server.

   • Features of the Job Scheduler, including:

     • HA database, such as Oracle, DB2, Informix, MySQL, Sybase, or MSSQL.

     • JDBC data source that is mapped to the HA database using the <data-source-for-job-scheduler> element in the config.xml file.

     • Leasing service. By default, database leasing will be used and the JDBC data source defined by the <data-source-for-job-scheduler> element in the config.xml file will be used.

   For more information about configuring the Job Scheduler, see "The Timer and Work Manager API" in Developing CommonJ Applications for Oracle WebLogic Server.

2. To enable the clustered EJB timer service, set the timer-implementation element in the weblogic-ejb-jar.xml deployment descriptor to Clustered:

   <timer-implementation>Clustered</timer-implementation>
   

   For more information, see timer-implementation.

Although infrequent, when you generate classes with appc, you may encounter a generated class name collision which could result in a ClassCastException and other undesirable behavior. This is because the names of the generated classes are based on three keys: the bean class name, the bean class package, and the ejb-name for the bean. This problem occurs when you use an EAR file that contains multiple JAR files and at least two of the JAR files contain an EJB with both the same bean class, package, or classname, and both of those EJBs have the same ejb-name in their respective JAR files. If you experience this problem, change the ejb-name of one of the beans to make it unique.

Because the ejb-name is one of the keys on which the file name is based and the ejb-name must be unique within a JAR file, this problem never occurs with two EJBs in the same JAR file. Also, because each EAR file has its own classloader, this problem never occurs with two EJBs in different EAR files.

WebLogic Server supports the use of ejb-client.jar files for packaging the EJB classes that a programmatic client in a different application requires to access the EJB.

Specify the name of the client JAR in the ejb-client-jar element of the bean's ejb-jar.xml file. When you run the appc compiler, a JAR file with the classes required to access the EJB is generated.

Make the client JAR available to the remote client. For Web applications, put the ejb-client.jar in the /lib directory. For non-Web clients, include ejb-client.jar in the client's classpath.

If you compile your EJBs with appc, you can use the appc -lineNumbers command option to add line numbers to generated class files to aid in debugging. For information, see appc Reference.

WebLogic Server collects a variety of data about the run-time operation of a deployed EJB. This data, which you can view in the Deployments node of the WebLogic Server Administration Console, can be useful in determining if an EJB has completed desired processing steps. To access EJB run-time statistics, expand the Deployment node in the WebLogic Server Administration Console, navigate to the JAR EAR that contains the bean, and select the Monitoring tab.

For information about the data available, see these pages in Oracle WebLogic Server Administration Console Online Help:

• Deployments-->EJB --> Monitoring --> Stateful Session EJBs

• Deployments-->EJB-->Monitoring-->Stateless EJBs

• Deployments-->EJB --> Monitoring--> Message-Driven EJBs

• Deployments-->EJB --> Monitoring --> Entity EJBs

For instructions on how to create messages in your application to help you troubleshoot and solve bugs and problems, see Configuring Log Files and Filtering Log Messages for Oracle WebLogic Server.

Oracle JDeveloper is a full-featured Java IDE that can be used for end-to-end development of EJBs. For more information, see the Oracle JDeveloper online help. For information about installing JDeveloper, see Installing Oracle JDeveloper.

Oracle Enterprise Eclipse (OEPE) provides a collection of plug-ins to the Eclipse IDE platform that facilitate development of WebLogic Web services. For more information, see the Eclipse IDE platform online help.

The javac compiler provided with the Java SE JDK provides java compilation capabilities. For information on javac, see http://www.oracle.com/technetwork/java/index-jsp-142903.html#documentation.

EJBGen is an EJB 2.x code generator. You can annotate your bean class file with javadoc tags and then use EJBGen to generate the remote and home interface classes and the deployment descriptor files for an EJB application, reducing to one the number of EJB files you need to edit and maintain.

Oracle recommends that you use EJBGen to generate deployment descriptors; this is a Oracle best practice which allows for easier and simpler maintenance of EJBs. When you use EJBGen, you have to write and annotate only one bean class file, which simplifies writing, debugging, and maintenance. If you use Oracle Workshop for WebLogic Platform as a development environment, Workshop automatically inserts EJBGen tags for you.

For information on EJBGen, see EJBGen Reference.

DDInit is a utility for generating deployment descriptors for WebLogic Server applications. DDInit uses information from the class files to create deployment descriptor files.

See DDInit in Command Reference for Oracle WebLogic Server.

WebLogic Server includes Ant utilities to create skeleton deployment descriptors.

The Ant task examines a directory containing an EJB and creates deployment descriptors based on the directory contents. Because the Ant utility does not have information about all desired configurations and mappings for your EJB, the skeleton deployment descriptors the utility creates are incomplete. After the utility creates the skeleton deployment descriptors, you can use a text editor or an XML editor to edit the deployment descriptors and complete the configuration of your EJB.

See Deploying Applications Using wldeploy in Developing Applications for Oracle WebLogic Server.

The weblogic.Deployer command-line tool is a Java-based deployment tool that provides a command line interface to the WebLogic Server deployment API. This tool was developed for administrators and developers who need to initiate deployment from the command line, a shell script, or any automated environment other than Java.

See weblogic.Deployer Command-Line Reference in Deploying Applications to Oracle WebLogic Server.

The appc compiler generates and compiles the classes needed to deploy EJBs and JSPs to WebLogic Server. It validates the deployment descriptors for compliance with the current specifications at both the individual module level and the application level. The application-level checks include checks between the application-level deployment descriptors and the individual modules as well as validation checks across the modules.

See appc Reference.

DDConverter is a command line tool that upgrades deployment descriptors from earlier releases of WebLogic Server. Oracle recommends that you always upgrade your deployment descriptors in order to take advantage of the features in the current Java EE specification and release of WebLogic Server.

You can use weblogic.DDConverter to upgrade your deployment descriptors. For information on using weblogic.DDConverter, see Developing Applications for Oracle WebLogic Server.