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 Where 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 Where 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