EJB3 tutorials on JBoss

Version 4

    Purpose of the tutorial:

     

    The EJB3 tutorials from JBoss are meant to be used by application developers to get acquainted with EJB3 features. There are multiple sub-tutorials each for a specific feature of EJB3. For example, there's a "stateless" tutorial which is used to explain how Stateless Session Beans in EJB3 can be developed and deployed on JBoss application server.

     

    Source:

     

    The source for EJB3 tutorials from JBoss are available at

     

    * Anonymous - http://anonsvn.jboss.org/repos/jbossas/projects/ejb3/trunk/docs/tutorial/
    * Authorized access - https://svn.jboss.org/repos/jbossas/projects/ejb3/trunk/docs/tutorial/

     

    How are the tutorials organized:

     

    The docs/tutorial is the parent of multiple sub-tutorials. For example, there is a tutorial on stateless beans under docs/tutorial/stateless. Similarly, each sub-tutorial has its own folder under the docs/tutorial. The tutorial can be built either through Maven (version 2.0.9) or through Ant (1.7). See the "Building from Source" section for details.

     

    Pre-requisites for the tutorial:

     

    The tutorial requires JBoss-5.0 GA and either Maven 2.0.9 or Ant 1.7.

     

    How the tutorials work:

     

    Each sub-tutorial generates a deployable through the build process. This deployable is then deployed to the JBossAS. The sub-tutorials also have a "client" which can be used to use these deployed tutorials.

     

    Building from Source:

     

    * Checkout the source of the tutorials:

     

    First 'cd' to the folder where you want to checkout the tutorials. Let's consider /home/jpai/EJB3Tutorials as a example. Then run either of the following two svn commands (Note: You need svn installed on your system).

     

        - Anonymous:


            [jpai@jpai EJB3Tutorials]svn co http://anonsvn.jboss.org/repos/jbossas/projects/ejb3/trunk/docs/tutorial/


        - Authroized access:


            [jpai@jpai EJB3Tutorials]svn co https://svn.jboss.org/repos/jbossas/projects/ejb3/trunk/docs/tutorial/

     

    * Set EJB3_TUTORIALS_HOME:

     

    This is NOT mandatory but will help in refering to the folder where the tutorials were checked out. As an example we checked out the tutorial source to /home/jpai/EJB3Tutorials. So let's set EJB3_TUTORIALS_HOME to point to this folder.

     

        export EJB3_TUTORIALS_HOME=/home/jpai/EJB3Tutorials

     

    At this point you are ready to build the tutorials.

     

    * Maven Users


        * Set up ~/.m2/settings.xml to include JBoss Maven2 Repos
            Instructions: http://wiki.jboss.org/wiki/Wiki.jsp?page=Maven
            Settings: http://wiki.jboss.org/wiki/Wiki.jsp?page=MavenSettings

     

        * Set MAVEN_HOME to point to Maven (2.0.9)
        * Update the PATH to include MAVEN_HOME/bin
        * Set JBOSS_HOME to point to the JBoss Application Server 5.0 GA
        * From the command prompt/shell, 'cd' to $EJB3_TUTORIALS_HOME
        * Run the following command:
       
        mvn clean install
       
        This will build the tutorials, deploy it to the JBoss server and also run the "client". You can see the output of the client on the console. For the server side logs, you can check it in %JBOSS_HOME%/server/default/log/server.log folder. TODO: We need to allow users to optionally configure the server profile to which they want to deploy (For ex: "all").

     

    * Ant Users


        * Set ANT_HOME to point to Ant (1.7)
        * Update the PATH to include ANT_HOME/bin
        * Set JBOSS_HOME to point to the JBoss Application Server 5.0 GA
        * From the command prompt/shell, 'cd' to $EJB3_TUTORIALS_HOME
        * Start the JBossAS "default" profile (This is required in the Ant approach unlike Maven approach where the server is started automatically through a Maven plugin)
        * Once the server is started successfully, run the following command:
       
        ant

     

        This command will build the tutorials, deploy it to the server and then will run the client. Finally, it will cleanup the deployed tutorial from the JBossAS (The cleanup is required since the Ant approach copies the tutorial to the deploy folder of the application server unlike the Maven approach where the deployment happens through the MainDeployer of JBossAS).

     

    Running one tutorial at a time:

     

    * Maven Users - The current version of the tutorial does not allow running one tutorial at a time. We do have plans to have this implemented.

     

    * Ant Users

     

      * From the command prompt 'cd' to the specific tutorial. For example, if you want to run the "stateless" tutorial alone, then cd to $EJB3_TUTORIALS_HOME/stateless

      * Run the following ant command to build and deploy the tutorial

     

        ant

     

      * After the above commands deploys the application on the server, run the client using the following command

     

       ant run

     

      * You will see the output on the console as well as the server.log file

      * Finally run the following command to cleanup the deployed tutorial from the server

     

       ant clean

     

     

    Building the tutorial guide :

     

    The EJB3 tutorials also come with a guide. The tutorial guide is a Maven2 project can be built by following the steps below:

     

    * 'cd' to $EJB_TUTORIALS_HOME/guide folder

    * Run the following Maven command

     

      mvn clean compile

     

    * This will create a html version of the guide under $EJB3_TUTORIALS_HOME/guide/target/docbook/html/index.html

     

     

    Report bugs or ask for enhancements:

     

    The EJB3 tutorials on JBossAS is maintained by the EJB3 team. As such, any issues or enhancements can be reported at https://jira.jboss.org/jira/browse/EJBTHREE