EJBs Demystified

Home: www.vipan.com

Vipan Singla

e-mail: vipan@vipan.com

EJBs Demystified
includes JDBC and JNDI Access

Some Information on Weblogic

Command Line Interface: To administer the running Weblogic server (say, localhost at port 7001), use the "java weblogic.admin" stand-alone Java application.
- To shutdown a Weblogic server:
```
   java weblogic.admin http://localhost:7001 SHUTDOWN system systemPWD 
```
- To verify if a server is running and ping it 23 times with 2048 bytes:
```
   java weblogic.admin http://localhost:7001 PING 23 2048  
```
- To test connection times by connecting 30 times:
```
   java weblogic.admin http://localhost:7001 CONNECT 30  
```
- To list name-object bindings in say, "cubicle" context of the Weblogic's JNDI:
```
   java weblogic.admin http://localhost:7001 LIST cubicle system systemPWD
```
- To list Weblogic version number:
```
   java weblogic.admin http://localhost:7001 VERSION  
```
- To list licenses:
```
   java weblogic.admin http://localhost:7001 LICENSES 
```
GUI (SLOWWWW!): To administer the running Weblogic server (say, localhost at port 7001), use the Weblogic console either from Windows Start menu or by issuing (after setting the Weblogic client classpath):
```
java weblogic.console
```
Web Browser: To view the configuration of the running Weblogic server (say, localhost at port 7001), go to url http://localhost:7001/AdminMain. This will call the Weblogic administration servlet which is available by default. When the authentication dialog box pops up, you MUST login as username "system" with your Weblogic system password (look in "weblogic.properties" files if you forgot).
Weblogic talks to itself using its own T3 protocol which you can also use within a Java program to talk to other Java programs connected to Weblogic (e.g. t3://localhost:7001). Replacing "t3" with "http" in clients is OK but slower. T3 is named after "Tengah" which is the old name for Weblogic.
All incoming requests to Weblogic are placed in a queue. Each request maintains the client identity.
Weblogic should be configured to start with and maintain a pool of 10 to 40 execution threads to service incoming requests from the queue.
The same Weblogic installation can be used to run multiple Weblogic servers. Default is to run the "myserver" server instance. Specify your custom configuration in "myserver/weblogic.properties" file in Java properties file format. It is read after the global "weblogic.properties" file in the Weblogic installation directory. Any repeat properties override previous global values, new ones are appended to global properties.
By default, requests connect as "guest" username. Use "system" username to get maximum authority.
By default, all users belong to "everyone" group.
To start Weblogic server, include "yourWeblogicDir\classes\boot" directory in the Java classpath.
Must use the "-D" option of the standard "java" command while starting Weblogic to add the key weblogic.class.path with a value of weblogicDir\lib\weblogicaux.jar;weblogicDir\classes; weblogicDir\license;weblogicDir\myserver\classes to the Java system properties list.
It not only allows Weblogic to activate EJBs and dynamically load classes during runtime, but also enables you to "hot-deploy" your EJBs into a running Weblogic server.
The clients that lookup your EJBs deployed in a Weblogic server MUST include some Weblogic-specific classes in their Java classpath. These are weblogicDir\lib\weblogicaux.jar;weblogicDir\classes. The file "cloudscape.jar" can also be included if using the CloudScape pure-Java file-based database (as opposed to a database server such as Oracle or MySql running on a port).

A Simple EJB Example (Stateless Session EJB)

Place each class or interface in a separate .java file of the same name as the class or interface name.
Compile using "javac". Make sure that "j2ee.jar" file is in the classpath.

Remote Interface

import javax.ejb.EJBObject;
import java.rmi.RemoteException;

public interface Converter extends EJBObject
{
   public double dollarToYen(double dollars) throws RemoteException;
   public double yenToEuro(double yen) throws RemoteException;
}

Home Interface

import java.io.Serializable;
import java.rmi.RemoteException;
import javax.ejb.CreateException;
import javax.ejb.EJBHome;

public interface ConverterHome extends EJBHome
{
    Converter create() throws RemoteException, CreateException;
}

EJB Class

import java.rmi.RemoteException;
import javax.ejb.SessionBean;
import javax.ejb.SessionContext;

public class ConverterEJB implements SessionBean
{
   public double dollarToYen(double dollars)
   {
      return dollars * 121.6000;
   }

   public double yenToEuro(double yen)
   {
      return yen * 0.0077;
   }

   public ConverterEJB() {}
   public void ejbCreate() {}
   public void ejbRemove() {}
   public void ejbActivate() {}
   public void ejbPassivate() {}
   public void setSessionContext(SessionContext sc) {}
}

Bundle the three class files in a JAR file:

jar cvf converting.jar Converter.class ConverterHome.class ConverterEJB.class

Save a "ejb-jar.xml" file under a "META-INF" directory:

<?xml version="1.0"?>

<!DOCTYPE ejb-jar PUBLIC
   '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 1.1//EN'
   'http://java.sun.com/j2ee/dtds/ejb-jar_1_1.dtd'>

<ejb-jar>
   <enterprise-beans>
      <session>
         <ejb-name>conv</ejb-name>
         <home>ConverterHome</home>
         <remote>Converter</remote>
         <ejb-class>ConverterEJB</ejb-class>
         <session-type>Stateless</session-type>
         <transaction-type>Container</transaction-type>
      </session>
   </enterprise-beans>
   <assembly-descriptor></assembly-descriptor>
</ejb-jar>

Change to the directory containing the "META-INF" directory and update "converting.jar" to contain the "META-INF" directory and its contents:
```
jar uvf <path-to>converting.jar META-INF
```
Form here on, it is Weblogic specific.

Save a "weblogic-ejb-jar.xml" under the same "META-INF" directory as the one with the "ejb-jar.xml" file:

<?xml version="1.0"?>

<!DOCTYPE weblogic-ejb-jar PUBLIC
   '-//BEA Systems, Inc.//DTD WebLogic 5.1.0 EJB//EN'
   'http://www.bea.com/servers/wls510/dtd/weblogic-ejb-jar.dtd'>

<weblogic-ejb-jar>
   <weblogic-enterprise-bean>
      <ejb-name>conv</ejb-name>
      <jndi-name>ConverterApp</jndi-name>
   </weblogic-enterprise-bean>
</weblogic-ejb-jar>

Change to the directory containing the "META-INF" directory and update "converting.jar" to contain the "META-INF" directory and its contents:
```
jar uvf <path-to>converting.jar META-INF
```
Run "weblogic.ejbc" Java stand-alone application to include weblogic-generated classes in "converting.jar" file:
```
java weblogic.ejbc converting.jar convertingWLS.jar
```

Hot deploy using "weblogic.deploy" Java stand-alone application. Enter, on one line:

java weblogic.deploy -host http://localhost -port 7001
   systemPWD ConverterApp file:///convertingWLS.jar

Write a test client to see if it works:

import javax.naming.Context;
import javax.naming.InitialContext;
import javax.rmi.PortableRemoteObject;
import Converter;
import ConverterHome;
public class ConverterClient
{
   public static void main(String[] args)
   {
      try
      {
          Context initial = new InitialContext();
          Object objref = initial.lookup("MyConverter");
          ConverterHome home =
              (ConverterHome)PortableRemoteObject.narrow(objref,
                                           ConverterHome.class);
          Converter currencyConverter = home.create();
          double amount = currencyConverter.dollarToYen(100.00);
          System.out.println(String.valueOf(amount));
          amount = currencyConverter.yenToEuro(100.00);
          System.out.println(String.valueOf(amount));
          currencyConverter.remove();
      }
      catch (Exception ex)
      {
          System.err.println("Caught an unexpected exception!");
          ex.printStackTrace();
      }
   }
}

Save the test client under "ConverterClient.java". Compile with the files "j2ee.jar", "Converter.class" and "ConverterHome.class" in the "javac" classpath. Assuming "javac" can find your classes in the current directory:
```
javac -classpath .;c:\j2ee\j2ee.jar ConverterClient.java
```
Run the client with "j2ee.jar", "Converter.class", "ConverterHome.class", "weblogicaux.jar" and weblogic's "classes" directory in the "java" classpath. Assuming "java" can find your classes in the current directory, enter on one line:
```
java -cp .;c:\j2ee\j2ee.jar;c:\weblogic\classes;
   c:\weblogic\lib\weblogicaux.jar ConverterClient
```

EJBs Demystified

An EJB is a way to instantiate an object in a different Java Virtual Machine(JVM) than the one your code is running in. You can then call this "remote" object's methods just as if you would call the methods of an object you instantiated in your own code by calling new (i.e. a local object).
The second JVM may be on the same computer as your code is on, or it may be on a networked computer accessible through a URL.
If you want, EJB servers can also automatically access databases and manage database transactions for you (entity EJBs with container-managed-persistence) without any coding on your part.^{EJB vs. RMI/CORBA}
In essence, EJBs combine the best practices of Java RMI and CORBA to make an enterprise's business logic and data available to any client on the network.

Java servlets are popular EJB clients but stand-alone Java applications, Java applets, other EJBs and non-Java programs can be clients too.
A servlet can maintain session with numerous clients and yet connect as one client to the EJB server. Thus, the server need only maintain one EJB instance per servlet instead of hundreds of EJB instances for, say, stand-alone Java application clients.
Many different servlets may connect to the same EJB server, wanting to run the same business method to validate something. So, the EJB server will still have the option of creating multiple instances of an EJB.
Servlets usually work with a session EJB which in turn works with an entity EJB.
Session EJBs serve one client at a time and should only define methods that implement business logic (such as validating form fields before storing them in the company database, or doing calculations based on data supplied to them).
Reason not to have business logic in entity EJBs: On any method call to an entity EJB, the EJB server first checks the underlying database to make sure that the entity EJB instance being accessed contains the most up-to-date data (Other clients may have modified the underlying data). This means calling the time-consuming "ejbLoad()" and "ejbStore()" methods. But the server does not do that for session EJBs, so they are faster.
Each entity EJB "instance" will contain one "row" of data (from a single table or a table "join" select statement) of the underlying database. Entity beans should only be used to pull-up or store data in some underlying database. No business logic should be there! Just get and set methods supplemented by create, find and delete methods.
Stateless session beans are faster than stateful session beans because the EJB server does not need to create a new instance for each new client and then destroy (garbage collect) it. The EJB server will just reuse pre-existing stateless instances.
When coding stateless session beans, do not even declare any attributes (data fields) for the bean class, just define methods that the client can call to execute business logic.
For each EJB, you code a minimum of two interface classes and one real-work class. For entity EJBs, you may also code one more class which represents the primary key of a row in a database.
Your EJB class extends SessionBean or EntityBean depending on which one you want.
Your "home" interface extends EJBHome interface (not implement). It is used as a factory to create, find and delete instances of your EJB class.
Your "remote" interface extends EJBObject interface (not implement). The subclass of its server-side skeleton is the actual "remote" object that your client will be accessing and calling methods on.
The instances (objects) of your EJB class ARE NOT the remote objects! Your EJB class does not even implement the remote interface or throw remote exceptions.
Only one "home" object is created and registered with the server-side JNDI. All clients get a copy of the same stub to this "home" object. They use the methods in the stub to instantiate the actual working EJB.
The "remote" object never gets registered with the JNDI. (If it did, JNDI will have hundreds of EJB objects, each registered under its own name. For example, one "remote" object for each row in the database.)
Here is how the whole EJB thing works:
1. The client first acquires a stub object from the EJB server. This stub object implements the "home" interface.^{Home Handle}
2. The client calls (one of) the "create()" method(s) declared in the "home" interface.^Find
3. The "home" stub makes a long distance call to the EJB server which calls the "home" object's corresponding "create()" method.
4. The "home" object's method:
  1. instantiates a SessionContext or EntityContext object depending on the type of EJB,
  2. instantiates a new object of your EJB class using the default no-argument constructor,
  3. sets its session or entity context by calling its "set...Context()" method,
  4. calls its "ejbCreate()" method corresponding to the one called by the client (you write the code here),
  5. instantiates a server-side "remote" object (whose class has been coded by the EJB server to implement the "remote" interface of the EJB),
  6. returns a "remote" stub object corresponding to the server-side "remote" object to the client over the wire.
5. The client "casts" the returned stub object to the "remote" interface type.^{Remote Object's Handle}
6. Now, the client is free to call any of the methods declared in the "remote" interface.
7. The "remote" stub will serialize those calls over the wire to the EJB server.
8. The EJB server will call the corresponding methods of the corresponding "remote" object.
9. The "remote" object will simply turn around and call the corresponding method of the corresponding EJB object.
10. The EJB object will actually perform some real work (what the client wanted to do in the first place).
11. After the EJB's method returns, the "remote" object passes any return values back to the client over the wire.
12. And the client is happy!
13. If no method call is received from the client for some time, the EJB server calls the "ejbPassivate()" method of the EJB object. You close any database connections here. Then, the EJB server stores the EJB's state to disk and deletes it from memory. (Stateless session EJB has no state to save.)
14. Next time a client calls a method of the passivated EJB, the EJB server retrieves the EJB from disk, loads it in memory and calls its "ejbActivate()" method. You re-establish any connections you want here. Then, the EJB server calls the client's requested method.
15. Note that no instantiated EJB object is permanently removed from memory by a running EJB server (it may be temporarily passivated). Therefore, when the client is done with its business with the EJB, it should call the "home" interface's "remove(handle or primary key)" method so that the EJB server can permanently remove it from memory, disk or database.
16. The EJB server (actually the server-side "home" object) calls the "ejbRemove()" method of the desired EJB object to give it a chance to clean up (similar to finalize() method of a class). It then removes all references to this EJB object (stateful session bean and entity beans), puts the EJB back in the pool (stateless session beans and entity beans) and DELETEs the corresponding row from the underlying database (entity beans).

Stateless session EJB

All instances are always identical.
Similar to a class file with no data attributes, just method definitions. The method code in these EJBs must not reference any attributes. Clients pass in the argument values and get back returned values or objects. The EJB object forgets it was ever called by THAT client (no state).
The EJB server is in control of these EJB objects. During startup, the EJB server will usually instantiate a "pool" of these EJB objects. When the client calls create(), the EJB server just returns the reference of one of the pre-existing EJB objects. Then, as the client requests come in, it will assign each request to any available instance since all instances are equal anyway. Thus, the EJB server ignores the EJB reference the client passed to it when making a method call. Such sharing results in maximum execution speed among all EJB types while utilizing the least server-side resources.
It is just a way to be able to call methods remotely (or locally but from a separate Java VM). Businesses use these EJBs to run business logic. For example, a Java servlet can act as a client, connect to these EJB objects, and call its methods, passing the data supplied in an HTML form. The EJB method can validate that data before writing it to the database (or calling an entity EJB to write to the database).
Although a servlet could have validated the data itself and written it to the database, by using an EJB, many servlets or applets can access the same business logic which only needs to be changed in one place instead of changing it in each client.
A stateless session EJB MUST ONLY declare one create() method with no arguments in its "home" interface! So, an EJB has to be stateful if it has more than one "create()" methods, OR "create()" methods with arguments.
You tell an EJB server whether an EJB is stateless or stateful in the "ejb-jar.xml" file.

Stateful Session EJB

Most EJBs are stateful.
Similar to a class file with both data attributes and method definitions. In fact, they are the same as a regular Java object except that these are available "remotely" (i.e. from a totally separate Java VM). This enables client-server model.
The EJB server also adds automatic transaction control, if you want it.
Every time a client calls "create()", a new instance is created and assigned to that client. No pre-instantiated pool is maintained by the EJB server.
Two stateful session beans are identical if their session contexts are equal, not their data attributes.
Multiple clients can not get the same EJB by "creating" new stateful session beans and setting their data attributes to the same values.

Entity EJB

Represent one row of a table in a database or one row of the resulting table from a table join statement.
"Home" interface extends EJBHome, "remote" interface extends EJBObject.
A entity EJB's "home" interface may not have any "create()" method, just "find...()" methods. This is because entity EJB objects can be instantiated with existing rows of a database.
Calling any "create()" method INSERTs a new row in the table.
Use a "find...()" method to access existing data in a database. The "home" interface must declare a "findByPrimaryKey()" method.
When many clients call the "findByPrimaryKey()" method and specify the same primary key, the EJB server creates only one instance of the entity EJB object with that primary key. It, however, creates remote stubs specific to each client. Your one EJB object can retrieve client-specific information through the EntityContext object.
Remember, clients never access the EJB object directly. They call the methods of the "remote" interface (stub). The EJB server passes these calls to the server-generated "remote" object WHICH, IN TURN, PLACES A LOCAL CALL TO THE CORRESPONDING METHODS OF THE EJB OBJECT.
Modifying the data attributes of an entity bean automatically "updates" the corresponding row in the underlying database table.
You can designate a single data attribute of your EJB class as the primary key in the "ejb-jar.xml" file. In most cases, your primary key class will be a Java "String" object or some other class that belongs to the standard Java package.
If no single field is unique in the database:
1. Write a primary key class with multiple data attributes which, when taken together, represent the primary key to the underlying data row.
2. Declare the same data attributes with same "name" and type in your EJB class.
3. Designate the primary key class as the "primary-key-class" in the "ejb-jar.xml" file but no "primary-key-field".
The primary key class and all its attributes must be "public" with a no-argument constructor (if you want to write one). It must be serializable so that it can be sent to the client over the wire. It must define its own public int hashcode() and public boolean equals(Object other) methods. Its data attributes must be among those persisted to the underlying database.
When you change the values in the EJB class, the EJB server automatically updates the corresponding attributes in the primary key class.
Two entity EJBs are identical if the "equals()" method of their primary key class returns true. You write the "equals()" method.
Must define an "ejbPostCreate()" method for each "create()" method in the home interface. It is usually an "empty" block of code. It is called by the EJB server after the new row has been INSERTed into the underlying database. You write code here, if ever, to pass the "remote" object of this EJB object to other EJBs.
For CMP entity EJBs, additional "find...(...)" methods in the "home" interface will need server-specific deployment-time finder code in the XML file.
For BMP, define ejbFind...(...) methods in your EJB class corresponding to each "find...(...)" method in the "home" interface.
For BMP, define your "ejbLoad()" and "ejbStore()" methods in the EJB class. The EJB server uses these to synchronize the EJB's data with the underlying database before and after EVERY CALL to a business method of the EJB class.
For BMP, define your "ejbActivate()" and "ejbPassivate()" methods in the EJB class.
Analogies:
- ejbCreate() = INSERT
- ejbStore() = UPDATE
- ejbLoad() = SELECT
- ejbRemove() = DELETE
Use a BMP entity EJB when your data spans multiple tables.

Coding an EJB

All methods in both "home" and "remote" interfaces must throw java.rmi.RemoteException.
All method arguments, return values and exceptions in both "home" and "remote" interfaces must be serializable (as they are sent over the wire).
Don't write any classes that actually implement the "home" and "remote" interfaces. EJB server will write these classes for you which call the corresponding methods in the EJB class that you write. This EJB class must implement either SessionBean or EntityBean. For each method that you declared in the "home" and "remote" interfaces, you will write the method definitions in the EJB class (some method names will need to be prefixed with the word "ejb").

It is OK to inherit the EJB class itself from any other class.
Declare all interfaces and methods as "public".
All "create()" methods must throw javax.ejb.CreateException and return the EJB's "remote" interface.
- For a stateless session EJB, the "home" interface must declare ONLY ONE "create()" method with no arguments.
- For a stateful session EJB, the "home" interface must declare AT LEAST ONE "create()" method, with or without arguments.
- For entity EJBs, the "home" interface must declare AT LEAST ONE "findByPrimaryKey()" method.
The EJB class itself must have one "ejbCreate()" method for each "create()" method in its home interface. It must return "void" (session EJB), or an object of the primary key class (entity EJB). In case of a CMP entity bean, the returned primary key object must contain "null" as the EJB server will assign the primary key before sending the result over to the client.
The EJB class must not be "static", "final" or "abstract", but it must be "public". It must not define "finalize()" method. It is not necessary to throw java.rmi.CreateExeception.
Don't use "static" variables or threads in the EJB class.
When creating an EJB object, the EJB server:
1. Calls the empty default no-argument constructor (Don't even write a constructor!)
2. Instantiates a new "remote" object specific to the calling client
3. Instantiates a new SessionContext or EntityContext object which contains the client and associated "remote" object information
4. Calls the EJB instance's "setSessionContext()" or "setEntityContext()" method (The connecting client's information is available through the passed object)
5. Finally, calls your "ejbCreate(...)" method (Write your code to initialize the object here, similar to what you would write in a constructor method)
If an EJB object is not used for some time, the EJB server calls its "ejbPassivate()" method before serializing the EJB object's state to disk. So, you can write your code, if you want, in this method to close any connections here. Next time a client comes looking for this SAME object, the EJB server retrieves it from disk and then calls its "ejbActivate()" method. So, you can write your code here to restore any connections which you want.
If the EJB server itself crashes, it forgets about the passivated EJB objects. All references (or handles) given to the clients become invalid. In other words, passivated EJB objects can only be re-activated within the same running server instance.
To permanently destroy an EJB object, the client will have to call the "home" interface's "remove()" method. The EJB server, in turn, calls the EJB objects's "ejbRemove()" method where you can write your code to prepare your EJB object for destruction (similar to what you would write, if ever, in the "finalize()" method of a regular Java object).
Declare "transient" any data attributes you don't want passivated (serialized). An example is the SessionContext object.
Don't throw java.rmi.RemoteException in the EJB class methods. It is technically not a remote object. The remote objects are the server-generated classes implementing the EJB's "home" and "remote" interfaces. The EJB instance merely responds locally to method calls from those implementations.
Under extreme circumstances, use the session or entity context's "getEJBHome()" method, and the "create()" method of the returned "home" object to self-reproduce! (i.e. an EJB instance can instantiate another instance of the same EJb class and become its client.)
You don't need to regenerate server-generated classes if you only modify the EJB class itself. Just update the previously deployed JAR file (using jar uvf ... and restart the server (or hot deploy).

Deployment Steps

You configure your EJB for deployment using the standard ejb-jar.xml file. It basically tells the EJB server the class names for the home interface, the remote interface and the real working EJB class itself. It also tells the server whether it is an entity EJB or a session EJB.
You also give a (fake) name to your EJB here and refer to this EJB with that fake name in all related .xml files. It will not be used outside the XML files for deployment. Here is a minimal example of an "ejb-jar.xml" file:
```
   <enterprise-beans>
      <session>
         <ejb-name>FibonacciComputationEJB</ejb-name>
         <home>com.bea.EJBD.examples.FibonacciComputationHome</home>
         <remote>com.bea.EJBD.examples.FibonacciComputation</remote>
         <ejb-class>com.bea.EJBD.examples.FibonacciComputationBean</ejb-class>
         <session-type>Stateless</session-type>
         <transaction-type>Container</transaction-type>
      </session>
   </enterprise-beans> 
```
You can specify multiple beans in one file, one bean per or tag-set.
All EJB servers need to know the JNDI name to which the "home" object instantiated by the EJB server should be bound. For example, Weblogic requires you to specify this in another .xml file called weblogic-ejb-jar.xml.
```
      <ejb-name>name-you-gave-in-ejb-jar.xml</ejb-name>
      <jndi-name>GreenBeans</jndi-name> 
```
The jBoss server requires "jBoss.xml" for the same purpose.
For CMP beans, you need to specify another .xml file which you can name yourself. Just specify what name you are giving this third .xml file in the "weblogic-ejb-jar.xml" file so that Weblogic can find it. This file maps the EJB attributes to-be-saved to the corresponding database fields.

Compile EJB classes and interfaces. You don't need Weblogic (or some other EJB server) specific library classes or JAR files to compile a spec-compliant EJB. You only need your code classes and the standard "j2ee.jar" file in your classpath. The "j2ee.jar" file comes with the J2EE software from Sun Microsystems. For example, enter this command on one line:
```
java -verbose -d c:\junk2 -classpath c:\junk2;
   c:\j2ee\j2ee.jar -sourcepath c:\junk c:\junk\pkg1\subpkg1\src-file.java 
```
Here is a suggested compilation order:
1. EJBObject sub-interface
2. Primary key class, if Entity EJB
3. EntityBean or SessionBean subclass
4. EJBHome sub-interface
JAR your compiled classes. Make sure that you preserve the package structure as the directory tree within the JAR file. There should be no directory visible above the package's root directory (below which all package directories are located) within the JAR file. Run jar tvf to list the JAR file contents, just to make sure. This is a standard Java requirement.
The best way to do this is to first change your current directory to just above the first directory of your package structure
```
cd c:\junk2
jar cvf c:\junk2\junky.jar pkg1  
```
This will have the effect of starting with the first directory within your package structure and recursively bundle all files and subdirectories within it, preserving the directory tree.
If you have multiple packages, run the jar uvf your-filename.jar command on each package but after changing directory to the root of each package.
Write a "META-INF/ejb-jar.xml" text file in XML format as required by the EJB spec. It is easier to open an existing file (probably provided as an example with your EJB server), modify it and save it as "ejb-jar.xml" under a "META-INF" subdirectory within your source code directory.
Update your JAR file to include the "META-INF/ejb-jar.xml" file. First change directory to just above the META-INF directory. For example, if "c:\junk" has the "META-INF" directory under it:
```
cd c:\junk
jar uvf c:\junk2\junky.jar META-INF 
```
"META-INF" must be written in all uppercase letters even if your operating system (Windows) is not case-sensitive (because Java is!).
You now have the JAR file you need to deploy your EJB in any EJB server in a server-specific way. Notice that you have not needed any server-specific classes or libraries to compile the .java files.
Update your JAR file to contain the server-specific XML files (e.g. "META-INF\weblogic-ejb-jar.xml"). Write and place additional XML files in the "META-INF" directory containing the "ejb-jar.xml" file.
```
cd c:\junk
jar uvf c:\junk2\junky.jar META-INF 
```
Note that this will pick up all the files and subdirectories of the "META-INF" directory and bundle them into the JAR file.
Some servers need RMI stubs, skeletons and other supporting classes in your JAR file before they can deploy it. You don't have to write any code, just run the server-supplied tool to generate what server needs.
Other servers take your JAR file and generate these on the fly as needed during startup and deployment.
For Weblogic, you need to run a command to do so.
```
java weblogic.ejbc c:\junk2\junky.jar c:\junk\junkyForWeblogic.jar
```
If all goes well (i.e. your code checks out OK), the computer, after a while, will come back with:
```
[EJB]: Creating output jar:wantedFinalJar.jar
```
For Weblogic, add the JAR file name in your server's "weblogic.properties" file. Be careful! Only use "/" as path separator because you will use "\" as line-continuation character.
```
weblogic.ejb.deploy=  \
   c:/junk2/junky.jar,    \
   <path-to>someOther.jar   
```
The "weblogic.ejb.deploy" property can only appear in one place and all comma-separated JAR files are to be added there.
Restart the server for the changes to take effect.

For jBoss, all you have to do is to put the jBoss-specific JAR file in its "deploy" directory. jBoss is very fast. It will automatically pick it up, generate all "home" and "remote" objects and hot deploy your EJB without ever having to stop the server and restart it.

Hot Deploy to a Running Weblogic Server

If you have the JAR file with all the server-generated classes, you can hot deploy using either the GUI console (slow!) or the command line interface (a bit faster)
1. Windows GUI: Start -> Programs -> Weblogic... -> Weblogic console -> File -> Attach Server. Then, myserver -> Distributed objects -> EJB -> Deployment units -> Commands tab -> New deployment button.
  Enter any name in the "Deployment unit name" field but enter the full absolute path name to the JAR file in the "Bean file location" field.
2. Command line interface: Use the "weblogic.deploy" stand-alone application.
```
   java weblogic.deploy -host http://www.ahost.com -port 7001 systemPWD
      EjbJndiNameWanted file:///c:/test/EJB/yourEJB.jar
```
  If you have problems running the tool, make sure that the "classes" subdirectory of your weblogic installation and the "weblogicaux.jar" file are in the "java" classpath.
  If you get errors while deploying, make sure that the JDBC drivers and databases you have specified in your EJB are in the Java classpath as well (e.g. "cloudscape.jar")
  Other commands of the "weblogic.deploy" application:
```
   java weblogic.deploy list systemPWD
   java weblogic.deploy undeploy systemPWD c:/test/EJB/yourEJB.jar
   java weblogic.deploy -help
```
If you don't have the JAR file or the XML files, create deployable JAR file and hot deploy using the GUI deployer tool.
1. On Windows, either select Start->Programs->Weblogic...->EJB Deployer or issue:
```
   java weblogic.ejb.ui.deployer.DeployerTool
```
2. Important! Set the path to your "javac" compiler in Tools->Preferences.
3. Select Projects->Developer for maximum control over deployment.
4. Select File->New to create a new JAR file.
5. Select Projects->Deployer->yourJarFileName TO MAKE THE "PROJECT" MENU APPEAR. Select Project->Edit file set menu item and add your .class (and .xml, if any) files to the JAR file.
6. Must specify a JNDI name for your EJB! Select Projects->Developer->yourJarFileName->Beans->yourBeanClassName->Classes tab.
7. If you want a stateful session bean, checkmark "Maintains conversational state". If you coded a BMP bean, checkmark "Uses bean managed persistence". If you coded a CMP mean, specify container-managed-fields under Beans->your Bean->Persistence. Always select "Weblogic RDBMS Persistence" as backing store and then specify the JDBC connection pool which must already be activated through your "weblogic.properties" file.
8. After adding files, press "Check Compliance" toolbar button to make sure everything is OK.
9. Press "Generate container" toolbar button to create a deployable JAR file. It takes a while for those rotating gears to crunch up a JAR file!
10. Press "Deploy" toolbar button to hot deploy your bean to a running server (Specify the server to deploy to under Servers).
11. If a message pops up saying "Done", the EJB is deployed! You can connect to it from a client written for this EJB.

Weblogic XML Deployment Files Examples

Here are some minimal XML files as required by the Weblogic server for various types of EJBs.
In the XML file examples below, "META-INF/ejb-jar.xml" file is in the standard J2EE format and is always required by all EJB servers.

Set of XML files required for deploying a stateless or stateful session EJB on Weblogic:

"META-INF/ejb-jar.xml" file: (Change Stateful to Stateless for a stateless session EJB)

<?xml version="1.0"?>
<!DOCTYPE ejb-jar PUBLIC
   '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 1.1//EN'
   'http://java.sun.com/j2ee/dtds/ejb-jar_1_1.dtd'>
<ejb-jar>
   <enterprise-beans>
      <session>
         <ejb-name>cart</ejb-name>
         <home>shop.ShoppingCartHome</home>
         <remote>shop.ShoppingCart</remote>
         <ejb-class>shop.ShoppingCartBean</ejb-class>
         <session-type>Stateful</session-type>
         <transaction-type>Container</transaction-type>
      </session>
   </enterprise-beans>
   <assembly-descriptor></assembly-descriptor>
</ejb-jar>

"META-INF/weblogic-ejb-jar.xml" file:

<?xml version="1.0"?>
<!DOCTYPE weblogic-ejb-jar PUBLIC
   '-//BEA Systems, Inc.//DTD WebLogic 5.1.0 EJB//EN'
   'http://www.bea.com/servers/wls510/dtd/weblogic-ejb-jar.dtd'>
<weblogic-ejb-jar>
   <weblogic-enterprise-bean>
      <ejb-name>cart</ejb-name>
      <jndi-name>ShoppingCartEJB</jndi-name>
   </weblogic-enterprise-bean>
</weblogic-ejb-jar>

Set of XML files required for deploying an entity EJB with container managed persistence on Weblogic:

"META-INF/ejb-jar.xml" file:

<?xml version="1.0"?>
<!DOCTYPE ejb-jar PUBLIC
   '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 1.1//EN'
   'http://java.sun.com/j2ee/dtds/ejb-jar_1_1.dtd'>
<ejb-jar>

   <enterprise-beans>
      <entity>

         <ejb-name>Transcript</ejb-name>

         <home>transcript.TranscriptHome</home>
         <remote>transcript.Transcript</remote>
         <ejb-class>transcript.TranscriptBean</ejb-class>

         <persistence-type>Container</persistence-type>

         <prim-key-class>transcript.TranscriptPK</prim-key-class>

         <reentrant>False</reentrant>

         <cmp-field>
            <field-name>school</field-name>
         </cmp-field>
         <cmp-field>
            <field-name>gpa</field-name>
         </cmp-field>
         <cmp-field>
            <field-name>degree</field-name>
         </cmp-field>
         <cmp-field>
            <field-name>id</field-name>
         </cmp-field>
         <cmp-field>
            <field-name>major</field-name>
         </cmp-field>
         <cmp-field>
            <field-name>name</field-name>
         </cmp-field>

      </entity>
   </enterprise-beans>

   <assembly-descriptor></assembly-descriptor>

</ejb-jar>

"META-INF/weblogic-ejb-jar.xml" file:

<?xml version="1.0"?>
<!DOCTYPE weblogic-ejb-jar PUBLIC
   '-//BEA Systems, Inc.//DTD WebLogic 5.1.0 EJB//EN'
   'http://www.bea.com/servers/wls510/dtd/weblogic-ejb-jar.dtd'>
<weblogic-ejb-jar>
   <weblogic-enterprise-bean>
      <ejb-name>Transcript</ejb-name>
      <persistence-descriptor>
         <persistence-type>
            <type-identifier>WebLogic_CMP_RDBMS</type-identifier>
            <type-version>5.1.0</type-version>
            <type-storage>

               META-INF/weblogic-cmp-jar.xml

            </type-storage>
         </persistence-type>
         <persistence-use>
            <type-identifier>WebLogic_CMP_RDBMS</type-identifier>
            <type-version>5.1.0</type-version>
         </persistence-use>
      </persistence-descriptor>
      <jndi-name>TranscriptEJB</jndi-name>
   </weblogic-enterprise-bean>
</weblogic-ejb-jar>

"META-INF/weblogic-cmp-jar.xml" file: (The file name is as referenced in the corresponding "META-INF/weblogic-ejb-jar.xml" file)

<?xml version="1.0"?>
<!DOCTYPE weblogic-rdbms-bean PUBLIC
 "-//BEA Systems, Inc.//DTD WebLogic 5.1.0 EJB RDBMS Persistence//EN"
 "http://www.bea.com/servers/wls510/dtd/weblogic-rdbms-persistence.dtd">
<weblogic-rdbms-bean>
   <pool-name>TranscriptPool</pool-name>
   <schema-name></schema-name>
   <table-name>Transcript</table-name>
   <attribute-map>
      <object-link>
         <bean-field>school</bean-field>
         <dbms-column>SCHOOL</dbms-column>
      </object-link>
      <object-link>
         <bean-field>gpa</bean-field>
         <dbms-column>GPA</dbms-column>
      </object-link>
      <object-link>
         <bean-field>degree</bean-field>
         <dbms-column>DEGREE</dbms-column>
      </object-link>
      <object-link>
         <bean-field>id</bean-field>
         <dbms-column>ID</dbms-column>
      </object-link>
      <object-link>
         <bean-field>major</bean-field>
         <dbms-column>MAJOR</dbms-column>
      </object-link>
      <object-link>
         <bean-field>name</bean-field>
         <dbms-column>NAME</dbms-column>
      </object-link>
   </attribute-map>
   <finder-list>
   </finder-list>
   <options>
      <use-quoted-names>false</use-quoted-names>
   </options>
</weblogic-rdbms-bean>

Set of XML files required for deploying an entity EJB with bean managed persistence on Weblogic:

"META-INF/ejb-jar.xml" file:

<?xml version="1.0"?>
<!DOCTYPE ejb-jar PUBLIC
   '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 1.1//EN'
   'http://java.sun.com/j2ee/dtds/ejb-jar_1_1.dtd'>
<ejb-jar>
   <enterprise-beans>
      <entity>
         <ejb-name>AlarmClockBMP</ejb-name>
         <home>examples.AlarmClockBMPHome</home>
         <remote>examples.AlarmClockBMP</remote>
         <ejb-class>examples.AlarmClockBMPBean</ejb-class>
         <persistence-type>Bean</persistence-type>
         <prim-key-class>examples.AlarmClockBMPPK</prim-key-class>
         <reentrant>False</reentrant>
      </entity>
    </enterprise-beans>
   <assembly-descriptor></assembly-descriptor>
</ejb-jar>

"META-INF/weblogic-ejb-jar.xml" file:

<?xml version="1.0"?>
<!DOCTYPE weblogic-ejb-jar PUBLIC
   '-//BEA Systems, Inc.//DTD WebLogic 5.1.0 EJB//EN'
   'http://www.bea.com/servers/wls510/dtd/weblogic-ejb-jar.dtd'>
<weblogic-ejb-jar>
   <weblogic-enterprise-bean>
      <ejb-name>AlarmClockBMP</ejb-name>
      <jndi-name>AlarmClockBMPEJB</jndi-name>
   </weblogic-enterprise-bean>
</weblogic-ejb-jar>

Additional standard "ejb-jar.xml" file tags:
- <env-entry>: Name, Java type and value of runtime environment variables to pass to the EJB during deployment. Similar to initialization parameters for servlets and applets. Access in your code using initCtx.lookup("java:/comp/env/your-env-name");
- <assembly-descriptor>: Defines security roles and permissions to run specific methods for different users/groups. Also specifies whether container-managed transactions are "NotSupported", "Required", "Supports", "RequiresNew", "Mandatory" and "Never" on specific EJB methods.
In addition, "weblogic-ejb-xml" file may have additional tags to control how many beans are in a pool using the <caching-descriptor> tag.

EJB Client

Your EJB client could be written as:
- A stand-alone command line application that does not use the Java Swing GUI (Best during development and testing)
- A Java servlet (Best in the production environment)
- An applet
- A stand-alone Java Swing application (Best during development and testing)
Compile your client by entering on one line: java -verbose -d c:\clientjunk -classpath c:\clientjunk; c:\j2ee\j2ee.jar -sourcepath c:\clientjunksrc c:\clientjunksrc\client-src-file.java
Note that, in the client's classpath, you will need:
- The compiled class files for the EJB's "home" and "remote" interfaces.
- All classes that appear in the "home" and "remote" interfaces as method arguments or return values so that the client can instantiate their objects, pass and receive them.
- All supporting classes and other files that any of the above depend on.
- Java 2 Enterprise Editions "j2ee.jar" file
All these required files may be bundled up in a JAR file and physically shipped to the client. The client can then just include that JAR file in its classpath.
Note that you do not need to give the actual bean implementation class (the one that extends EntityBean or SessionBean) to the client. So, you are free to make changes to it on the server side as long as the method arguments and return values in the "home" and "remote" interfaces still remain valid.
Just to compile the client, you do not need the Weblogic (or some other EJB server) specific library classes or JAR files. However, you do need these when running the client if you are connecting to the Weblogic server.
In order to actually run your client application/servlet/applet, you will need server-specific classes and JAR files in the Java classpath. For Weblogic, they are <weblogic-dir>\classes;%lt;weblogic-dir>\lib\weblogicaux.jar.
To make sure that the EJB server is running and that the EJB you want is deployed in the server. You will need to know the system password.
```
java weblogic.deploy -host http://www.ahost.com -port 7001 list systemPWD
```

Coding an EJB Client

All method calls on an EJB must be within try/catch blocks.
First, get the initial context particular to your EJB server.
Then, "lookup()" the JNDI name of EJB's home interface. A JNDI lookup on an EJB's bound name always returns a stub implementing the "home" interface of the EJB.

Use "narrow()" to check if the returned object really is of "home" interface type. Then, cast it to the "home" interface type to be able to use its methods.

import javax.naming.*;
import java.util.*;
import javax.rmi.PortableRemoteObject;
...
...
...
try {
   Properties   env = new Properties();
   env.setProperty("java.naming.factory.initial",
           "weblogic.jndi.WLInitialContextFactory");
   env.setProperty("java.naming.provider.url", "http://localhost:7001");

   Context ctx = new InitialContext(env);

   Object oj = ctx.lookup("Blnky");
   BlankyHome hm = (BlankyHome)PortableRemoteObject.narrow(
                     oj, BlankyHome.class);
} catch(NamingException e) { ... }

A "home" interface will always have these methods: remove(a-handle), remove(an-object), getEJBMetaData(), getHomeHandle().
You may also "create(...)" or "find...(...)" using the "home" interface.
"find...(...)" returns either the "remote" stub, an "Enumeration" of "remote" stubs or a "Collection" of "remote" stubs.
A "create(...)" on an entity EJB also inserts a new row in the underlying database where as a "find...(...)" does not.
Call "hm.create()" etc. which return the most-useful stub implementing the "remote" interface of the EJB. Again, make sure to use "narrow()" to check the returned object's type (a CORBA standard thing).
```
Blanky bl = (Blanky)PortableRemoteObject.narrow(hm.create(), Blanky.class); 
```
Once you have the stub which implements the remote interface, go crazy calling its methods to actually conduct your official business with the EJB (what you wanted the EJB for in the first place).
A "remote" interface will always have these methods: getEJBHome(), getHandle(), getPrimaryKey(), isIdentical(), remove().
The EJB server at this point should have instantiated a server-side "remote" object just to take care of your needs. But, what if you happen to loose the network connection to that "remote" object midway through your business? Well, you will be fine IF you had gotten a "handle" to that EJB object (bl.getHandle()) while you were still connected to the EJB object AND saved (serialized) that handle to a disk file.
Your client program can then crash, restart, retrieve the handle from the disk (which will instantiate the same handle object again), and call getEJBObject() method on that handle to reconnect to the EJB object you were dealing with. Of course, the EJB object should still exist on the EJB server.
```
//Saving the handle to a disk file
Handle handle = bl.getHandle();
try {
   ObjectOutputStream oos =
      new ObjectOutputStream(new FileOutputStream("myhandle.ser") );
   oos.writeObject(handle);
   oos.flush();
   oos.close();
}catch (Exception e) {}

//Later, retrieving the handle from the disk
//Another client can also retrieve it to "share" the EJB object!
File  handleFile = new File("myhandle.ser");
Blanky bl2;
if (handleFile.exists())
{
   FileInputStream fis = new FileInputStream(handleFile);
   ObjectInputStream ois = new ObjectInputStream(fis);
   Handle handle = (Handle) ois.readObject();
   bl2 = (Blanky) handle.getEJBObject();
} 
```
Now, call Blanky's methods on bl2 to run your business.
A side effect of using handles is that you can pass or email the serialized handle to other client programs who can also deserialize the same handle file and get connection to the same EJB object. Then, many clients can work with the same EJB object.
A handle is of no practical use in stateless session beans (no state).
Use the "remote" interface's "isIdentical()" method (not Java's "equals()" method) to see if two "remote" objects are equal and refer to the same underlying EJB instance.
The isIdentical() method on a stateless-session-EJB always returns true.
Two entity EJBs are identical if their primary key objects are equal. In response to a client's call to "isIdentical()", the EJB server calls the "equals()" method of the primary key class.
The EJB server assigns a session ID to every stateful-session-EJB but masks this ID from the outside world.

Transactions and EJBs

Sooner or later, you are going to want to do "transactions" with the databases through EJBs. You can program it yourself but, usually, you will have the EJB server manage them for you.
Transactions are ACID:
- Atomic - Either all statements execute successfully or all are rolled back
- Consistent - If any statement fails and a roll-back cannot be done right away, the system can still be accessed.
- Isolated - A transaction's changes are not visible to other operations on a database until the whole transaction successfully completes.
  This is the ideal scenario. In reality, to improve performance, there are four isolation levels:
  1. Dirty Reads: The least strict level. You are allowing your transaction to read data changed but uncommitted by other transactions.
  2. Non-Repeatable Reads: You don't want your transaction to read uncommitted data of other transactions. But, you can read the data state before or after another in-progress transaction. You may not get the same data back if you issue the same read statement after another in-progress transaction ends up COMMITing (non-repeatable).
  3. Phantom Reads - You don't want your transaction to even read existing data rows if they are being modified by other transactions. You will rather wait. (Its OK for other transactions to be INSERTing new rows, just not UPDATE existing rows.) It means that, using the same "WHERE" clause a second time, you will get the same data rows as before. IN ADDITION, you may get newly INSERTED data (rows). So, you were still operating on less data than could have been available.
  4. Serializable Transactions - The most strict level. None of the above is allowed. You want all other transactions to finish their business with the data you want to read before you will continue with your transaction.
  In EJB's UserTransaction object, you set these isolation levels as follows:
  1. "TRANSACTION_READ_UNCOMMITTED" allows dirty, non-repeatable and phantom reads (lowest isolation level).
  2. "TRANSACTION_READ_COMMITTED" allows non-repeatable and phantom reads but not dirty reads. Usually the DEFAULT.
  3. "TRANSACTION_REPEATABLE_READ" only allows phantom reads.
  4. "TRANSACTION_SERIALIZABLE" does not allow any of the dirty, non-repeatable and phantom reads and is most isolated.
- Durable - Eventually, a successful transaction WILL be written to the database(es) even if the underlying hardware or software fails and restarts.
Any of the EJB client, the EJB server or the EJB itself can BEGIN...COMMIT/ROLLBACK a transaction within their own scope. You can configure your EJB deployment to one of "TX_NOT_SUPPORTED", "TX_SUPPORTS", "TX_MANDATORY", "TX_REQUIRED", "TX_REQUIRES_NEW", and "TX_BEAN_MANAGED".
1. When the EJB server sees "TX_NOT_SUPPORTED", it will suspend the client's or its own transactions for the duration of calling this EJB's methods.
2. If the client BEGINs a transaction, calls an EJB method and the EJB server sees "TX_SUPPORTS", the EJB server will pass further client's requests for a COMMIT or a ROLLBACK to the EJB method. The EJB server will not, however, start a transaction on behalf of the client when calling this EJB's methods.
3. If the client DOES NOT BEGIN a transaction, calls an EJB method and the EJB server sees "TX_MANDATORY", the EJB server will throw TransactionRequired exception to the client without even accessing the EJB. The EJB server will not, however, start a transaction on behalf of the client when calling this EJB's methods (see "TX_REQUIRED").
4. If the client DOES NOT BEGIN a transaction, calls an EJB method and the EJB server sees "TX_REQUIRED", the EJB server will enclose the client's method call within a BEGIN...COMMIT/ROLLBACK block, in effect starting a transaction on behalf of the client, when calling this EJB's methods. This is a kindler, gentler approach to satisfy both the client and the EJB.
5. If the EJB server sees "TX_REQUIRES_NEW", it will ALWAYS enclose the client's method call within a NEW BEGIN...COMMIT/ROLLBACK block, in effect starting a new transaction on behalf of the client, when calling this EJB's methods. This happens even if the client has already started a transaction of its own (which will be suspended for the duration of call to this EJB's methods). Don't use this!
6. If the EJB server sees "TX_BEAN_MANAGED", it does not do anything, except may be suspend a client's transaction for the duration of call to this EJB's methods. Only session EJBs can manage their own transactions. You code the BEGIN...COMMIT/ROLLBACK blocks within your methods using the javax.transaction.UserTransaction interface. This interface has "begin()", "commit()" and "rollback()" methods.
You can also set each of these transaction attributes on individual methods instead of the whole EJB (since it is the methods that are being called one at a time). It can get rather unmanageable though.
For attributes other than "TX_BEAN_MANAGED", access "javax.transaction.UserTransaction" methods through the session or entity context object. (e.g. entityCtx.setRollbackOnly(); to flag the unsuccessful statement execution within your own method to the rest of the world, but not start roll-back yourself)
The EJB's conversational state or data attributes are NEVER rolled back. They are not part of any transaction. If you need to, reset them manually.

Username/Group based Access to EJB Methods

In an enterprise, you probably want to restrict access to critical EJB methods based on who is calling them.
Define method-level restrictions in the standard "ejb-jar.xml" file based on "roles" (president, admin. assistant, salesperson, customer). Use <security-role>, <role-name>, <method-permission>, <method>, <ejb-name> and <method-name> tags.
Map these roles to actual usernames or groups in a server-specific file. For example, in the "weblogic-ejb-jar.xml" file, use <security-role-assignment>, <role-name> and <principal-name> tags)

JDBC - Accessing Databases in Java Code

Type 1 driver translates its calls into ODBC calls. ODBC then interacts with the wanted database. It is the most available type.
Type 2 driver translates its calls to the native (C, C++ etc.) API calls of the wanted database and then calls the wanted database directly. Both need database-specific native drivers to be installed on the client machine.
Type 4 driver is for databases that have written their APIs in Java (as opposed to C or C++). So, no translation is needed by the driver, it calls the database using its Java API. Type 1, 2 and 4 are two-tier (client-server) drivers.
Type 3 driver is a multi-tier (n-tier) driver. It is database independent unlike Type 2 and 4 drivers. Type 3 driver itself connects to a web or application server on a network. The server, in turn, knows how to pass the driver calls to the wanted database which is also connected to the same network. The server generally talks to the wanted database using Type 1, 2 or 4 drivers.
Using a Type 3 driver, you should never have to change the client code when the back-end database changes.
First load the appropriate JDBC driver using Java's static Class.forName("some-class-name-string") method.
How it works: Class.forName() method looks for the specified .class file in the classpath of the "java" command used to execute the .class file containing this method call. If found, this method loads the .class file specified as the method argument in the running Java VM. During loading, this class registers itself with the DriverManager class.

Then, get a connection to the actual database to use or, if using a Type 3 driver, to the application server.


//////// Simple Connection
Connection connection
   = DriverManager.getConnection("jdbc:dbVendorHere:dbNameHere");

//////// Type 2 connection using a username and password
// (Pass empty strings if none required)
Properties  dbprops = new Properties();
dbprops.put("user", "scott");
dbprops.put("password", "tiger");
dbprops.put("server", "DEMO");

Connection  connection =
   DriverManager.getConnection("jdbc:weblogic:oracle", dbprops);

//////// Type 3 connection using server-side connection pools

Properties t3props = new Properties();

// Specify the URL of the Weblogic server to connect to, including port
t3props.put("weblogic.t3.serverURL", "t3://localhost:7001");

// Create "phoneBook" connection pool.  Only required parameters are shown here.
// Append to "myserver\weblogic.properties" file:
//       weblogic.jdbc.connectionPool.phoneBook=\
//          url=jdbc20:weblogic:oracle,\
//          driver=weblogic.jdbc20.oci.Driver,\
//          maxCapacity=10,\
//          capacityIncrement=1,\
//          props=user=SCOTT;password=tiger;server=DEMO
// Must also add an ACL for the connection pool
//       weblogic.allow.reserve.weblogic.jdbc.connectionPool.phoneBook=everyone

t3props.put("weblogic.t3.connectionPoolID", "phoneBook");

// (Optional) Connection name to display in Weblogic Console
t3props.put("weblogic.t3.name", "SimpleDB");

// (Optional) Your description to display in Weblogic Console
t3props.put("weblogic.t3.description", "Phone Book Connection");

// Instantiate a weblogic t3 driver object from known class name
Class.forName("weblogic.jdbc.t3.Driver");

Connection connection =
      DriverManager.getConnection("jdbc:weblogic:t3", t3props);

Statement statement = connection.createStatement();

Now, you can create or prepare your SQL statements or database-specific commands and execute them to interact with the database.
The ResultSet class extends the Enumeration class.

How to do transactions:

try
{
   connections.setAutoCommit(false);
   Statement stm = connection.createStatement();
   stm.executeUpdate("UPDATE ...");
   stm.executeUpdate("UPDATE ...");
   stm.executeUpdate("UPDATE ...");
   ...
   connection.commit();
}
catch(Exception e)
{
   connection.rollback();
}

Use Weblogic's jdbc:weblogic:t3 driver in a client-side class file. Never use this driver in a server-side class file. It always makes calls over the TCP/IP.
Here "t3" is the name of Type 3 driver that connects to the Weblogic server (no relations to Weblogic's "t3" communications protocol).
Use either the database-specific driver (e.g. jdbc.weblogic.oracle or Oracle-provided JDBC driver) or Weblogic's "POOL" driver in a server-side class file. All of these drivers support connection pooling.

Test Weblogic's connection to the database:


# Two-tier connection testing
java utils.dbping ORACLE bill secret DEMODATABASE

# Multi-tier connection testing
java utils.t3dbping http://localhost:7001 scott tiger
   DEMODATABASE weblogic.jdbc.oci.Driver jdbc:weblogic:oracle

Use JNDI to completely make your server-side or client-side code independent of the underlying database.
1. First, come up with a name (e.g. "gold") that your actual database (may be named "garbage" in the DBMS) will be known to others.
2. Then, create a connection pool (e.g. "phoneBook") in the "weblogic.properties" file that connects to "garbage" database.
```
      weblogic.jdbc.connectionPool.phoneBook=\
          url=jdbc20:weblogic:oracle,\
          driver=weblogic.jdbc20.oci.Driver,\
          maxCapacity=10,\
          capacityIncrement=1,\
          props=user=SCOTT;password=tiger;server=garbage
      #Must also add an ACL for the connection pool
      weblogic.allow.reserve.weblogic.jdbc.connectionPool.phoneBook=everyone
```
3. Then, add a line to the "weblogic.properties" file:
```
   weblogic.jdbc.DataSource.gold=phoneBook
   # Or, to support transactions (JTS)
   weblogic.jdbc.TXDataSource.gold=phoneBook 
```
4. The next time the Weblogic server starts up, it will read this line, create an object of type javax.sql.DataSource and place it in Weblogic's JNDI under the name "gold".
5. From here on, you or any other client can connect to your database by looking up "gold" in JNDI and typecasting it to the JDBC 2.0 standard class javax.sql.DataSource:
```
   javax.sql.DataSource ds = (javax.sql.DataSource) ic.lookup("gold");
   Connection connection = ds.getConnection();
```

A simple JDBC program:

import java.sql.*;

public class PrintDB {
   static String  last;
   static String  first;
   static String  phone;

   public static void main(String args[]) {

   Properties  dbprops = new Properties();
   dbprops.put("user", "sa");
   dbprops.put("password", "");
   dbprops.put("server", "DEMO");
   dbprops.put("database", "mydb");

   try {
      Class.forName("COM.cloudscape.core.JDBCDriver");
      Connection  connection =
         DriverManager.getConnection("jdbc:cloudscape:E:\\student\\SimpleDB",
                                       dbprops);

      Statement statement = connection.createStatement();
      ResultSet resultSet;
      String sql;

      statement = connection.createStatement();

      // Insert or update a database
//    sql =
//       "INSERT INTO CONTACT_TABLE (\"LAST\",\"FIRST\",\"PHONE\") VALUES ('"
//       + last + "','" + first + "','" + phone + "')";
//    statement.executeUpdate(sql);

      // printout entire database
      sql = "SELECT * FROM CONTACT_TABLE";
      resultSet = statement.executeQuery(sql);
      while (resultSet.next()) {
         last = resultSet.getString(1);
         first = resultSet.getString(2);
         phone = resultSet.getString(3);
         System.out.println("\t" + last + ", " + first + ", " + phone);
      }
      statement.close();
      resultSet.close();
      connection.close();
   } catch (Exception e) {
      System.out.println("Error:" + e);
   }
   }
}

Connection pool usage:


      // This will be passed by Weblogic's t3 (Type 3) database driver
      // to the underlying database connection object
//      Properties  dbprops = new Properties();
//      dbprops.put("user", "jose");
//      dbprops.put("password", "canaima");
//      dbprops.put("server", "theServer");
//      dbprops.put("database", "E:\\student\\SimpleDB");

      // This is for the Weblogic's t3 driver itself
      Properties  t3props = new Properties();
      t3props.put("weblogic.t3.name", "SimpleDB");
      t3props.put("weblogic.t3.description", "Phone Book Connection");
      // Pass "dbprops" to the underlying database connection
//      t3props.put("weblogic.t3.dbprops", dbprops);
      t3props.put("weblogic.t3.driverClassName",
                  "COM.cloudscape.core.JDBCDriver");
      t3props.put("weblogic.t3.driverURL", "jdbc:cloudscape");
      t3props.put("weblogic.t3.serverURL", "t3://localhost:7001");
      t3props.put("weblogic.t3.cacheRows", "100");

      // Must create a "phoneBook" connection pool in weblogic.properties file.
      // Append to "myserver\weblogic.properties" file:
      // weblogic.jdbc.connectionPool.phoneBook=\
      //    url=jdbc:cloudscape:e:\\student\\SimpleDB,\
      //    driver=COM.cloudscape.core.JDBCDriver,\
      //    initialCapacity=4,\
      //    maxCapacity=10,\
      //    capacityIncrement=2,\
      //    props=user=none;password=none;server=none
      // Must also add an ACL for the connection pool
      // weblogic.allow.reserve.weblogic.jdbc.connectionPool.phoneBook=everyone

      t3props.put("weblogic.t3.connectionPoolID", "phoneBook");

      try {
         // Instantiate a weblogic t3 driver object from known class name
         Class.forName("weblogic.jdbc.t3.Driver");

         // Get a connection object using a Type 3 database
         // (which is really just a connection pool)
         Connection  connection =
            DriverManager.getConnection("jdbc:weblogic:t3", t3props);
         Statement   statement = connection.createStatement();
      } catch(Exception e) {}

(Redundant) Notes on JNDI

Java Naming and Directory Interface (JNDI) allows you to give common, well-known names to your objects. JNDI enables Java programs to connect to real-life directory services. Programming to use a directory service is just about as hard as programming to use an RDBMS.
A "naming" service is almost similar to a computer's directory tree with files at the lowest level of each node in a tree.
A "directory" service allows assigning attributes (e.g. date modified for a file) to bound objects where as a naming service does not (just a name is assigned to a real thing, no attributes).
Popular keys for object attributes are "c", "o", "ou", "cn" (common name or first name) and "sn" (last name). The values for these keys are "objects" which are vendor-proprietory.

Objects bound in JNDI must be serializable.
Must use JNDI to access real EJB object, whether local or remote.
In case of remotely accessible objects over RMI or CORBA, only their stubs are bound to JNDI. The client looks up the object but gets its stub. This stub knows how to connect to the actual remote object and, transparent to the client, passes clients calls to the remote object and gets results.
Refer to subcontexts using "dot" delimiters. (com.bea.someContext)
Cannot add an object to a non-existent sub-context (i.e. Weblogic will not automatically create the subcontext for you, you have to create it explicitly).
Standard JNDI environment variables:
- java.naming.factory.initial (same as the Context.INTIAL_CONTEXT_FACTORY constant): Vendor-specific class file name to load to be able to read the vendor's JNDI tree.
- java.naming.provider.url (same as the Context.PROVIDER_URL constant): This will be, for example, the URL to access the Weblogic server such as http://localhost:7001. Also, you can specify initial context here which can be any subcontext under the root context.
- java.naming.factory.object (same as the Context.OBJECT_FACTORIES constant): This specifies a colon-separated list of class names for objects bound in the JNDI. When a "lookup()" method is called, JNDI finds the class name of the object, loads that class, instantiates the object (may be by deserializing its attributes) and returns the object to the calling method.
- java.naming.security.principal (same as the Context.SECURITY_PRINCIPAL constant): Username to connect to JNDI (e.g. "system"). Weblogic default is "guest".
- java.naming.security.credentials (same as the Context.SECURITY_CREDENTIALS constant): Password to authenticate the username (e.g. "systemPWD")
Must copy all the class files for the bound objects in the Weblogic classpath (e.g. in "e:\weblogic\classes" directory)

JNDI usage:

      import javax.naming.*;
      import java.util.*;
      Properties   env = new Properties();
      env.setProperty("Context.INITIAL_CONTEXT_FACTORY,
              "weblogic.jndi.WLInitialContextFactory");
      env.setProperty(Context.PROVIDER_URL, "http://localhost:7001");

/*
      // Alternative property name usage
      env.setProperty("java.naming.factory.initial",
              "weblogic.jndi.WLInitialContextFactory");
      env.setProperty("java.naming.provider.url", "http://localhost:7001");
*/

      try {
         Context     ic = new InitialContext(env);
         AddressBook ab = new AddressBook("Tom", "35 Vernon Terrace",
                                          "485-7613", 23);
         // (Re)Bind an instantiated Java object to a name in JNDI
         ic.rebind("Tom H", ab);
         // Usually, in a separate client code
//         AddressBook ab = (AddressBook) ic.lookup("Nerney");
//         System.out.println("Name: " + ab.getName());
      } catch (NamingException e) {
         e.printStackTrace();
      }

To list all names in a particular (sub)context:

NameClassPair     item = null;
NamingEnumeration enum = null;
// Instantiate "ic"  with getInitialContext.
// Then, specify context name to look into, empty string for ROOT context
enum = ic.list("");
while (enum.hasMore()) {
   // Each item on the list is an instance of NameClassPair.
   item = (NameClassPair) enum.next();
   // Get name of the object as known to JNDI
   System.out.println("Object Bound As: " + item.getName());
   // Get the actual class name to which the bound object belongs
   System.out.println("Class Type of Bound Object: " + item.getClassName() );
}

To recursively list all subcontexts and bound object names, starting with the ROOT context:

try {
   Context  initialContext = new InitialContext(env);
   printContext(initialContext, 0);
} catch (NamingException e) {
   System.out.println(e);
}

public static void printContext(Context dir, int numLevelsDeep)
{
   // The listBindings method returns a NamingEnumeration
   Binding           item = null;
   NamingEnumeration enum = null;
   try {
      enum = dir.listBindings("");
      while (enum.hasMore())
      {
         try {
            // Each item on the list is an instance of NameClassPair.
            item = (Binding) enum.next();
            // Print out some leading spaces.
            for (int i = 0; i < numLevelsDeep; i++)
            {
               System.out.print("  ");
            }
            // Check if enum.next() returned a subcontext or a bound object
            if (item.getObject() instanceof Context)
            {
               // If a Context, recursively call printContext() to print
               // content tree
               //  How to bind a superclass to a subclass!
               Context  subContext = (Context) item.getObject();
               System.out.println("DIR => " + item.getName());
               printContext(subContext, numLevelsDeep + 1);
            } else
            {
               Object   ab = (Object) item.getObject();
               System.out.println("Object => " + item.getName());
            }
         } catch (NamingException e) {
            System.out.println("Inner Exception");
            System.out.println(e);
         }
      }
   } catch (NamingException e) {
      System.out.println("Outer Exception");
      System.out.println(e);
   }
}

To pass any username and password to JNDI (For example, default user "guest" does not have list permission on the weblogic subcontext. So, specify user "system" with password "weblogic" or your weblogic system password to get administrator privileges!)
```
env.put(Context.SECURITY_PRINCIPAL, "system");
env.put(Context.SECURITY_CREDENTIALS, "weblogic"); 
```

A subcontext is like a subdirectory

Context subCtx = createSubcontext("some-name");
destroySubcontext("some-name");

To find where you are at (similar to path-to-working-directory)
```
String pwd = getNameInNameSpace();  //JNDI 1.2  
```

By default, Weblogic permits everybody to lookup objects, modify them and "list()" (but not "listBindings()") all bound objects in its JNDI. Override in "weblogic.properties" file.

#"com" is context under the root context
weblogic.allow.list.com=everyone
#Subcontexts are "dot"-delimited, groups are ","-delimited
weblogic.allow.lookup.com.abcdef=friends,family
#Or, Specify ","-delimited users
weblogic.allow.lookup.com.abcdef.xyzpqr=bob,jane

To access your local file system, use:

      env.setProperty("java.naming.factory.initial",
              "com.sun.jndi.fscontext.RefFSContextFactory");
      env.setProperty("java.naming.provider.url", "file:///");

To access an RMI registry, use:

com.sun.jndi.rmi.registry.RegistryContextFactory

Context is to cast "naming" only, DirContext is to cast "directory" services.

Working with a bound object's attributes in a "directory" service:

Attributes attrs = ( (DirContext)ctx).getAttributes("object's jndi name");
NamingEnumeration allAttrs = attrs.getAll();
While (allAttrs.hasMore() )
{
   Attribute attr = (Attribute)allAttrs.next();
   String id = attr.getID().toString();
   Attribute val =  attr.get(); //Only one value returned (vendor decides)
   NamingEnumeration values = attr.getAll();
   while (values.hasMore() )
   {
      System.out.println(values.next() );
   }
   // If a value cannot be added, nothing happens, otherwise it is added
   // to the "attr" object copy.  Underlying dir. is not modified
   attr.add("blankety blank"); //attr knows it is an id or a name etc.
   attr.remove("somevalue");
   attr.clear(); //clear all values of this attribute
   boolean isItThere = attr.contains("taco");
   int howManyValues = attr.size();
}

To write modified "attr" to the underlying dir, use modifyAttributes().

EJB vs. RMI or CORBA

Java RMI and CORBA provide the same capability as EJBs. EJBs are just easier to code. Both allow code in one Java VM to call code in another Java VM.
The simplest RMI program works like this: You instantiate an object of some class and register it with a server. Some program in another Java VM starts up, looks for your object in the (remote) server's registry, gets a stub back and calls methods on that stub.
A client may modify the remote object's data attributes through its public setter methods. To allow multiple clients to be able to do that, you will need to instantiate multiple objects on the server, one for each client. For example, say you maintain a database of, say, a thousand users with their name, address, phone etc. Your class has methods that allow users to update their information in the database. Since you don't know which user will want to update his or her information at a particular time, you will need to instantiate a thousand objects of your class, populate each object's data attributes with the data from the database, and register each object under a userid with the server. Then, a user supplies his or her user id, looks up the object, gets the stub back, and calls update methods on it.
Obviously, this model is not very scalable. You are essentially loading up the whole database in a computer's memory and never letting go.
So, the "factory design pattern" was invented. You write an additional class whose sole job is to create instances of your main remote class on demand. You unregister your main object(s) from the server and, instead, register one instance of the factory class with the server. Now the clients know to first look up this factory object and call a pre-established method on it, passing their user id, to create an instance of the real object which they want to use. The factory class calls the real class's constructor, passing the user id to it. The real class's constructor looks up that user id's data in the database and populates the new object's data attributes with it. After the real object's constructor returns, the factory class passes a stub to the newly created object to the calling user. The user can now call the stub's methods to update his information (the business he or she wanted to conduct in the first place). If a user has not called any method on an instantiated object for some time, the factory object simply destroys it, thus conserving resources.
EJBs do all that and more (database access, transactions, security etc.)
CORBA works the same way except:
- It works with Java, C++ and many other languages.
- It can "bridge" languages. A Java client may call a C++ remote object's methods and not know the difference.
- It uses a different protocol to send stubs and method calls over the network (IIOP).
You can call a (Java) EJB's methods from non-Java clients if you compiled its stubs and skeletons with IIOP option turned on. Then, all the client needs is the Java interfaces translated in CORBA IDL and then compiled into stubs in the client's language.

Home Handle

When the EJB server deploys an EJB, it instantiates a server-side object which implements the "home" interface of the EJB. Since only one such object is created, all clients get the SAME reference to an EJB's "home" interface in the "home" stub. So, why not serialize it and store it to disk? You can then just copy or email it to different clients in different Java VMs. They can deserialize it and connect to the server-side "home" object without having to do a lookup on JNDI or any such atrocity.
Better still, the EJB server can just publish the serilaized version of the reference to the "home" object at a well-known URL.
Now, "EJBHome" interface provides a public HomeHandle getHomeHandle() method. You can serialize the returned value of the "HomeHandle" type to disk just like a regular Java object.
Next time, just deserialize it and call the public EJBHome getEJBHome() method on it to reestablish connection to the server-side "home" object. If that "home" object dies in the mean time (server crashed, EJB undeployed etc.), you will get a RemoteException.

Remote Object's Handle

Each remote object is created for a specific client.
"EJBObject" interface (which the "remote" interface extends) provides a public Handle getHandle() method. You can serialize the returned value of the "Handle" type to disk just like a regular Java object.
To use the same server-side "remote" object again, just deserialize it and call the public EJBObject getEJBObject() method on it to reestablish connection to the server-side "remote" object. If that "remote" object dies in the mean time (remove() called, server crashed, EJB undeployed etc.), you will get a RemoteException.
You can pass the "handle" object or, say, email the serialized version to many clients. They can all reuse it to connect to the same "remote" and consequently, the same EJB object you are connected to. All of you can share the state of an EJB object in this way.

Miscellaneous Information

J2EE consists of EJB, JSP, servlets, J2EE Connector (to other Enterprise Information Systems), JNDI, Java IDL (an IDL-to-Java compiler and a lightweight ORB that supports IIOP), JDBC, JMS (queuing, publish/subscribe), Java Transaction API (JTA), Java Transaction Service (JTS), JavaMail, and RMI-IIOP.