OpenEJB - Container System                                     D. Blevins
Getting Started Guide: GSG-1                                 October 2000


                   Getting Started Guide -- The RI Server                   


Abstract

  This document contains basic information on how to use OpenEJB's Reference 
  Implementation (RI) Server.


Table of Contents
   
   1   Introduction
   2   Starting the RI Server
   2.1   Configuring the RI Server's CLASSPATH
   2.2   Configuring the RI Server's properties
   2.2.1   openejb_config_file
   2.2.2   naming_server_properties_file
   2.2.3   ri_host_ip
   2.2.4   ri_host_port
   3   Starting a sample Client
   3.1   Configuring the Client's CLASSPATH
   4   References


1  Introduction
  
  The Reference Implementation (RI) Server is a simple implementation of an
  application server and is designed to illustrate the responsibilities of a
  server that uses the OpenEJB container system[1].  

  The RI Server platform's intended uses:
  - By Application Server Vendors as a reference for integrating OpenEJB into
    their own application server platform.
  - By Users as a demo platform for experimenting with and learning the
    OpenEJB container system.
  - By Developers as the launching pad for new functionality being developed
    in the OpenEJB container system
  - By Testers as the means for testing the operation of the OpenEJB 
    container system and compliance with the OpenEJB 0.2 and EJB 2.0 
    specifications.
    
  The reference server is NOT a production quality application server and is
  NOT intended for production environments.

  If you would like to use some of the code in the RI server in part of your
  application server, you're more than welcome.  But you would need to decide
  whether or not the code is reliable enough to meet your goals and make any
  improvements where you need them.


2  Starting the RI Server

  You can start the RI server with a command such as the one below:

    prompt$ java org.openejb.ri.server.Server <properties file>

  Where <properties file> is the location of the RiServer.properties file
  containing the configuration information needed by the RI Server.

    example 1 (Windows)
      java org.openejb.ri.server.Server C:\openejb\conf\RiServer.properties

    example 2 (Unix/Linux)
      java org.openejb.ri.server.Server /openejb/conf/RiServer.properties

  Before the RI Server can be started, the classpath in the environment the 
  server will run in needs to be setup correctly.  Also, the RI Server's 
  properties file must be configured to match the local machine.


2.1  Configuring the RI Server's CLASSPATH

  The following directories and jars from the OpenEJB repository must be in 
  the RI Server environment's classpath. 

  ./openejb/src/main
  ./openejb/src/facilities
  ./openejb/test/src
  ./openejb/lib/ejb.jar
  ./openejb/lib/jdbc-se2.0.jar
  ./openejb/lib/jndi.jar
  ./openejb/lib/jta1.0.1.jar
  ./openejb/lib/xerces.jar

  The tools.jar from the JDK 1.2.x distribution is also needed to run the RI
  Server.  Locate and add it to the classpath.  This jar can be found at 
  ./lib/tools.jar in the directory where JDK was installed.

    example 1 (Windows)
      C:\Program Files\jdk1.2.2\lib\tools.jar

    example 2 (Unix/Linux)
      /usr/local/jdk1.2.2/lib/tools.jar

  The paths of any beans, classes, or jars referenced in the 
  openejb_config_file must also be included in the classpath.

  IMPORTANT NOTE:  Be sure that Sun's J2EE Reference Implementation server 
  is NOT in your classpath or path.  This will cause mysterious problems 
  including, but not limited to: JNDI failure due to non-existent service 
  providers listed in the classpath; RMI portable object failures due to 
  library conflicts with the standard ioser12.dll and that shipped with the 
  J2EE Reference Implementation.


2.2  Configuring the RI Server's properties

  The RiServer.properties has four values that will need to be set to match 
  the paths and network configuration of the local system:
  openejb_config_file, naming_server_properties_file, ri_host_ip, and 
  ri_host_port.


2.2.1  openejb_config_file 

  Specifies the location of an OpenEJB xml configuration file. This file
  will be passed to OpenEJB where it will be parsed and used to initialize 
  the container system.

    example 1 (Windows)
      openejb_config_file=C:\\openejb\\conf\\sample_openejb_config.xml

    example 2 (Unix/Linux)
      openejb_config_file=/openejb/conf/sample_openejb_config.xml


2.2.2  naming_server_properties_file 
 
  Specifies the location of the RI Naming Server's configuration file. This 
  file is used to map JNDI names referenced by clients to deployment-ids of
  beans deployed in the openejb_config_file.

    example 1 (Windows)
      naming_server_properties_file=C:\\openejb\\conf\\naming.properties

    example 2 (Unix/Linux)
      naming_server_properties_file=/openejb/conf/naming.properties

  When the RI Server starts its JNDI naming server, the names in this file 
  are entered into the namespace and can be used by client applications to
  lookup the EJBHome object of the deployed bean.
  

2.2.3  ri_host_ip 

  Specifies the IP or host name of the local system that the RI Server will
  run on.  The RI Server will bind itself and its JNDI naming server to this 
  address at startup.  

    example 1 (RI Server is accessible by clients in the local system only)
      ri_host_ip=127.0.0.1

    example 2 (RI Server is accessible by clients in the local network only)
      ri_host_ip=192.168.1.1

    example 3 (RI Server is accessible by any client in the Internet)
      ri_host_ip=207.33.160.101

  This is the address that Clients will use in the java.naming.provider.url
  JNDI environment property for creating a javax.naming.InitialContext.  
  See javax.naming.Context.PROVIDER_URL for more information.


2.2.4  ri_host_port

  The port you wish to have the RI Server listening on.

    example 1 
      ri_host_port=1099 

  The RI Server's JNDI naming server always binds to port 1098.  Therefore, 
  the following would be an invalid port to bind the RI Server to:

    example (Invalid) 
      ri_host_port=1098 


3  Starting a sample Client

  There are a few sample clients in the OpenEJB repository under the 
  test/src/org/openejb/test/ directory.  These clients are short examples
  to illustrate how to connect to the RI JNDI naming server and lookup 
  beans.  They can be invoked from the command line as shown below:

    prompt$ java org.openejb.test.NamingClient <ri_host_ip>

  Where <ri_host_ip> is the host address used in the RiServer.properties   
  file passed in while starting the server.

    example 1 (RI Server was started on 127.0.0.1)
      java org.openejb.test.NamingClient 127.0.0.1

    example 2 (RI Server was started on 192.168.1.1)
      java org.openejb.test.NamingClient 192.168.1.1

    example 3 (RI Server was started on 207.33.160.101)
      java org.openejb.test.NamingClient 207.33.160.101

  The classpath in the clients environment must be configured before the 
  client can properly access the running RI Server and lookup beans.


3.1  Configuring the Client's CLASSPATH

  The following directories and jars from the OpenEJB repository must be in 
  the client environment's classpath. 

  ./openejb/test/src
  ./openejb/lib/ejb.jar
  ./openejb/lib/jndi.jar
  ./openejb/lib/RI_Client.jar

  NOTE:  The ./openejb/test/src directory contains the OpenEJB sample 
  clients and beans.  This directory is NOT required by clients that do not 
  reference the sample clients or sample beans.

  If the client uses any of the JDBC 2.0 Standard Extensions or Java 
  Transaction API, the classpath must also contain the following jars:

  ./openejb/lib/jdbc-se2.0.jar
  ./openejb/lib/jta1.0.1.jar

  The paths of any beans, classes, or jars referenced in by the client must 
  also be included in the client environment's classpath.

  The following directories from the OpenEJB repository must NEVER be in 
  the client environment's classpath:

  ./openejb/src/main
  ./openejb/src/facilities

  Having these directories in the client's classpath prevents dynamic class 
  loading of classes generated in the VM of the running RI Server.

  IMPORTANT NOTE:  Be sure that Sun's J2EE Reference Implementation server 
  is NOT in your classpath or path.  This will cause mysterious problems 
  including, but not limited to: JNDI failure due to non-existent service 
  providers listed in the classpath; RMI portable object failures due to 
  library conflicts with the standard ioser12.dll and that shipped with the 
  J2EE Reference Implementation.


4  References

   [1] R. Monson-Haefel & D. Blevins, "OpenEJB Specification: Jalapeņo 
       version", http://www.openejb.org/specification.html

