This is QueWeb 3.0 Core project's subversion trunk directory.


Prerequisites
~~~~~~~~~~~~~
Install the following software on Linux or Windows:
- Subversion command line client
    Linux: it is included in your installed distribution.
    Windows: http://subversion.tigris.org/files/documents/15/34093/svn-1.4.0-setup.exe
- JDK 6
    http://java.sun.com/javase/downloads/index.jsp
    Queplix team shared drive: \project\Queplix\Distribs\Java\j2se-6_0
- GWT 1.3.1
    Linux and Windows: http://code.google.com/webtoolkit/download.html
    Queplix team shared drive: \project\Queplix\Distribs\GWT
            gwt-linux-1.3.1.tar.gz
            gwt-windows-1.3.1.zip
- JBoss 4.0.4
    IMPORTANT: Install it in "All" configuration
    Linux and Windows: http://prdownloads.sourceforge.net/jboss/jboss-4.0.4.GA-Patch1-installer.jar?download
    Queplix team shared drive: \project\queplix\Distribs\JBoss\jboss-4.0.4.GA-Patch1-installer.jar
- NetBeans 5.5 (Optional)
    Linux and Windows: http://www.netbeans.org/downloads/index.html
    Queplix team shared drive: \project\queplix\Distribs\NetBeans
            netbeans-5_5-linux.bin
            netbeans-5_5-windows.exe
- NetBeans 5.5 Profiler (Optional)
    Linux and Windows: http://www.netbeans.org/downloads/index.html
    Queplix team shared drive: \project\queplix\Distribs\NetBeans
            netbeans-profiler-5_5-linux.bin
            netbeans-profiler-5_5-win.exe
- MS SQL 2000 SP3
    Windows only:
        Queplix team shared driver: 
            SQL: \\merlin\Distrib\Windows\Apps\Network\SQLServer_2000_Professional_Edition
            SP3: \\merlin\Distrib\Windows\Apps\Network\SQLServer_2000_Enterprise_Edition\Updates\sql2ksp3
- Far Manager 1.70
    Windows only: http://farmanager.com/files/FarManager170.exe


Source Code Setup
~~~~~~~~~~~~~~~~~
- Go to a directory in your local file system where you will place project source code
- Run the following command: 
    svn checkout https://svn.queplix.com/svn svnroot
- Use provided login and password
- If prompted accept the certificate permanently
- A directory named svnroot will be created; it is the root of all source code of
    this project.
- Go to the directory where this readme.txt file is located (possibly, svnroot/core/3.0u/trunk);
    all paths below will be denoted relatively to that directory.


Build Environment Setup
~~~~~~~~~~~~~~~~~~~~~~~
- Go to the directory where this readme.txt file is located and run "nb-create" ant target:
    ant nb-create
    (Note that if ant is not on your executables path, you can find it in NetBeans installation directory
    under ide7/ant/bin subdirectory)
- After that you have two options to proceed further. First option is using NetBeans 5.5 for development. 
    In this case all environment related settings are done from within NetBeans. Another option is using 
    any other IDE and in this case ant task is used to configure the build environment

Option 1. NetBeans Project Setup
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Start NetBeans if it is not running
- Go to main menu/Tools/Library Manager/New Library, name it "QWCore" (case sensitive) and add all jars 
    from the following directory to it:
    qwcore/lib
- Add another libary named "JBoss" (case sensitive) and add all jars from the following directories
    of JBoss installation directory to it:
    lib
    client
    server/default/lib
- Add/update GWT library
    - click Tools/Library Manager and remove GWT library (if it is already there) and click OK 
        (note this step should be performed exactly as it is advised here)
    - click Tools/Library Manager and add library named GWT
    - click Add JAR/Folder and add one jar from the GWT installation directory:
        gwt-user.jar
    - switch to Sources tab and add the following jars there:
        gwt-user.jar
        gwt-dev-*.jar
    - switch to Javadoc tab and add doc/javadoc directory from the GWT installation directory
    - click OK
- Go to main menu/Tools/Server Manager/Add Server, select JBoss Application Server 4 in the drop down
    and proceed with its setup
- Open the following projects in NetBeans:
    qwapp
    qwapp/qwapp-ejb
    qwapp/qwapp-gwt
    qwapp/qwapp-war
    qwcore/qwcore-ejb
    qwcore/qwcore-gwt
    qwcore/qwcore-war
- When warned, resolve dependences of those projects to each other
- Resolve GWT jars dependencies
    - if some project has unresolved reference to gwt-dev-linux.jar, then navigate to GWT installation
        directory and select either gwt-dev-linux.jar or gwt-dev-windows.jar depending on your OS
    - resolve references to other GWT jars if there are any (for ex., gwt-servlet.jar)
- Right click on qwapp-gwt project and "Set Main Project"

Option 2. Environment Setup Using Ant Task
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Rename <application code>/build.properties.example to <application code>/build.properties
- Modify <application code>/build.properties file to set the following properties:
        qwcore.dir
        app.name
        gwt.home
        jboss.home
        your.os
- Run "ant set-env" command from the application folder, e.g. qwapp
- After that you can run any IDE you like, modify the code and buld/deploy the application using ant targets 
    from command line, e.g. ant run. See "Running Application" section below for more details.

Database Setup
~~~~~~~~~~~~~~
- Follow the instructions in "Database Setup" section of
    qwapp/readme.txt


Configuring Settings
~~~~~~~~~~~~~~~~~~~~
- Modify qwapp/qwapp-war/setup/jboss-ds.xml file and specify database connection parameters.
- Enable debugging for JBoss:
    - go to JBOSS_HOME/bin directory
    - modify run.sh (for Linux) or run.bat (for Windows)
    - add the following line as the first command in the file:
        for Linux:
            export "JAVA_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=n"
        for Windows:
            set JAVA_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=n

            
Running Application
~~~~~~~~~~~~~~~~~~~
To run the application from command line with Ant, the section NetBeans Projects Setup above should be
performed once to create your local system specific property files. Ant version 1.6.5 or newer is required
(it can be found in ide7/ant directory of NetBeans 5.5).
Normally to run the application you need to deploy the server application and run the client application
(see sections 1 and 3 below).
1. Deploying the server application
    With NetBeans:
        Right click "qwapp" project and "Deploy Project"
    With Ant:
        cd qwapp
        ant run
2. Debugging the server application (make sure you performed Configuring Settings section above)
    Run JBoss with deployed application and
    With NetBeans:
        Click Run/Attach Debugger menu item and connect to localhost, port 8787
        Or
        Right click "qwapp" project and "Debug Project"
    With any other Java IDE/Debugger:
        Attach the debugger to localhost, port 8787
3. Running the client application (no compilation to JavaScript performed)
    With NetBeans:
        Right click "qwapp-gwt" project and "Run Project"; or if the project is set as main, just press F6
    With Ant:
        [TODO]
4. Debugging the client application
    With NetBeans:
        Right click "qwapp-gwt" project and "Debug Project"; or if the project is set as main, just press F5
    With Ant:
        [TODO]
5. Building the client application (GWT compilation to HTML and JavaScript; the output will go to 
    qwapp-gwt/build/www directory)
    With NetBeans:
        Right click "qwapp-gwt" project and "Build Project"; or if the project is set as main, just press F11
    With Ant:
        [TODO]


Configuring Application
~~~~~~~~~~~~~~~~~~~~~~~
- Navigate to http://localhost:8080/qwapp-war/tools
    Note that:
        - It's "tools", not "tools.jsp"
        - If you get error "Cannot retrive metadata", then restart JBoss and try again
- Run Installation Tool with absolute paths to the following directories (in order) separated with 
  ":" on Linux or ";" on Windows:
      qwcore/misc/xmlmeta
      qwapp/misc/demo/xmlmeta
  For example:
      /home/sultan/my/svnroot/core/3.0u/trunk/qwcore/misc/xmlmeta:/home/sultan/my/svnroot/core/3.0u/trunk/qwapp/misc/demo/xmlmeta

      
Accessing Application
~~~~~~~~~~~~~~~~~~~~~
- Run the client application (see entry 3 in Running Application section above)
- Enter "admin" and click the button
- Application's main screen will be displayed.


Updating Application
~~~~~~~~~~~~~~~~~~~~
- Run the following ant target:
        ant update
    It will:
        - update the application source code from subversion repository
        - apply database changes if there are any
        - run installation tools if there are any xml meta changes


Developing Application
~~~~~~~~~~~~~~~~~~~~~~
See doc/guidelines.txt in qwcore directory.


Upgrading Software
~~~~~~~~~~~~~~~~~~
GWT Upgrade
-----------
Let's consider as an example GWT upgrade from 1.2.11 to 1.3.1.
- Perform "Add/update GWT library" subsection of "NetBeans Projects Setup"
    section above using GWT 1.3.1 installation directory
- Delete or rename the old GWT installation directory (of version 1.2.11). Note 
    that this step is important
- Restart NetBeans
- Perform "Resolve GWT jars dependencies" subsection of "NetBeans Projects Setup"
    section above using GWT 1.3.1 installation directory



==========================================
= How To Create a New QueWeb Application =
==========================================

- Define the name of your new QueWeb application using a short acronym in the form:
    qw[project acronym]
    For ex., if the project is for company called ACME Ltd, then the QueWeb 
    application could be called "qwal".
- Run the following target in the directory where this readme.txt file is located:
    ant app-create


=======================================================
= How To Upgrade QueWeb 2.6 to QueWeb 3.0 Application =
=======================================================

To upgrade application based on QueWeb 2.6 core to QueWeb 3.0 you need to perform all the steps, 
described in "core\3.0u\trunk\qwcore\misc\upgrade_2.6_to_3.0\readme.txt" file.
