content/webapp-based-ejbs.mdtext

Title: Webapp-based EJBs
{note:title=THIS PAGE WILL BE ARCHIVED AND REMOVED}
Instructions on Webapp-based EJBs can be found at  [Collapsed EAR](collapsed-ear.html)

{note}
<a name="Webapp-basedEJBs-Introduction"></a>
# Introduction

The basic idea of this approach is that your Servlets and EJBs are together
in your war file as one app.

      * No classloader boundries between Serlvets & EJBs

      * EJBs and Servlets can share all third-party libraries (like
Spring!), no ear required.

      * Can put the web.xml and ejb-jar.xml in the same archive (the war
file).

      * EJBs can see Serlvet classes and vice versa.

How is this done?  The support for running your EJBs (OpenEJB) is loaded
into your webapp classloader and not visible to any other webapps.


<a name="Webapp-basedEJBs-NotquiteJ2EE"></a>
## Not quite J2EE

This is very different than J2EE as defined by the spec as there aren't
several levels of separation and heirarchy.  This is going to take some
getting used to and it should be understood that this style of packaging
isn't J2EE compliant.

J2EE classloading rules:

      * You cannot ever have ejbs and servlets in the same classloader.

      * Three classloader minimum; a classloader for the ear, one for each
ejb jar, and one for each war file.

      * Servlets can see EJBs, but EJBs cannot see Servlets.

  To pull that off, J2EE has to kill you on packaging:

      * You cannot have EJB classes and Servlet classes in the same
archive.

      * You need at least three archives to combine servlets and ejbs;
	1 ear containing 1 ejb jar and 1 servlet war.

      * Shared libraries must go in the ear and be included in a
	specially formatted 'Class-Path' entry in the ear's MANIFEST
	file.

Critically speaking, forcing more than one classloader on an application is
where J2EE "jumps the shark" for a large majority of people's needs.

<a name="Webapp-basedEJBs-Setup"></a>
# Setup

This is new feature for OpenEJB 1.0.

Configure OpenEJB per webapp requires the following steps:
* Copy the _openejb-loader-*.jar_ into the WEB-INF/lib directory of the
webapp that is to use EJBs deployed onto OpenEJB
* Add the _loader_ servlet definition to the WEB-INF/web.xml file of the
webapp with a valid value for openejb.home init-param.

    <servlet>
        <servlet-name>loader</servlet-name>
        <servlet-class>org.openejb.loader.LoaderServlet</servlet-class>
        <init-param>
          <param-name>openejb.loader</param-name>
          <param-value>tomcat-webapp</param-value>
        </init-param>
        <init-param>
          <param-name>openejb.home</param-name>
          <param-value>...define OPENEJB_HOME here...</param-value>
        </init-param>
        <load-on-startup>0</load-on-startup>
      </servlet>



Should you define other OpenEJB configuration settings use another
<init-param> stanza. It's just for that. These parameters are directly
passed to OpenEJB at initialization of the servlet. Think about the loader
servlet as a bridge between OpenEJB's world (EJBs) and Tomcat's world
(servlets, JSPs).

At startup OpenEJB prints out all of the configuration settings to Tomcat
logs:


    INFO: Installing web application at context path /openejb from URL
file:C:\webapps\openejb
    OpenEJB init-params:
    	param-name: openejb.home, param-value: c:\openejb
    	param-name: openejb.configuration, param-value: conf\openejb.cfg
    	param-name: openejb.base, param-value:
c:\webapps\openejb\WEB-INF\openejb
    	param-name: openejb.loader, param-value: tomcat-webapp



* Start up Tomcat and have fun with the EJBs