RapidEnv Example Java EE
========================

This is an example of a Java EE development environment
with JBoss, Maven and Eclipse that demonstrates the power
of automated installation, configuration and update by RapidEnv.


Highlights:
-----------

* based on one single configuration file (environment/env.xml, size < 50 kB)
  the small but powerful Java tool RapidEnv (size < 5 MB) helps you to install
  and set up a complex development einvironment (size around 600 MB) without
  any or with only a few user interactions.

* development environment specific operating system environment variables
  are controlled completely locally without polluting the global environment.

* desktop and start menu icons are provided to start and stop the components
  of the development environment.


Software installed:
-------------------

The RapidEnv environement setup and maintenance tool will set up
a standard development environment consisting in the following
software:

- jdk      Java SE Development Kit (including Java Runtime Environment)
           version 1.6.0_30 (upgrade to 1.7.0_3)

- maven    Maven build system
           version 3.0.3 (upgrade to 3.0.4)

- jboss    JBoss Application Server
           version 6.0.0.Final, (upgrade to 7.1.1.Final)

- eclipse  Eclipse IDE for Java EE developers SR2
           version 3.6.2 / Helios SR2, 3.7.1 (upgrade to 3.7.2 / Indigo SR2)

  - plugin jbosstools   JBoss integration into Eclipse
                        Version 3.2.0.GA.aggregate-Update-2011-02-16_18-30-44-H329
                        (upgrade to version 3.3.0.M5.aggregate-Update-2011-12-14_19-42-13-H61)

  - plugins m2e and m2e-wtp Maven integration into Eclipse
                         versions 0.12.1.20110112-1712 and 0.12.0.20110421-1500
                         (no upgrade so far)


System Requirements:
--------------------

2 GB of Space on your harddisk. This includes not only the
development environment but also the local repository for
installer (archive) files.S

At the moment RapidEnv basically works under Windows and Linux.
It has been tested so far with:
- Windows XP
- OpenSUSE Linux 11.4

A Java Runtime Environment (Version 1.6.x) has to be
installed in order to run the RapidEnv command line tool "renv".
Simply open a command prompt or terminal window and type
"java -version". You should be able to execute this command with
reasonable output showing a sufficient version in order to
be able to run the command line tool.


Download and install the example:
---------------------------------

The GIT way:

  If you have installed the GIT version controly system you

- Open a Windows command prompt or Unix terminal window and
  go to the folder where you want the example to be installed

- type command
  git clone git://github.com/bluemel/RapidEnvExampleJavaEE.git

Without version control:

   simply download the latest version of all sources of
   repository RapidEnvExampleJavaEE using the ZIP button
   (download this repository a zip file).


Use Cases:
----------

  - Preparation:

    Unfortunately caused by Oracle's strict download policies I had mixed expierences
    trying to automate the JDK installer download (sometimes it worked but very often not).
    So in order to work quickly through the rest of the examples I propose to download the
    two JDKs used here manually.

    - JDK 1.6.0_30
      Download web site:
        http://www.oracle.com/technetwork/java/javase/downloads/jdk-6u30-download-1377139.html
      File
        Windows x86, 32 bits: jdk-6u30-windows-i586.exe
        Linux x86, 32 bits:   jdk-6u30-linux-i586.bin
      Local folder:
        RapidEnvExampleJavaEE/toolsrepo/jdk/1.6.0_30

    - JDK 1.7.0_3
      Download web site:
        http://www.oracle.com/technetwork/java/javase/downloads/jdk-7u3-download-1501626.html
      File
        Windows x86, 32 bits: jdk-7u2-windows-i586.exe
        Linux x86, 32 bits:   jdk-7u2-linux-i586.bin
      Local folder:
        RapidEnvExampleJavaEE/toolsrepo/jdk/1.7.0_3


  1) Use Case: Setup
     Initial development environment setup
     -------------------------------------

  - open a Windows command prompt or Unix terminal window
    in folder RapidEnvExampleJavaEE/environment/bin

  - start RapidEnv by entering command:
    - Windows> renv -yes
    - Linux> . renv -yes
      Prepending . on Linux is essential to influence the
      environment settings of the current terminal window.

    This will install the development environment without
    any user interaction in 15 - 30 minutes depending of the
    speed of your internet connection and harddisk.

    On Linux typing the root user's password once might be
    necessary after 1 to 2 minutes because the JDK installation
    requires root user rights.

    Please note: if you have not downloaded the JDK installer
    beforehand RapidEnv will stop the download procedure
    open a Browser and ask you to download the JDK installer(s)
    manually. In this case you simply continue the environment
    set up after successfull download by typing:
    - Windows> renv install
    - Linux> . renv install

    Please note also: in order to achive an optimal tradeoff
    between comfort and flexibility the JDK installation is
    only done temporary. A zip file containing the whole installation
    will be built automatically and the whole installation will
    be removed afterwards. This policy will fail in case a JDK
    of the same version already installed on your machine.
    In this case currently you would have to deinstall this JDK
    (at least temporarily) or to build the zip file on your own.

  - watch the results:

    * Development environment specific command prompt / terminal window:
      Under Windows your Windows Explorer context menu now contains
      a menu entry "RapidEnv_RapidEnvExampleJavaEE_main".
      Using this menuy entry you can open a specif command prompt / terminal window
      "RapidEnv_RapidEnvExampleJavaEE main Command Prompt".
      This command prompt automatically has set up the specific environment
      variables for the example project (e. g. JAVA_HOME is now set
      to the appropriate Java installation folder).

    * Output of renv command:
      Whenever you type the "renv" command (which is now automatically
      in your current command path) you will see the properties and installation
      units of your development environment. The end of the renv command's
      output should look like this:
        ...
      Install units:
        = jdk 1.6.0_30
        = maven 3.0.3
        = jboss 6.0.0.Final
        = rapidenv-eclipseheadless 1.0.0
        = eclipse 3.6.2
        = eclipse/jbosstools 3.2.0.GA.aggregate-Update-2011-02-16_18-30-44-H329
        = eclipse/m2e 0.12.1.20110112-1712
        = eclipse/m2e-wtp 0.12.0.20110421-1500
  
    * JDK 1.6.0_30:
      Type command "java -version" in order to verify the correct environment set up.
      Expected output:
        java version "1.6.0_30"
        Java(TM) SE Runtime Environment (build 1.6.0_30-b12)
        Java HotSpot(TM) Client VM (build 20.5-b03, mixed mode)

    * Maven 3.0.3:
      Type command "mvn -version" in order to verify the correct environment set up.
      Expected output:
        Apache Maven 3.0.3 (r1075438; 2011-02-28 18:31:09+0100)
        Maven home: <root folder>\RapidEnvExampleJavaEE\tools\maven\3.0.3
        ...

    * JBoss 6.0.0.Final "Neo":
      For JBoss there is an extra start command "jboss_start" which will start
      JBoss with it's own associated console window. After JBoss has started up
      successfully it should print out a message similar to the following one:
      JBossAS [6.0.0.Final "Neo"] Started in 22s:953m
      Command "jboss_stop" will shut down JBoss and close the associated terminal window.

    * Desktop and start menu icons:
      After successfull installation of the development environment your desktop
      should contain the following desktop / start menu icons:
      - RapidEnv Example JEE JBoss start main: starts JBoss with a console window
      - RapidEnv Example JEE JBoss stop main: stops JBoss
      - RapidEnv Example JEE Eclipse main: starts Eclipse
      Under Windows you'll find the same shortcuts also under the start menu.

    * Eclipse Helios with configured JBoss (JBoss Tools plugin) and Maven (m2ecipse plugin)
      integration:

      Once you've started Eclipse the first time you should see:

      - the welcome screen: Eclipse Java EE IDE for Web Developers
      
      - a pop up dialog askig for confimation for data transfer JBoss Tools specific
        data to the JBoss Tools development team (answer what fits you best)

      - automatic build actions going on in Eclipses Progress view:
        The first time you run Eclipse you'll see the Progress view showing some
        activity with message "Update indexes". Opening the Progress window
        you schould see the percentage of the degree of filling for the
        "index" file .index/nexus-maven-repository-index.gz built together and
        used by the m2eclipse Eclipse Maven integration pugin. Unfortunately
        the whole download and index process can take up to 20 minutes.
        Better let this indexing action and all other build actions finish
        before continuing. If all has been built correctly our JEE example
        web application should be alread built and deployed / published and
        ready for take off.
    
      - specific Eclipse tool bar icons added by the JBoss Tools plugin:
        Using icon "Start JBoss 6.0 Runtime Server" you can start JBoss while
        the server process will write its output into the Eclipse Console view.

    * in order to run the example from Eclipse it should be enough to
      - start JBoss from Eclipse's toolbar (wait for the well known "started" message)
      - start the web application in the browser of your choice:
        http://localhost:8080/jeesandboxexample

    If the jeesandboxeample UI appears you have already run the first use case
    successfully but you may take your time to play around a little bit with
    the application and its development environment.


  2) Use Case: Upgrade 
     Version upgrade of different parts of the development envrionment
     -----------------------------------------------------------------

   In order to upgrade the components of your development environment
   to new versions you have usually to
   - change some settings in your environment configuration file
   - execute the RapidEnv update command

   In order to demonstrate larger changes of the development environment I've prepared
   some files that can be activated via one single command execution.

   - Open development environment specific Windows command prompt
    or Unix terminal window in folder ~\RapidEnvExampleJavaEE\environment\config
    using
    - Windows Explorer context menu entry
    - or KDE Dolphin "Actions" menu entry
    - or Gnome Nautilus "Scripts" menu entry
      "RapidEnvJavaEE Command Prompt main"

  - activate the new configuration by executing command:
    setEnvConfig7.cmd

    Let's make a short interrupt for a brief discussion of the modification we did
    (feel free to use Git / Git GUI to review the changes):
    - the largest changes of course can be found in the environment definition
      ~\RapidEnvExampleJavaEE\environment\env.xml. Mainly version numbers but also
      checksums, source URLs, and some configurations are affected.
    - besides that we need also some small modifications in project jeesandboxexample
      (.classpath, .settings/org.eclipse.wst.common.project.facet.core.xml,
      src/main/resources/META-INF/persistence.xml - new default data source).

  - start RapidEnv by entering command:
    - Windows> renv update
    - Linux>   . renv update

        This will install the development environment without
    any user interaction in 15 - 30 minutes depending of the
    speed of your internet connection and harddisk.

    On Linux typing the root user's password once might be
    necessary after 1 to 2 minutes because the JDK installation
    requires root user rights.

    Please note: if you have not downloaded the JDK installer
    beforehand RapidEnv will stop the download procedure
    open a Browser and ask you to download the JDK installer(s)
    manually. In this case you simply continue the environment
    set up after successfull download by typing again:
    - Windows> renv update
    - Linux> . renv update

  - watch the results:

    * Output of renv command:
      When you type the "renv" command you will see the update properties and
      installation units of your development environment. The end of the
      renv command's output should look like this:
        ...
        Install units:
          = jdk 1.7.0_3
          = maven 3.0.4
          = jboss 7.1.1.Final
          = rapidenv-eclipseheadless 1.0.0
          = eclipse 3.7.1
          = eclipse/jbosstools 3.3.0.M5.aggregate-Update-2011-12-14_19-42-13-H61
          = eclipse/m2e 0.12.1.20110112-1712
          = eclipse/m2e-wtp 0.12.0.20110421-1500

    * JDK 1.7.0_3:
      Type command "java -version" in order to verify the correct environment set up.
      Expected output:
        java version "1.7.0_02"
        Java(TM) SE Runtime Environment (build 1.7.0_03-b05)
        Java HotSpot(TM) Client VM (build 22.1-b02, mixed mode)

    * Maven 3.0.4:
      Type command "mvn -version" in order to verify the correct environment set up.
      Expected output:
        Apache Maven 3.0.4 (r1232337; 2012-01-17 09:44:56+0100)
        Maven home: <root folder>\RapidEnvExampleJavaEE\tools\maven\3.0.4
        ...

    * JBoss 7.1.1.Final "Brontes":
      For JBoss again the extra start command "jboss_start" will start the updated
      JBoss version with an extra associated terminal window. After JBoss has
      started up successfully it should print out a message similar to the following one:
        08:36:05,671 INFO  [org.jboss.as] (Controller Boot Thread)
            JBoss AS 7.1.1.Final "Brontes" started in 34218ms
            - Started 93 of 148 services (55 services are passive or on-demand)
      Command "jboss_stop" will shut down JBoss and close the associated terminal window.

    * Desktop and start menu icons:
      Will still work like before

    * Eclipse Indigo with configured JBoss (JBoss Tools plugin) and Maven (m2ecipse plugin)
      integration:

      Start Eclipse again using the Eclipse start icon titled
      "RapidEnv Example JEE Eclipse main". The splash screen should now idicate "INDIGO"
      (the name of the Eclipse 3.7.x release) instead of "HELIOS" before.

      Once you've started Eclipse the first time you should see:

      - again the pop up dialog asking for confimation for data transfer JBoss Tools specific
        data to the JBoss Tools development team (answer what fits you best)

      - aince source files and settigs files have been modified you should refresh
        the jeesandboxexample project.

      - automatic build actions going on in Eclipses Progress view:
        Since the "index" file .index/nexus-maven-repository-index.gz is stored
        in you local Maven repository its already there and has not to be built up
        again. So expect the build actions to come to an end much quicker.
        Nevertheless I'd again recommend to let all build actions finish
        before continuing (should take longer than 3 Minutes). If all has been built
        correctly our JEE example web application should be alread built and
        deployed / published and ready for take off.
    
      - specific Eclipse tool bar icons added by the JBoss Tools plugin:
        Using icon "Start JBoss 7.0 Runtime Server" you can start JBoss while
        the server process will write its output into the Eclipse Console view.

    * in order to run the example from Eclipse it should be enough to
      - start JBoss from Eclipse's toolbar (wait for the well known "started" message)
      - start the web application in the browser of your choice:
        http://localhost:8080/jeesandboxexample

    If the jeesandboxeample UI appears you have also run the second use case
    successfully. Especially the faster startup and shutdown behaviour of
    JBoss 7 (Brontes) is impressing compared to JBoss 6 (Neo).

    Small troubleshooting:

    - during your first tries to start Brontes from Eclipse the start may fail
      with the following error message
        'Starting JBoss 7.0 Runtime Server' has encountered a problem.
        Server JBoss 7.0 Runtime Server failed to start.

    - another effect I've already observed from time to time weas some interpretation
      problem of setting file org.eclipse.wst.common.project.facet.core.prefs.xml

    In both cases I'd recommend to do the following:

    - assure that you have refreshed the project. In case of doubt refresh it again.

    - rebiuld the project by cleaning it in Eclipse

    - restart Eclipse

    - a third problem that might happen altough the project has been built properly
      might be that the jeesandbox app does not start up. Try a full publish from the
      Eclipse "Server" view in this case.


  3) Teardown
     Removal of the complete development environment
     -----------------------------------------------

  - Open development environment specific Windows command prompt
    or Unix terminal window using
    - Windows Explorer context menu entry
      "RapidEnvJavaEE Command Prompt main"
    - Linux KDE Dolphin "Actions" menu entry
      "Open Terminal RapidEnvJavaEE main"
    - Linux Gnome Nautilus "Scripts" menu entry
      "Open Terminal RapidEnvJavaEE main"

  - start RapidEnv by entering command:
    - Windows> renv deinstall
    - Linux>   . renv deinstall
    Answer the confirmation query with "y".

  - remove folder RapidEnvExampleJavaEE from the
    file system.

  - watch the results:

    * your development environment has completely been
      wiped out without any trace left including
      file manager pop up menu entry, desktop and
      start menu entries as well as desktop icons.


License issues:
---------------

RapidEnv 1.3.0 itself is released under
  GNU Lesser General Public License, Version 3

It contains Ant 1.8.2 which is released under
  Apache License, Version 2.0

Licenses of development environment installation units set up and
maintained by RapidEnv:

- jdk
  Java SE Development Kit (incuding Java Runtime Environment)
  Version: 1.6.0_30 (1.7.0_3)
  License: Oracle Binary Code License Agreement for Java SE and JavaFX Technologies
           http://www.oracle.com/technetwork/java/javase/downloads/java-se-archive-license-1382604.html

- maven
  Maven build system
  Version: 3.0.3 (3.0.4)
  License: Apache Software License 2.0
           http://www.apache.org/licenses/LICENSE-2.0

- jboss
  JBoss Application Server
  Version: 6.0.0.Final "Neo" (7.1.1.Final "Brontes")
  License: GNU Lesser General Public License 2.1
           http://www.gnu.de/documents/lgpl-2.1.de.html
           and others (see *)

- eclipse
  Eclipse Helios (Indigo) IDE for Java EE developers SR2 (SR1)
  Version: 3.6.2 (3.7.2)
  License: Eclipse Public License Version 1.0
           http://www.eclipse.org/legal/epl-v10.html
           and others (see **)
  ...

  - plugin jbosstools 3.2.0.GA.aggregate-Update-2011-02-16_18-30-44-H329
    License: GNU Lesser General Public License 2.1
           http://www.gnu.de/documents/lgpl-2.1.de.html
    License: Eclipse Public License Version 1.0
           http://www.eclipse.org/legal/epl-v10.html
    ...

  - plugin m2eclipse 0.12.1.20110112-1712
    License: ???

PLEASE READ AND ACCEPT ALL LICENSE TERMS AND CONDITIONS PRIOR TO DOWNLOADING,
INSTALLING AND USING THE SOFTWARE.

* JBoss itself uses a lot of components with their own licenses
  including but not limited to:
  - Antlr License
  - ASL, Version 1.1
  - ASL, Version 2.0
  - ASM License
  - Apache License, Versions 1.0 and 2.0
  - BSD (style) License
  - Bouncy Castle Licence
  - Common Development And Distribution License (CDDL), Version 1.0
  - Common Public License, Version 1.0
  - Creative Commons Attribution License, Version 2.5
  - Dom4j License
  - GNU Lesser General Public License (LGPL), Version 2.1
  - GNU General Public License (GPL), Version 3
  - GPLv2+CE
  - Jaxen License
  - JDOM Licnesem, Version 1.0
  - MIT License
  - MPL 1.1
  - Oswego License
  - Tanuki Software license
  Please refer to $JBOSS_HOME/docs/licenses/licenses.xml for a
  comprehensive overview.

** According to the "Eclipse Foundation Software User Agreement"
(see http://www.eclipse.org/legal/epl/notice.php)
IT IS YOUR OBLIGATION TO READ AND ACCEPT ALL LICENSE TERMS AND CONDITIONS
OF ECLIPSE FEAURES AND PLUGINS THAT COME WITH ECLIPSE PRIOR TO USE OF THE
CONTENT.
If no About, Feature License, or Feature Update License is provided,
please contact the Eclipse Foundation to determine what terms and conditions
govern that particular Content.