Open Immunization Software - Spring 2016
Home Interfacing Data Quality Forecasting Matching

Admin User Manual

Developer Manual

Developer Guide

Setup Instructions for DQA Development

DQA is easiest to develop in Eclipse. But this is not required. Here are the instructions to the standard setup:

  1. Get Source Forge account
    The source code is stored in Source Forge. You should register an account and then send an email to Nathan Bunker with your new Source Forge id to request to become a member of the project.
  2. Install Maven
    Maven is a build process that is way awesome. It does a lot of what ant does but even more. Installing is as easy as ant and makes the rest of the dev process so much better.
  3. Install Eclipse
    Development does not require Eclipse, but it's what the developers on this project are using and so you may find it easiest to use this.
  4. Install Maven Eclipse plugin
    This plugin supports functions that help with using both Maven and Eclipse. You install this from within Eclipse. Go to Help >> Install software and use the second link below to get the software.
  5. Install SVN plugin
    This supports connecting to SVN. Eclipse doesn't support SVN out of the box. Install this just like the Maven Eclipse plugin.
  6. Install Oracle jar into Maven
    All the other jars in this project are open source, but you will need to add the Oracle jar manually. If you do not plan to use Oracle then you will need to comment out the oracle dependency in the pom.xml file instead.
    • Modify the script below to indicate the location of your Oracle jar and then run:
      mvn install:install-file -Dfile={ORACLE_HOME}/jdbc/lib/ojdbc6.jar -Dpackaging=jar\ -DgroupId=com.oracle -DartifactId=oracle -Dversion=10.2.0
  7. Setup database
    • Oracle: Better scripts are coming soon, contact Nathan Bunker for now
    • MySQL: Better scripts are comming soon, contact Nathan Bunker for now
    • Hypersonic: This is ready to go and you don't need to do anything to run Hypersonic
  8. Check out DQA code
    • In Eclipse switch to SVN Repository perspective.
    • Add new SVN Repository at this URL: https://svn.code.sf.net/p/ois-dqa/code You will have to use your source forge credentials
    • The project is now organized into four areas areas. The three main ones you will want to check out are listed below:
      • /core/branches/v1_08 DQA application Core
      • /database All DQA database scripts
      • /webui/branches/v1_08 DQA stand alone web application
    • Choose "New Project Wizard"
    • On the wizard give the project a name and then finish
  9. Check out TCH Connector
    The TCH Connector allows the DQA to request Clinical Decision Support when replying back with a QBP. This functionality is optional, but the connecting jar must be built into the project.
    • Follow the instructions for checking out the DQA code in SVN.
    • URL for this repository is https://svn.code.sf.net/p/tchforecastconn/code/
    • The current version to check out is: branches/v2_12
  10. Build TCH Connector
    Build the connector by running mvn install -Dmaven.test.skip=true for this project.
  11. Include Oracle as Dependency
    If you are connecting to Oracle you will need open pom.xml in the WebService and/or WebUI project and comment in the Oracle jar dependency. This should now point to the Oracle jar that you loaded previously into your Maven repository. (Oracle is not enabled by default as this is a proprietary solution and DQA is designed to work out-of-the-box without Oracle.)
  12. Setting up each project so it compiles
    • On the command line, go to the project root folder. (Same folder the pom.xml is in.)
    • Prep the file for Eclipse by running: mvn eclipse:eclipse
    • Go back to Eclipse, right-click on project and choose refresh.
    • The project should now have no compile errors and be setup correctly.
    • If this is the WebUI or WebService project you will also want to right click on the project, click properties, and configure the build path to point to the DQA core project. This will allow Eclipse to automatically see changes you make in core.
  13. Compiling the core
    • On the command line, run mvn install -Dmaven.test.skip=true on the core. This will install the DQA core application in your local repository which will make it available to the the WebUI and/or WebService project.
  14. Setup database parameters.
    • In Eclipse go to src/main/resources and open hibernate.cfg.xml in the WebService adn/or WebUI project.
    • Eclipse may try to be cute and show you the XML doc in a special window, you can select the Source tab on the bottom and switch to source.
    • By default the file is configured to work with HSQL. Change this to your preferred database by copying the lines of code from either the hibernate.cfg.oracle.xml or hibernate.cfg.mysql.xml file. As you will see these files are only a snippet of the full file so be sure to copy and replace carefully.
    • Change the connection parameters so the url/username/password is correct. For Hypersonic there is no need to make this change.
  15. Make sure database is running
  16. Running the project
    • To run, go into Test folder and find the Start java file.
    • Right click on Start and Run As >> Java Application.
    • Now the application will start in Jetty and the output will show in the Console inside Eclipse
    • Remember to stop it using the red stop button if you want to stop and restart it
  17. Building the project
    • On the command line, in the project root folder for either WebUI and/or WebService. (Same folder the pom.xml is in.) run this command: mvn install -Dmaven.test.skip=true
    • Maven will first compile, then run the JUnit tests (database has to be runing so unit tests will work), and then buld the war.
    • The war file is in the target directory and is named with the current version.
    • You will probably want to rename the war file to simply dqa.war
  18. Running
    The application can be run during develop easily using Jetty.
    • In Eclipse navigate to src/test/org/openimmunizationsoftare/dqa/Start.java.
    • Right click on Start.java, select Run As >> Java Application.
    • Jetty will start project in Eclipse environment and listen on port 8281. Navigate to http://localhost:8281/config.
    • Jetty can be stopped by pressing STOP button in Jetty console window in Eclipse. Remember that in this way Jetty shares the JVM of Eclipse. DQA can't process extremely large DQA files in this environment. Test this functionality using Tomcat.
  19. Deploy
    • Both WebUI and/or WebService project can be deployed on Tomcat, Glassfish, our it may work on your favorite J2EE app server. Try it!