Instructions - How to Start with Development

The application and it's build process is OK with GNU/Linux, Microsoft Windows and other operating systems.

Setting up Java Development Kit (JDK)

The application is coded in the Java programming language, so you will need the tools that are part of a recent JDK. The recommended IDE is Eclipse, which also uses Java. If you want you can run Eclipse in one version of Java, and compile and run the application with another version of Java, but it is not necessary.

Installation

The application has been tested with:

• Open JDK 7
• Oracle JDK 8 (​http://www.oracle.com/technetwork/java/javase/downloads/index.html).

We recommend going the 8 route due to planned upgrades of the code base in the near future. So, download the JDK version that you prefer and install it.

NOTE: Check if you already have some other Java or JDK versions. If you use built-in packages and package managers in some operating systems, the JDK version might be old, and if you try to install a new version alongside an old one, you might get a conflict when using the default installation options. If you don't need both versions, uninstall the old one before installing the new one. If you do need both version, install the new one in a different path. It is possible to switch between the two afterwards.

Configuring in Windows

• Set up system variable JAVA_HOME to the absolute path to the main directory where you installed the JDK
• Set up system variable PATH to the absolute path of the bin directory inside the JDK or %JAVA_HOME%\bin
• For 64-bit operating systems, both 64-bit and 32-bit JDK versions should be installed

• Check installation in command shell

  javac -version
  

you should get the version of the installed java compiler

---

Download and setup Eclipse IDE

• Download Eclipse (there are many versions - you can use the Eclipse IDE for Java Developers as a basic installation, but Eclipse IDE or Java EE Developers is the recommended choice because the packages for Web Development (WTP) are preinstalled.
• Best way is to download a ZIP or TGZ version and just unpack it in the folder of your choice

Before running Eclipse

Make sure that Eclipse uses the JDK version that you installed for this, and not some other one.

The instructions are given here: ​http://wiki.eclipse.org/Eclipse.ini

NOTE: If you have problem in the future with the memory for recompilation being full too often it might be beneficial to increase some of the default values in this file (PermGen). Check the instructions at the bottom.

Then you can start Eclipse IDE

Install the Maven and Subversion support in Eclipse

The application is built using Maven, so you need the maven integrated in the Eclipse IDE. In all late versions of Eclipse, Maven integration is built-in. For older version of Eclipse you would have to install the m2eclipse plugin from the following update address - ​http://m2eclipse.sonatype.org/sites/m2e (In Eclipse → Help → Install New Software , you will add the address and available packages will showup, please add everything becides AJDT and WTP that depend on other plugins)

The application source is managed in a central subversion repository, so you need a SVN integration in Eclipse to access this repository and commit new versions of the code. You can find such integration plugins in the Eclipse Marketplace. There are two main such plugins and we have used them both in the past:

• Subversive team provider (recommended)
• Subclipse

If you use Subversive, after the installation and restart of Eclipse it will ask to download and install a SVN connector, there are two options:

• SVN Kit based that are pure Java and work everywhere - recommended - choose the latest version
• JavaHL which are compiled with native code for the operating system and can run faster in some occasions/

Download the project source code and setup a project

Setup the subversion repository location, get the source, prepare maven and subversion

Change the Eclipse IDE perspective to the SVN Repository.

Create a new SVN Repository location, pointing to ​https://develop.finki.ukim.mk/svn/isis

You will then be able to view the contents of the repository.

The main and latest source code is in the folder "trunk".

Right click on trunk and choose "Checkout". This means that you will get a version of the source code out of the repository for you to work on. It will be automatically downloaded and setup as a new project with the name "isis".

If you create modifications to the source code in this project, you will be able to check them in with the subversion Commit command.

Switch back to the Java perspective.

Right click on the project and activate the Maven - Convert to Maven project option, if not already active.

Maven should start automatically to download all necessary files needed to compile and run the application. The dependencies and all options regarding this are configured in the start maven configuration file "pom.xml". This is a large download with many files and it might actually take very very long depending on the internet connection speed.

If all went OK, there will be a small M icon (stands for Maven) besides the isis project title, small J icon (stands for Java) and you will see the repository location for the project besides the title and latest modification version for all files in the project, beside the name of the file.

Setting up which JDK or JRE to use to run the project

• In Eclipse open Window → Preferences → Java → Installed JREs

If this is not the one you installed for our purpose, delete that one or add new one that points to the JDK that you installed (and not JRE) similar to the image below

Building the project

Before running or building the project, several local parameters should be set depeding how to run the project, the paths, which database to use, etc.

This is done via a standard way of maven profiles, so you should open/create a file named settings.xml in the .m2 directory in your user profile directory. If you don't know where this is - check Eclipse preferences - maven - user settings.

Sample maven settings.xml file:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">
    <localRepository />
    <interactiveMode />
    <usePluginRegistry />
    <offline />
    <pluginGroups />
    <servers />
    <mirrors />
    <proxies />
    <profiles>
        <profile>
            <id>develop</id>
            <activation>
                <property>
                    <name>env</name>
                    <value>develop</value>
                </property>
            </activation>
            <properties>
		<jdbc.url>???????</jdbc.url>
		<jdbc.default_schema>????????</jdbc.default_schema>
		<jdbc.username>??????????</jdbc.username>
		<jdbc.password>??????????</jdbc.password>
		<hib.hbm2ddlauto>??????????</hib.hbm2ddlauto>
		<cas.server>??????????</cas.server>
		<app.server>??????????</app.server>
		<ldap.addomain>??????????</ldap.addomain>
		<ldap.baseUserDN>??????????</ldap.baseUserDN>
		<ldap.bindPassword>??????????</ldap.bindPassword>
		<ldap.bindUserDN>??????????</ldap.bindUserDN>
		<ldap.protocol>??????????</ldap.protocol>
		<ldap.url>??????????</ldap.url>
            </properties>
        </profile>
    </profiles>
    <activeProfiles />
</settings>

You can create several profiles in this file, with different id and activation parameters, so that you can use choose the one you want on running the application, or packaging for deployment.

Contact the developer team for parameter values for the development test servers and example content of this file.

Otherwise, if you are not part of the official developer team - you can do it yourself, but harder. Install PostgreSQL, setup a username, password and create a new empty UTF-8 database, and set the hbm2ddlauto parameter to update, and the database schema structure will be automatically created. WARNING: if you create the database yourself, you will need some seed data in some tables to be able to use the application. Check ModelConstants.java for some of the special codes of entities that you will need to have and cope with this

When hbm2ddlauto=update is used, it enables updates to the database schema structure when the Java source code of the Entities changes, otherwise the default value of this parameter is validate.

More precisely this parameter designates that the database will be scanned and if the source code has structural changes, such changes will be automatically implemented in the database schema. This should be only used by intent and it should not be left as default as unwanted changes could be commited to the database by mistake without a warning.

So set this to UPDATE only when you are about to make database structure changes and then change it back to VALIDATE, which only checks that the source and the schema correspond.

If you use another database system, then hibernate.dialect should be changed, but this is not tested.

CAS (CENTRAL AUTHENTICATION SERVICE)

The application uses CAS for login authentication, so you need to set up a test service.

If you already have a CAS server, change the paths in the settings.xml file. If you need a test CAS server, follow the procedure.

• Download any of the 3.4.x CAS versions from ​http://downloads.jasig.org/cas/ and unpack it.
• Find the included file named CAS-server-webapp-someversionnumber.war and copy it to the main folder of the isis project and rename it to cas.war

This will enable a test login to the system, whereas the username is anything you need, and the password is the same as the username.

Create a Run Configuration in Eclipse

Run → Run Configurations , then in the maven section right click then New, use any Name you like (for example start isis), Base Directory → ${workspace_loc:/isis} , Goals → clean jetty:run

In the profiles put the name of the profile (the id of the profile) that you have put in .m2/settings.xml.

Usually you will have separate profiles for testing database, profile for official database, etc. This is where you choose how will the application run and where it will connect to.

Repeat this again for another configuration for stopping the app - all the same but with a Name stop isis and Goals jetty:stop

It should look like this:

Starting the application

Open the Run Configuration and click on Run and the application will begin to build.

Note that on the first run, Maven will try to download all required libraries for runtime from the Internet and setup the library paths for all dependencies. This can take a very long time if your connection is not fast. On subsequent runs, this will not happen, as Maven only checks for updates. If you want to speed up the process, after everything has been run without problems at least once, you should check the parameter Offline in the Maven parameters for that run configuration.

If everything is OK you will see this in the end:

[INFO] Started SelectChannelConnector@0.0.0.0:8081
[INFO] Started Jetty Server

This means that the appliation was built successfully and that even the web server started successfully. For testing purposes an internal Jetty web server was downloaded and automatically setup to run on port 8081. This might change in the future.

You should inspect the starting logs and find lines starting with ERROR: message. Such messages are important and should be dealt with until there are no such messages. Stop the application via the stop configuration that you have created and fix the problems. Do this until you fix all such errors before continuing. Usually errors at first run can be related to database permission issues.

When there are no ERRORS: open ​http://localhost:8081/upisi in your browser, and log in with any user you wish. As mentioned just put the username in the password again and it will be OK.

Logging

In log4j.properties in the application folder src/main/resources one should change the line

log4j.appender.R.File=/upisi.log or log4j.appender.R.File=/home/username/upisi.log

or to a location where the user that is running eclipse has write permission and where the logs should reside.

WikiStart Back