Getting Started with Jonas 5
Total Page:16
File Type:pdf, Size:1020Kb
Getting started with JOnAS 5 JOnAS Team ( Philippe Coq, Guillaume Sauthier) - March 2009 - Copyright © OW2 Consortium 2007-2009 This work is licensed under the Creative Commons Attribution-ShareAlike License. To view a copy of this license,visit http://creativecommons.org/licenses/by-sa/2.0/deed.en or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA. Table of Contents Preface ........................................................................................................................ v 1. First contact with JOnAS 5 ......................................................................................... 1 1.1. How do I set up a JOnAS environment? ............................................................. 1 1.1.1. JONAS_BASE creation ......................................................................... 1 1.2. How can I check if everything is correct? ............................................................ 2 1.2.1. jonas check ......................................................................................... 2 1.3. How can I run a JOnAS server? ........................................................................ 2 1.4. How can I run my first Java EE application? ....................................................... 3 1.5. Understanding how all of this runs out of the box ................................................. 4 1.6. First step in JOnAS administration ..................................................................... 5 2. Learning JOnAS by examples ..................................................................................... 6 2.1. javaee5-earsample example from a 10.000 foot view ............................................. 6 2.1.1. Java EE Technologies in Use ................................................................. 6 2.1.2. javaee5-earsample EAR Sample Architecture ............................................. 7 2.2. javaee5-earsample example detailed ................................................................... 9 2.2.1. JOnAS Server Configuration .................................................................. 9 2.2.2. Data Tier: JPA Entity Beans ................................................................. 10 2.2.3. Business Tier: EJB3 Beans ................................................................... 15 2.2.4. Web Tier: Servlets .............................................................................. 25 2.2.5. Application Clients ............................................................................. 29 2.2.6. EAR ................................................................................................. 38 A. Download and installation instructions ........................................................................ 39 A.1. Where can I find JOnAS? .............................................................................. 39 A.2. How can I download JOnAS? ......................................................................... 39 A.3. How can I install JOnAS? .............................................................................. 39 A.4. Pre-requisites ............................................................................................... 39 B. JOnAS 5 distribution description ............................................................................... 41 B.1. JONAS_ROOT structure ................................................................................ 41 C. Glossary ................................................................................................................ 43 JOnAS 5 ii List of Figures 2.1. javaee5-earsample Sample Architecture ...................................................................... 8 2.2. Author and Book JPA Model .................................................................................. 10 JOnAS 5 iii List of Examples 2.1. JPA Entity: META-INF/persistence.xml .................................................................... 15 2.2. Stateless Session Bean: Reader Business Interface ....................................................... 16 2.3. Stateless Session Bean: Writer business Interface ........................................................ 18 2.4. Stateless Session Bean: Mailer Business Interface ....................................................... 20 2.5. An example of e-mail ............................................................................................ 30 2.6. META-INF/application-client.xml ............................................................................ 33 2.7. META-INF/jonas-client.xml .................................................................................... 33 2.8. jaas.config ........................................................................................................... 33 2.9. META-INF/application-client.xml ............................................................................ 36 2.10. META-INF/jonas-client.xml .................................................................................. 36 JOnAS 5 iv Preface Welcome new users of JOnAS ! This guide is intended to help you. Chapter 1, First contact with JOnAS 5 shows that a downloaded JOnAS 5 is usable as is. The environment to set is truly minimal. It's child's play to run a Java EE application. This chapter shows not only how to perform some actions but also explains why everything runs so easily. JOnAS 5 is distributed with examples ready to use. Users can learn a lot by studying these examples Chapter 2, Learning JOnAS by examples Theses examples may be used as a tutorial for Java EE 5 technology. They are using the simplified programming model, dependency injection, Java Persistence API, security and other functionalities available in Java EE 5. Note that this guide wants to be simple and is not intended to resolve all problems that can be encountered in real life situtations, which can be very complex. For more experimented users that need to perform more complex tasks, we recommend taking a look at the JOnAS 5 Configuration guide [configuration_guide.html] Appendix A, Download and installation instructions summarizes downloading and installing JOnAS. Appendix B, JOnAS 5 distribution description describes what you get when you download and install JOnAS. JOnAS 5 v Chapter 1. First contact with JOnAS 5 It is assumed, in this guide, that the first time user has already downloaded and installed JOnAS 5. If this is not the case, please refer to Appendix A, Download and installation instructions. In this chapter an unexperienced user will learn how to run an existing Java EE application with JOnAS. He will understand why it is so easy to achieve such results with nearly zero configuration. 1.1. How do I set up a JOnAS environment? Once you have installed your JOnAS distribution, you have to set up the JONAS_ROOT environment variable prior to using JOnAS or any of its tools. You will also have to update your PATH variable. • Unix platforms Open a new terminal and proceed as follows: bash> export JONAS_ROOT=<your_install_dir> bash> export PATH=${PATH}:${JONAS_ROOT}/bin or • Windows platforms Open a new DOS window and proceed as follows: C:> set JONAS_ROOT=<your_install_dir> C:> set PATH=%PATH%;%JONAS_ROOT%\bin To update the path permanently, do the following depending upon your Windows version: Windows XP Go to the Start Menu, then double click on System. In the System Control Panel select the Advanced tab and push the Environment Variables button. Now, you can look for the PATH to edit. Append the value ;C:\jonas-5.x\bin (assuming that you installed JOnAS in the C:\jonas-5.x directory). JOnAS distribution contains a number of configuration files in $JONAS_ROOT/conf directory. These files can be edited to change the default configuration. However, it is recommended to put the configuration files needed by a specific application running on JOnAS in a separate location. This is done by using an additional environment variable called JONAS_BASE. 1.1.1. JONAS_BASE creation 1. To create a JONAS_BASE template from scratch : Unix export JONAS_BASE=~/my_jonas_base cd $JONAS_ROOT/templates/newjb ant -f build-jb.xml create_jonas_base Windows set JONAS_BASE=my_jonas_base cd %JONAS_ROOT%/templates/newjb ant -f build-jb.xml create_jonas_base This will copy all the required files and create all the needed directories. 2. Another way to create a JONAS_BASE template from scratch : JOnAS 5 1 First contact with JOnAS 5 $JONAS_ROOT/bin must be set in the system path: Unix export JONAS_BASE=~/my_jonas_base newjb Windows set JONAS_BASE=my_jonas_base newjb The JONAS_BASE content created with the newjb command is well suited to run the JOnAS JEE conformance test suite and the example applications without any additional configuration. In order to customize a JONAS_BASE with specific property values (port numbers, services, protocols etc...), you must edit the $JONAS_ROOT/templates/newjb/build- jb.properties file or $HOME/jb.config/conf/jonas-newjb.properties file before running newjb. For further customization that cannot be performed by newjb you should modify the generated files in $JONAS_BASE/conf. For more information see the description of the newjb command in Commands Reference Guide [./command_guide.html#commands.newjb]. 1.2. How can I check if everything is correct? JOnAS provides the command jonas check that checks if your environment is set correctly. 1.2.1. jonas check Command allowing to check that the JOnAS environment is correctly set . 1.2.1.1. Synopsis jonas check [-help]