Quick Install Guide

In this installation guide, you will learn how to:

  • Download an all-embracing zip file from the NSX website.

  • Extract all NS infrastructure parts and all NS source repositories.

  • Understand the different subdirectories in the extracted folder NSF-3.0.1.

  • Start a sample Normalized Systems test application.

  • Start the NS expansion of a test application.

  • Build, deploy and start an expanded test application.

  • NS Expansion supporting another database type.

  • Perform an initial database population.

  • Update the NS source repositories to a specific release tag.

Download NSF-3.0.1.zip from www.normalizedsystems.org

Download the all-embracing zip file NSF-3.0.1.zip from the NSX website at http://www.normalizedsystems.org.

This zip file can be used to make a full NSF (Normalized Systems Framework) installation on Windows and Linux platforms. The zip file also contains the JVM (jdk1.7) for both OS’s. By default this tutorial uses Windows bat scripts in ‘Command Prompt’ shells to explain the different installation, configuration and execution steps.

Extract the file NSF-3.0.1.zip

Extract the file NSF-3.0.1.zip to whatever location on your computer (but avoid spaces in the folder pathname!). You will find an extracted folder ‘NSF-3.0.1’ that contains the following subdirectories:

  • infrastructure

  • repositories

  • workspace

In the folder ‘NSF-3.0.1’ you will find a script ‘set_all_env_vars.bat’. This bat script needs to be executed in order to set all NSF environment variables in the current Command Prompt session. The script will launch other scripts in the subdirectories infrastructure, repositories and workspace, in order to add all needed ‘env vars’ and it will add all ‘bin’ folders to the ‘%Path%’ variable.

1. The folder ‘infrastructure contains all the different open source components that are used in the current ‘NSF technology stack’:

  • jdk1.7.0_51

  • apache-ant-1.9.4

  • apache-maven-3.0.5

  • jonas-full-5.2.4 (Java Open Application Server)

  • dependencies (javaee-api-5, struts2 2.3.15, …)

  • apache-tomee-plus-1.6.0.2

Folder dependencies contains various jar files, e.g. javaee-api-5.jar, the jar file of the Java Platform, Enterprise Edition, v5.0 API and several Struts2 jars.

JOnAS is an open-source implementation of the Java EE application server specification, developed and hosted by the ObjectWeb consortium.

From NS version 2.2 it is also possible to deploy an expanded application on another open source application server: Apache TomEE, in folder apache-tomee-plus-1.6.0.2.

2. The folder ‘repositories’ contains all the different subprojects of the Normalized Systems expanders:

  • baseComponents

  • expanders (to be fetched explicitly from Bitbucket)

  • nsfInstaller

  • nsx-libraries

  • nsx-runtime

  • testApplications

  • webStyles

These subdirectories are actually Mercurial clones taken from different projects that are hosted at bitbucket.org by a ‘normalizedsystems’ academic account (e.g. project ‘expanders’: https://bitbucket.org/normalizedsystems/net.democritus.expanders).

Projects ‘nsx-libraries’ and ‘nsx-runtime’ contain supporting source code for basic compile-time and run-time functionality as utility classes for Struts2, EJB, JPA and logging operations.

  • nsx-libraries’ contains 3 smaller maven2 projects: nsx-common (some basic utility classes), nsx-logging (slf4j-based delegation logger) and nsx-metadata (classes to hold the metadata of all NS elements).

  • nsx-runtime’ also has 5 smaller maven2 projects: nsx-shared-common (basic runtime classes), nsx-shared-ejb3 (some EJB based helper classes), nsx-presentation-struts2 (Struts2 utility classes), nsx-shared-jpa (JPA utils) and nsx-shared-yaml (YAML data serialization support).

  • Project ‘baseComponents’ contains the elements and the customized code for basic functionality as utility classes to support Struts2, EJB and JPA, user and profile information, validation, workflow, notification (email).

  • In project ‘expanders’ the actual Normalized Systems expanders source code is kept, together with a whole set of unit tests. The repository ‘expanders’ can be cloned from the repository of the Bitbucket ‘normalizedsystems’ academic account (by users that have been given ‘read-access’ by the Bitbucket academic account administrator).

  • Project ‘nsfInstaller’ contains 3 subdirectories: in ‘nsfInstaller\expanders’ is a ‘bin’ folder containing the scripts to launch the different java based expanders, and a ‘lib’ folder to store the latest version of the expanders jar files (including a jar file including all expander dependencies). ‘nsfInstaller\install’ contains some scripts to automatically clone the Bitbucket projects starting from a properties file containing the tags of the latest stable versions.

  • Project ‘testApplications’ contains the elements and the scripts to expand a number of test applications (e.g. an EU Rental tutorial application). The scripts in the applications folder are a good starting point to understand the way a Normalized Systems application is generated.

  • In project ‘webStyles’ you will find some common image files, css files and Struts2 jsp files, together with a number of OEM specific layout files (e.g. for style ‘nsxbootstrap’).

    Additionally, folder ‘repositories’ became a parent Mercurial repository for all underlying repositories (the repository is called ‘nsfRepositories’ in the Bitbucket academic account).

    3. The folder ‘workspace’ is used to contain the different ‘descriptors’ for new NS projects, and all generated applications and components.

    In ‘descriptors\applications’ the user will put his application descriptors, while in ‘descriptors\components’ the descriptors of the new components will be stored.

Also folder ‘expansions’ has the same structure, with a subfolder ‘applications’ and a subfolder ‘components’; in these folders the expanded source code will be generated.

Start the NS sample application

Open a ‘Command Prompt’ and navigate (‘cd’) to the main extracted folder ‘NSF‘-3.0.1. Run the bat script ‘set_all_env_vars.bat’. This script will call sub-scripts in the folders infrastructure, repositories and workspace to set all the environment variables needed for the (JOnAS) application server and the NS expanders.

Then ‘cd’ to NSF-3.0.1\infrastructure\jonas-full-5.2.4\BASE\apps; copy the ear of the NS sample application to the hot-deploy folder, and start the JOnAS application server:

copy euRentApp.ear ..\deploy

jonasStart.bat

[remark:]{.underline} the JOnAS start script dumps all logging to a log-file ‘jonas-console.log’ in the following way:

jonas start -Dhsqldb.reconfig_logging=false > jonas-console.log 2>&1

You can monitor the startup of the sample application in ‘jonas-console.log’ (e.g. using mTail).

[Remark]{.underline}: Ignore the following Exception (actually a warning) in the log file:

HsqlDBServiceImpl.__doStar : Error while creating/adding user

java.sql.SQLException: statement does not generate a result set

Now you can point a browser to the URL ‘http://localhost:9000/euRentApp/login’ and login with the {user, pwd} combination {admin, testAdmin}.

To stop the sample application:

jonas stop

Now you can clear all cashes of the JOnAS application server; this is needed in between different runs in case HSQLDB is used as the underlying RDBMS (to avoid ‘socket creation errors’ when starting the JDBC ConnectionManager) :

jonasCleanup.bat

[Remark]{.underline}: Do not remove NSF-3.0.1\infrastructure\jonas-full-5.2.4\BASE\work\hsqldb, because this folder contains the HSQL database.

Expand the NS sample application

Open a ‘Command Prompt’ and ‘cd’ to the main extracted folder ‘NSF-3.0.1’. Run the bat script ‘set_all_env_vars.bat’.

Navigate to folder ‘NSF-3.0.1\ workspace\descriptors\applications\euRent’. You can start the ‘euRentApp’ expansion process by running the generic build_application bat script.

After running ‘set_exp_env_vars.bat’, the script build_application.bat is available in your %Path% environment variable.

Also your application descriptor will be available by the expansion script in %APPLICATION_PATH% and your component descriptors will be located in %COMPONENT_PATH%:

build_application.bat euRentApp > build_application_euRentApp.log 2>&1

You can follow the correct working of the expansion process in the log-file build_application_euRentApp.log.

Build & run the expanded sample application

Open a ‘Command Prompt’ and navigate (‘cd’) to the main extracted folder ‘NSF-3.0.1’. Now run the bat script ‘set_all_env_vars.bat’.

[Remark:]{.underline} when using maven for the first time as the build engine for your expanded application, you will need to run the script prepare_maven_repository.bat in folder ‘NSF-3.0.1\repositories’. This script will install all NS (expander) jar artifacts inside your personal ‘.m2’ maven repository. (As an alternative, the build engine, ant can be used. This reconfiguration is explained in the NS Expanders 3.0 Developers Guide).

Then navigate to folder ‘NSF-3.0.1\workspace\expansions\euRentApp’ and run the maven script to build the sample application ‘euRentApp’:

**mvn package **

This script will perform the maven build process for the different components of which the application is composed, and finally it will build the applications ‘enterprise archive’ (euRentApp.ear).

If everything goes well, the ‘ear’ file will be available in the folder ‘NSF-3.0.1\workspace\expansions\euRentApp\ear\target’. Copy this euRentApp.ear file into the ‘apps’ folder of the JOnAS application server: ‘NSF-3.0.1\infrastructure\jonas-full-5.2.4\BASE\apps’.

Now you can start the newly built sample application ‘euRentApp’ by following the same steps as explained before in section ‘Starting the NS sample application’ (copy the ear to the deploy folder and start JOnAS).

Expand your own NS application

Open a ‘Command Prompt’ and ‘cd’ to the main extracted folder ‘NSF-3.0.1’. Run the bat script ‘set_all_env_vars.bat’.

Navigate to subfolder ‘NSF-3.0.1\ workspace\descriptors’ and place the application descriptor file for your new application, e.g. ownApp.ad’, in the folder applications\ownApp.

The same needs to be done for the components of your new application: place the descriptor files in the subfolder ‘dd’ of the folder components\ownComp.

Then start the expansion using build_application..bat:

build_application.bat ownApp > build_application_ownApp.log 2>&1

Now you can start adding element descriptors to your component(s) and extend your application with custom extensions and custom harvests. These steps are further explained in the NS Expanders 3.0 Developers Guide.

[Remark:]{.underline} you can also harvest (keep your customizations) and inject (redo your customizations) from the command line. It is also possible to ‘only expand’ without implicit injection. Here an overview of all possible commands and their meaning:

harvest_component.bat testApp testComp

= harvest the customizations of component testComp (for application testApp)

expand_component.bat testApp testComp

= expand component testComp (for application testApp)

inject_component.bat testApp testComp

= inject harvested customizations into the expanded code of testComp (for testApp)

build_component.bat testApp testComp

= expand component testComp and inject all harvested customizations (for testApp)

harvest_application.bat testApp

= harvest the customizations for testApp (this does not harvest the components)

build_application.bat testApp

= expand testApp including components and inject all harvested customizations

Expand using another database type

In order to work with another RDBMS at the persistence layer of the JOnAS application server, one needs to make two configuration changes, one at the expansion level and one at deployment time.

To choose another ‘database target’ during the expansion of an application {appName}, the environment variable %TARGET_DATABASE% needs to be changed in the script set_exp_env_vars.bat, located in ‘NSF-3.0.1\workspace\descriptors\applications\{appName}.

E.g. in order to expand for PostgreSQL, first ‘comment out’ (‘rem’ or ‘::’) the line containing HSQLDB and enable the line with POSTGRESQL:

:: set TARGET_DATABASE=HSQLDB

:: set TARGET_DATABASE=SQL_SERVER

set TARGET_DATABASE=POSTGRESQL

:: set TARGET_DATABASE=ORACLE

Before starting JOnAS with the newly deployed ‘{appName}.ear’ in the hot-deploy folder, we need to reconfigure JOnAS to make use of some PostgreSQL properties files.

This configuration is done in the following configuration file: NSF-3.0.1\infrastructure\jonas-full-5.2.4\BASE\deploy\ jdbc-ds.xml.

There is a separate xml section for each application component, except for the base components ‘utils’, ‘validation’, ‘account’ and ‘workflow’, which are configured in a single xml section (the one containing datasource-configuration with name ‘jdbc_appName_base’).

Finally, in your RDBMS, you also need to create the database(s) configured in your jdbc-ds.xml properties files, before starting the JOnAS application server.

All ‘underlying’ database tables will be created automatically. This is performed through the Hibernate (or OpenJPA) persistency provider, as the expanded persistence.xml files contain the following line:

<property name="hibernate.hbm2ddl.auto" value="update"/>

If the expanded application contains data elements that are configured using the options ‘optionDataBaseSchema’ or ‘optionDataSchemaName’, then you will need to create (manually) these database schemas in the RDBMS before starting the application server.

In case the option is ‘optionDataBaseSchema’, the name of the schema needs to be equal to the name of the component of the data element(s).

Initial database population

You can find an example of an initial database population script in NSF-3.0.1\repositories\testApplications\applications\testApp\populate.

The script populate_all.bat is a script orchestrating the basic population scripts for the components utils, account and workflow, and the picklist and menu screen population scripts for the elements of the test components basisComp and testComp.

Before running this full population script, make sure you start from an empty database with the same name as configured in your properties files (e.g. ‘db_jonas’). To do so, you can make a backup of database db_jonas and drop / re-create it; or you can run a script to drop all the existing database tables.