Getting Started
API Docs
Config Docs
Examples





Development

Getting Started

There are two ways to begin using jeospace. You can download the source code and build it yourself, or you can use the pre-built jars. In either case, there are some base requirements to be met listed in the System Requirements section. If you wish to start with the source, the Build Environment section will describe the requirements and process. If you wish to start from pre-built jars, you can skip to the Runtime Environment section.

System Requirements

The Jeospace libraries are written in Java and have been developed with J2SE 1.4.2, which is the minimum recommended JDK. It can be downloaded from here:

Build Environment

Tools

Jeospace has been developed utilizing the Xj3D project's X3D browser for it's 3D visualization capabilities, and (courtesy of the Xj3D developers) has adopted their development environment. This is a Unix environment utilizing GNU tools. GNU Make is required.

For MS Windows systems, the GNU tools can be obtained from Cygwin:

The base Cygwin executable package contains sufficient functionality to support the build environment.

Note: The following examples of environment settings and build instructions are taken from a Windows system running Cygwin using bash as the command shell.

Required Libraries

In order to build, the following external libraries are necessary.

To build the jeospace base library (org.jeospace.base), an X3D Java SAI library (package - org.web3d.x3d.sai) is required. The Xj3D libraries have been utilized in the jeospace development and are highly recommended (As no other X3D Java SAI library has been tried, this is most likely a requirement not a recommendation). The package org.web3d.x3d.sai (jar file xj3d-sai_2.0.0.jar) is included in the Xj3D jar and native library set provided here:

To build the jeospace swt ui library (org.jeospace.ui.swt), the Eclipse SWT library (package - org.eclipse.swt) is required. The current 3.2 release version is recommended. The package org.eclipse.swt (jar file swt.jar) can be downloaded from here:

Note that a Win32 version of the SWT library is included in the downloadable Xj3D 2.0 Prerelease. It can be found as:

xj3d-win32-rt/lib/org.eclipse.swt.win32.win32.x86_3.2.0.jar

Environment Variable Settings

Requirements

The JAVA_HOME variable must be set with the base directory of the JDK installation.

The PROJECT_ROOT variable must be set to the root directory of the source code. In the following examples, the user's HOME directory shall be:

C:/home/source_user

and if the project is checked out into this directory, the PROJECT_ROOT setting would be:

export PROJECT_ROOT="C:/home/source_user/jeospace"
Options

CVS can most easily be used by setting the CVSROOT environment variable as follows:

export CVSROOT=":pserver:anonymous@cvs.jeospace.org:/cvs/jeospace/cvsroot"

For the build environment, if the PROJECT_CLASSPATH variable is defined, it will be appended to the standard CLASSPATH variable. The required external libraries are typically added to this variable rather than directly to the CLASSPATH. If for example, the required external libraries have been saved to the directory

C:/xj3d-win32-rt/lib

then PROJECT_CLASSPATH setting would be:

export PROJECT_CLASSPATH="C:/xj3d-win32-rt/lib/xj3d-sai_2.0.0.jar;C:/xj3d-win32-rt/lib/org.eclipse.swt.win32.win32.x86_3.2.0.jar"

Build Process

Source Checkout

With the environment variables set, from a shell command line, the jeospace source can be checked out of the CVS repository.

# cd $HOME
# cvs co jeospace
Source Make
# cd jeospace
# cp make/Makefile .

The build options can be displayed by invoking make without any options:

# make

 Jeospace

Information on this project can be found at http://www.jeospace.org

The following options are offered and will build the entire codebase:

class: Compile just the classes. Don't make JAR files.
jar: Make the java JAR files
javadoc: Generate the javadoc
all: Build everything (classes, jars, javadocs)
clean: Remove all the classes

The following options allow you to build subsets of the libraries

base-class: Jeospace base classes
base-jar: Jeospace base jar
base-javadoc: Jeospace base javadoc

swt-class: Jeospace SWT UI classes
swt-jar: Jeospace SWT UI jar
swt-javadoc: Jeospace SWT UI javadoc

swing-class: Jeospace Swing UI classes
swing-jar: Jeospace Swing UI jar
swing-javadoc: Jeospace Swing UI javadoc

The following make options will place their results as follows:

# make class $PROJECT_ROOT/classes
# make jar $PROJECT_ROOT/jars
# make javadoc $PROJECT_ROOT/docs/javadoc

The jeospace build will produce three libraries:

  • org.jeospace.base - The core simulation library.
  • org.jeospace.ui.swt - The library required for usage with the Eclipse SWT UI Toolkit.
  • org.jeospace.ui.swing - The library required for usage with the J2SE UI Tookit.

Runtime Environment

The prebuild jeospace jars are available for download:

Several runtime environments are possible, depending on application requirements.

Browserless

In applications without an X3D browser for visualization, configuring the runtime environment for jeospace is relatively simple.

  • Applications without a GUI - the jeospace base library (org.jeospace.base) is the only library required to be included in the CLASSPATH.
  • Applications with a Swing UI - the jeospace swing library (org.jeospace.ui.swing) provides components that interface to jeospace objects and may be desirable to include.
  • Applications with an SWT UI - the jeospace swing library (org.jeospace.ui.swt) provides components that interface to jeospace objects and may be desirable to include. The SWT jar and native library are required.

X3D Browser

For applications requiring an X3D Browser, the Xj3D version 2.0 runtime is required. The full instructions for obtaining the source and setting up the Xj3D runtime environment can be found on the Xj3D web site. The specifics of obtaining the Xj3D source from it's CVS repository are found here: Xj3D CVS Details.

Since Xj3D version 2.0 is currently in a pre-release development phase, as a convenience, a zip archive of the Xj3D jars and Win32 native library set is available for download from this site:

The directory structure of this archive is:

xj3d-win32-rt
xj3d-win32-rt/bin
xj3d-win32-rt/lib

The bin directory must be included in the java.library.path property for the JVM. The jar file

xj3d-win32-rt/lib/xj3d-all_2.0.0.jar

should be included in the CLASSPATH

For example, if this archive were unpacked in the C:/ directory, then including the jars and native libraries could be accomplished from a command line in the following manner:

# java -Djava.library.path=C:\xj3d-win32-rt\bin -classpath .;C:\xj3d-win32-rt\lib\xj3d-all_2.0.0.jar;C:\jeospace\jars\org.jeospace.base_1.0.0.jar SimpleEarthSatelliteTracker