Developers Guide

This revised guide supports version 1.3 of the Dataverse Network application. Use this guide to create a development environment in which you can view, modify, or add to the existing DVN core code. Also see the Dataverse Network Project Forum for additional information about specific platforms and versions.

Required components for the development environment are:

You can download all of the required components from the Internet.

Note: You do not need to install the DVN-DSB package from SourceForge.Net, unless you choose to work with the DVN data subsetting function. See the Installers Guide for information about installing and configuring this package.

Read the following topics for detailed information about how to install and set up a development environment:

Development Checklist

Use the following checklist to create the DVN development environment.

Note: You must have superuser (admin or root user) privileges on the installation machine. Also, all ports mentioned in this guide are defaults specified by the applicationsused, and you can substitute your own port numbers if you choose.

  1. Install the minimum environment components:
    1. Install Java SE, with JDK and JRE.
    2. Install NetBeans Web bundle, which includes GlassFish server.
    3. Install PostgreSQL and compatible administration tool.
      Then, create a new database.
    4. Refer to the SourceForge.Net wiki pages and install a compatible SVN client.
      Then, check out the DVN-EAR package.
  2. Configure the NetBeans IDE component.
  3. Configure the GlassFish server component.
  4. Build and deploy the DVN application.

To access your local DVN application, run or deploy the application from the NetBeans IDE. The default location for the deployed DVN application is http://localhost:8080/dvn.

Install Environment

Install the components of the development environment:

Install Java SE

If you are not using the minimum Java platform version in your environment, go to http://java.sun.com/javase/downloads/index.jsp and update to this version.

Install NetBeans Web Bundle

To install the NetBeans Web bundle, including the GlassFish server:

  1. Download the most recent release of NetBeans from the NetBeans Download page.
    Be sure to select the Web & Java EE bundle, which includes the GlassFish server.
  2. Install the NetBeans and GlassFish packages on your machine.
    Use the Installation Instructions provided at the NetBeans Download page.
    Note: The NetBeans Web bundle also includes the Apache Tomcat server. Do not install this server.

Install and Set Up PostgreSQL

Install PostgreSQL and the pgAdmin utility. If you encounter problems installing PostgreSQL, be sure to check the Dataverse Network Forum for platform-specific information that might help you resolve issues.

Note: The JDBC driver used with PostgreSQL is packaged with the DVN core code.

To install and set up the DBMS:

  1. Download and install PostgreSQL. Downloads for most platforms are available on the Downloads binary page.
    Specify the PostgreSQL service account and super-user account passwords as secret.
    Refer to the PostgreSQL FAQ and the PostgreSQL Installer for Windows documentation if you need assistance installing this component.
    Note: If you install to a Windows environment, be sure to install PostgreSQL as a service, which is the default. If you do not, you must start and stop the DBMS manually to use the DVN development environment.
  2. Download and install the appropriate pgAdmin tool from the Graphical Clients list on the PostgreSQL Downloads page.
    Note: If you install to a Windows environment, the pgAdmin tool in included in the PostgreSQL download.
  3. Start the PostgreSQL database server, open the pgAdmin tool, and connect to the PostgreSQL database server at http://localhost:5432.
  4. Create a New Login Role.
    Set the username to dvnApp and the password to secret. Accept all default settings.
  5. Create a new database.
    Set the database name to <your database name>, and the owner to dvnApp. Accept all default settings.
  6. Restart the server.

Install SVN Client and Check Out DVN Code

Install an SVN client:

  1. Install an SVN client compatible with the SourceForge.Net repository. Refer to the SourceForge.Net wiki pages for more information.
    NetBeans is set up to work with Subversion from within the IDE. You can locate the SVN client downloads from the NetBeans website Docs & Support menu. For example, for NetBeans IDE 6.1 refer to http://www.netbeans.org/kb/60/ide/subversion.html.
  2. Register a user account at SourceForge.net.
    You can check out the DVN Project without registering an account, but you cannot contribute to the code. If you check out the project without an account and then register, SourceForge will not accept your contributions until you check out the Project by using your account.
  3. Check out the DVN Project packages.
    In NetBeans, use the Subversion Checkout wizard and perform a checkout:

    If you choose to check out the DVN project packages from a command line, enter the following:
    svn co <https://dvn.svn.sourceforge.net/svnroot/dvn dvn
    Note: Make sure that you check out the DVN-EAR release that uses the GlassFish version which you installed with NetBeans.

Configure NetBeans

After you install the DVN development environment, configure the NetBeans IDE with project-specific settings for the DVN. Also see the GlassFish server configuration.

To configure NetBeans, open the IDE and perform the following:

  1. If you updated your Java platform, use the Java Platforms Tool and add the required <JDK version> used in the DVN-EAR project.
  2. Use the Plugins Tool to install the following from the list of Available Plugins:
    • Facelets Support
    • Facelets Library 1.1.14
  3. Set the DVN-EAR project as the main project.
  4. Configure the remaining NetBeans components. See the topics listed below.

To check that your environment is configured properly, perform a build for the main project, DVN-EAR. Resolve any errors before you continue.

Complete the following NetBeans configurations before you build the main project:

Configure the dvn-WEB Class Library

Use the Library Tool and add a new class library, dvn-WEB, with the following 16 classpaths:

  • <SVN>/lib/commons-beanutils.jar
  • <SVN>/lib/commons-codec-1.3.jar
  • <SVN>/lib/commons-collections-3.2.jar
  • <SVN>/lib/commons-digester-1.7.jar
  • <SVN>/lib/commons-el.jar
  • <SVN>/lib/commons-httpclient-3.0.1.jar
  • <SVN>/lib/commons-io-1.4.jar
  • <SVN>/lib/commons-lang-2.4.jar
  • <SVN>/lib/commons-logging-1.1.jar
  • <SVN>/lib/dvn-defaulttheme.jar
  • <SVN>/lib/dvn-webui.jar
  • <SVN>/lib/harvester2.jar
  • <SVN>/lib/log4j-1.2.12.jar
  • <SVN>/lib/oaicat.jar
  • <SVN>/lib/recaptcha4j-0.0.7.jar
  • <SVN>/lib/xalan.jar

Configure the dvn-EJB Class Library

Add a second new class library, dvn-EJB, with the following 17 classpaths:

  • <SVN>/lib/commons-codec-1.3.jar
  • <SVN>/lib/commons-httpclient-3.0.1.jar
  • <SVN>/lib/commons-io-1.4.jar
  • <SVN>/lib/commons-lang-2.4.jar
  • <SVN>/lib/datax.jar
  • <SVN>/lib/handle.jar
  • <SVN>/lib/harvester2.jar
  • <SVN>/lib/jhove-handler.jar
  • <SVN>/lib/jhove-module.jar
  • <SVN>/lib/jhove.jar
  • <SVN>/lib/license.jar
  • <SVN>/lib/log4j-1.2.12.jar
  • <SVN>/lib/lucene-core-2.3.2.jar
  • <SVN>/lib/marc4j.jar
  • <SVN>/lib/nesstar_api.jar
  • <SVN>/lib/NesstarHarvester.jar
  • <SVN>/lib/normalizer.jar
  • <SVN>/lib/oaicat.jar
  • <SVN>/lib/parser.jar
  • <SVN>/lib/REngine.jar
  • <SVN>/lib/Rserve.jar
  • <SVN>/lib/VDCNet-jaxb.jar
  • <SVN>/lib/xalan.jar

Configure the dvn-Ice Class Library

Add another new class library, dvn-Ice, with the following 13 classpaths:
  • <SVN>/lib/icefaces/backport-util-concurrent.jar
  • <SVN>/lib/icefaces/commons-beanutils.jar
  • <SVN>/lib/icefaces/commons-collections.jar
  • <SVN>/lib/icefaces/commons-digester.jar
  • <SVN>/lib/icefaces/commons-discovery.jar
  • <SVN>/lib/icefaces/commons-fileupload.jar
  • <SVN>/lib/icefaces/commons-logging.jar
  • <SVN>/lib/icefaces/el-ri.jar
  • <SVN>/lib/icefaces/icefaces.jar
  • <SVN>/lib/icefaces/icefaces-bm.jar
  • <SVN>/lib/icefaces/icefaces-comps.jar
  • <SVN>/lib/icefaces/icefaces-facelets.jar
  • <SVN>/lib/icefaces/krysalis-jCharts-1.0.0-alpha-1.jar

Configure the DVN-WEB Project

Set up the DVN-WEB project properties:

  1. Configure the Sources category as follows:

    • Source/Binary Format is JDK 5. This is a required setting, regardless of the JDK version used in your environment.
    • Encoding is UTF-8.
  2. Configure the Libraries category to use Java Platform <JDK version>.
  3. Add the following compile-time Libraries:
    • Web UI components
    • Web UI default themes
    • JSF1.1/1.2 support (Package)
    • DVN-ejb - dist/DVN-ejb.jar (Package)
    • dvn-WEB (Package)
    • dvn-Ice (Package)
  4. Add the following Build category Packaging options, and set
    WEB-INF/lib as the path in the WAR for all of them:

    • dvn-WEB
    • dvn-Ice
    • Web UI components
    • Web UI Default Themes
    • JSF1.1/1.2 support
    • Exceptionhandler-runtime

Configure the DVN-EJB Project

Set up the DVN-EJB project properties:

  1. Configure the Sources category as follows:

    • Source/Binary Format is <JDK version>.
    • Encoding is UTF-8.
  2. Configure the Libraries category to use Java Platform <JDK version>.
  3. Add the compile-time Library dvn-EJB (Package).

Configure GlassFish

After you install the DVN development environment, configure the GlassFish server. Also see the NetBeans IDE configuration.

To configure GlassFish:

  1. In your file browser, copy the following files:
    • Copy the PostgreSQL JDBC driver jar file from the
      /<SVN>/doc/PostgresDriver directory and paste it in the
      /<glassfish>/lib directory.
      An example driver is the postgresql-8.3-603.jdbc4.jar file.
    • Copy the files in the
      /<SVN>/working_directory directory and paste them in /<glassfish>/domains/domain1/config directory.
  2. Start the GlassFish server, and open the Admin Console at http://localhost:4848.
    NetBeans is set up to work with the GlassFish server. You can start the server and open the console from the Services tab of the IDE.
  3. See Configure Resources for JDBC Connections in the Installers Guide for the JDBC settings.
  4. See Configure Resources for JMS Resources in the Installers Guide for the JMS settings.
  5. See Configure Resources for JavaMail Sessions in the Installers Guide for the JavaMail settings.
  6. For the Application Server, configure the JVM Settings:
    1. Add the following JVM Options.
      Note: Be sure to include the dash in front of the option:

      • -Djhove.conf.dir=${com.sun.aas.instanceRoot}/config
      • -Ddvn.inetAddress=localhost:8080
      • -Dvdc.export.log.dir=${com.sun.aas.instanceRoot}/logs/export
      • -Dvdc.temp.file.dir=${com.sun.aas.instanceRoot}/config/files/temp
      • -Dvdc.import.log.dir=${com.sun.aas.instanceRoot}/logs/import
      • -Dvdc.study.file.dir=${com.sun.aas.instanceRoot}/config/files/studies
      • -Dvdc.dsb.host=<DSB component host URL>
      • -Ddsb.rserve.host=<R host machine domain>
      • -Ddsb.rserve.port=<R host machine port>
      • -Dvdc.dsb.rserve.user=<account>
      • -Dvdc.dsb.rserve.pwrd=<password>
      • -Dvdc.dsb.rserve.port=<port number>
      • -Dvdc.dsb.port=<DSB component host port>
      • -Ddvn.index.location=${com.sun.aas.instanceRoot}/config
      • -Ddvn.googleanalytics.key=<googleanalyticsTrackingCode> (Optional)
      • -Djava.util.logging.config.file= ${com.sun.aas.instanceRoot}/config/logging.properties (Optional)

      Notes: To customize error logging, edit the <glassfish>/config/logging.properties file and change WARNING to INFO.
      Also, see Install RServe for information about configuring the -Dvdc.dsb.rserve values in the Rserv.conf and Rserv.pwd files.

    2. Change the following options’ settings:
      • Change –client to –server.
      • Change -Xms512m to –Xms1024m.
      • Change -Xmx512m to –Xmx1024m.

        • Note: Make sure that the Xms and Xmx settings have the same value.

  7. See Set Up Configuration for EJB Container in the Installers Guide for the EJB settings.
  8. Restart GlassFish to make the configuration take effect.

Build Application

To build and deploy the DVN application:

  1. In NetBeans, perform a Clean and Build for the main project.
    Make sure that the build is successful before you continue.
  2. In NetBeans, perform a Undeploy and Deploy for the main project.
  3. After you build the application the first time, run the referencedData.sql script from the PostgreSQL pgAdmin tool to poplulate the database with default values:
    1. Start pgAdmin, and select the Query tool.
    2. Execute the file referenceData.sql in the directory /<SVN>/src/DVN-EJB/src.conf.
  4. Restart GlassFish server.
  5. In NetBeans, perform a Run Main Project to build, deploy, and run the DVN application.

By default, the DVN application deploys from the build directory. To deploy from the GlassFish directory:

  1. Open the GlassFish server Properties.
  2. Disable the option Directory Deployment Enabled, and then close the Properties.

To access your local DVN application, run or deploy the application from the NetBeans IDE. The default location for the deployed DVN application is http://localhost:8080/dvn.

Upgrade Tips

Upgrades to the development environment to support version 1.3 were extensive.

The Project recommends that you review the full Developers Guide to upgrade your environment. Pay particular attention to the Configure NetBeans and Configure GlassFish sections.