GENESIS II DEVELOPMENT WITH ECLIPSE

This page describes how to setup a PC for Genesis II development with Eclipse. Afterwards, you will be able to run Genesis II Containers and Clients and debug them.

If you do not plan on using Eclipse, consult the older Genesis II Development Tutorial. If you would like to run a standalone build of Genesis II, consult the Getting Started and System Admin Tutorials.

INSTALLATIONS

Java

If you do not have a Java 6.x development environment, then install and configure the appropriate package for your needs. You can download the Java 6.x JDK from http://www.oracle.com/, or you can download the open source implementation from http://openjdk.java.net/.

After you install the JDK, it may be necessary to edit either your PATH environment variable or your JAVA_HOME environment variable. The installer generally does not set these up for you. JAVA_HOME should point to the root of the JDK that you want to use, whereas $JAVA_HOME/jre/bin should be added to your path.

Eclipse

Download the newest version of the Eclipse IDE for Java Developers from http://www.eclipse.org/. Among providing a software development environment, you can use Eclipse for debugging with dynamic code injection, call-hierarchy searching, and auto-formatting. Also, there is a plugin called Subclipse which integrates Eclipse with SVN with GUI features for diff’ing workspaces, files, etc. Also, we have a license for a Java profiler called YourKit which can be integrated with Eclipse.

When you first run Eclipse, you will be asked to select a workspace. Do not specify a path that contains spaces (this just generally makes life easier, although it may not be strictly necessary).

Subclipse

Go to http://subclipse.tigris.org/. Click on "Download and Install". Follow the instructions to install the Subclipse plugin in Eclipse. The best version of the SVN client to use with our SVN server is version 1.6.x.

If Eclipse fails to install Subclipse, then you may need to install the "Mylyn" plugin. The Mylyn update site is http://download.eclipse.org/mylyn/releases/latest. With most versions of Eclipse, you don't need to worry about this.

If Eclipse complains about not finding JavaHL on Linux, you may need to add /usr/lib/jni to your Java build path in Eclipse. This article has some good info about this: Failing to load JavaHL on Ubuntu

Genesis II

To obtain a copy of the Genesis II source, check out the GenesisII source tree from SVN. Under the File menu in Eclipse, select Import. In the Import dialog, in the SVN folder, select "Checkout Projects from SVN". Select "Create a new repository location". The URL is:

svn://svn.xcg.virginia.edu:9002/GENREPO/GenesisII

If you would like the current version of Genesis II, select the "trunk" folder. If you are working from a branch, select your branch name under the "branches" folder.

Select the "Check out as a project in the workspace" option. Check out the HEAD. Click Finish. You'll be asked to enter your SVN username/password to complete the checkout.


CONFIGURATIONS

Eclipse Package Explorer

For easier browsing of the Genesis II source code, setup your Package Explorer view with the following options:

  • Right click on the package explorer menu button (down arrow) and under Package Presentation select Hierarchical.
  • Right click on the package explorer menu button (down arrow) and select Filters. Add the "Libraries from external" filter.

Security

After the source distribution has been obtained, you may optionally configure your JRE to allow the BouncyCastle JCE security provider to run at full strength (with no restrictions on key length or algorithm selection). To do this, copy the Unlimited Strength Java Cryptography Extension (JCE) Policy Files (the two .jar files found in <GII-BASE>/ext/jce) to the JDK’s jre/lib/security directory.

Ant Builds

To build Genesis II, we use Ant. The two Ant targets that are most often used: build and clean.

To run ant from the command line, set the variable ANT_OPTS='-Xms512m -Xmx768m -XX:MaxPermSize=768m' to ensure that ant has sufficient memory to build Genesis.

To clean up your build:

  • ant clean

To build the default version of Genesis II:

  • ant build

To build the 64-bit version of Genesis II for Linux:

  • ant -Dbuild.targetArch=64 build
  • Note that you must use a 64-bit JVM to run this build.

The build target performs the following activities:

  • Creates directories for generated sources
  • Normalizes our extended form of WSDL (GWSDL) into proper service WSDL
  • Runs Axis WSDL2Java stub generation on our service WSDL to create the Java stub classes used by client tools and the data-structure classes for representing operation parameters within both client and server code.
  • Copies the generated .wsdd files into the "deployments/default/services" directory, so that the Axis web application can find the Java classes that implement the port types
  • Compiles both the generated and pre-existing sources
  • Archives the bytecode class files into their respective utility, client, and container .jar files.
  • Creates shell scripts for starting the container and the command-line tools in the base GenesisII directory

To create these Ant targets, go to the Run menu and select External Tools. Create Ant Builds with the following specifications.

Build Clean

  • Name: Build Clean
  • Under the Main tab: set the Buildfile. Browse Workspace and select build.xml
  • Under the Target tab: select only clean

Build Codegen

  • Name: Build Codegen
  • Under the Main tab: set the Buildfile. Browse Workspace and select build.xml
  • Under the Target tab: select only genii.ws
  • Under the JRE tab: Under VM Arguments add: -XX:MaxPermSize=512M

After running Build Codegen targets, refresh the project (F5) so that Eclipse will compile everything that must be compiled.

User Directory for Genesis II Grid State

When running, the GenesisII container stores its database state and its RNS state in a directory called the state directory. Also, the command-line client tool(s) store their session state (transient login credentials, current working directory, etc.) in this directory. By default this directory is located at:

  • $HOME/.genesisII-2.0 for Linux
  • C:/Documents and Settings/<username>/.genesisII-2.0 for Windows

You can change the location of the state directory by setting the GENII_USER_DIR environment variable before you run the container or the client. Genesis II always respects this environment variable, regardless of whether you are using Linux or Windows, and regardless of whether you run GII from Eclipse or from a shell.

In Windows, to set an environment variable, go to System Properties, open the Advanced tab, open the Environment Variables dialog, and create a new variable:

  • Name: GENII_USER_DIR
  • Value: <location of dir> (i.e. C:/.genesisII)

Note, you will need to manually delete this directory in order to restart your container in a totally clean state.

Run Configurations

To run Genesis II within Eclipse, you will need to configure two Run Configurations. To create a configuration, right-click on the project (in the Package or Navigator view). In the menu, select "Run As". In the submenu, select "Run Configurations..." In the dialog window, select "Java Application" and click the "New launch configuration" button.

Creating a Profile for Running the Container

  • Name: Container
  • In the Main tab, select the Project
  • In the Main tab, set the Main class to:
    edu.virginia.vcgr.genii.container.Container
  • In the Arguments tab, add the following VM arguments:
    -Dlog4j.configuration=genesisII.log4j.properties
    -Djava.library.path=${workspace_loc:GenesisII/jni-libs/lin32}

(or

    -Djava.library.path=${workspace_loc:GenesisII/jni-libs/lin64}
    -Djava.library.path=${workspace_loc:GenesisII/jni-libs/win32}
    -Djava.library.path=${workspace_loc:GenesisII/jni-libs/osx64}

)

    -Dedu.virginia.vcgr.genii.install-base-dir=${workspace_loc:GenesisII}
    -Djava.net.preferIPv4Stack=true
    -Djava.net.preferIPv6Addresses=false
  • If you want to change the default location of the state directory, then in the Environment tab, create a new variable called GENII_USER_DIR and set the location.

After you save this configuration, you can run it either (a) from the Run Configurations dialog box, or (b) from the Debug Configurations dialog box, or (c) from the Run menu's "Run As" or "Debug As" submenus, or (d) from the Run tool or the Debug tool in the toolbar.

Creating a Profile for Running the Client

This will create a launch configuration that starts the CLI tool called the grid shell. You can use the grid shell to run all of the subtools.

  • Name: Client
  • In the Main tab, select the Project
  • In the Main table, set the Main class to:
    edu.virginia.vcgr.genii.client.cmd.Driver
  • In the Arguments tab, use the same VM arguments as for the Container
  • In the Environment tab, you may set the GENII_USER_DIR variable

RUNNING GENESIS II

Once you have setup the above, here are the steps to running Genesis II.

  • Run the Build Codegen target in order to generate Java files from WSDL files.
  • Refresh the project in order to compile the source files and the generated files.
  • Run the Container profile.
  • Run the Client profile.

At this point you should see the Grid shell running and ready for input commands.

The first time that you run the container, you will need to create the root directory and related resources. To do this, in the Grid shell, run:

    script file:deployments/default/configuration/bootstrap.xml

Then you will need to login. Initially, there are no defined users, groups, or accounts. The security credential that "owns" the grid is an X509 certificate named "skynet1.cs.virginia.edu". To login with this credential, run:

    keystoreLogin --password=[...] file:deployments/default/security/keys.pfx --pattern=skynet1

(Even though the password to skynet1's private key is not in this document, it's not a secret. It's semi-public. Do not store private data in a grid owned by skynet1. Only use it for debugging.)

Verify that your local container and local client work by running commands such as "whoami", "ls", etc.