Working with the SRC Demo Source Code

General Instructions

All of the source code needed to build the Demo Application is available as either Java source or bundled in the srcdemo.jar archive. The libraries listed in the file sharedrecords/etc/.classpath need to be added to your build path. In addition, you will need to install the Java Web Services Development Kit, available from the Sun website, and add the JWSDK libraries to your build path. The JWSDK provides the jax-rpc framework that is used when the API is accessing the server.

Working with Eclipse

Subclipse is the Subversion plug-in for Eclipse. If you are running Eclipse in a Linux environment, you may need to do the following steps as root, depending on the details of your installation.

  • Start up Eclipse, and go to Help -> Software Updates -> Find and Install
  • Select "Search for new features to install" then click Next. On the following screen, select New Remote Site; enter "Subclipse" as the name and  http://subclipse.tigris.org/update_1.0.x as the URL. Click Okay.
  • Select this new site and click Finish. The Eclipse package manager will stat the site and show you a list of plug-ins you can install.
  • Select the newest version of Subclipse, and then click through the dialog screens until it is installed. You will be prompted to accept the license agreement for Subclipse, and then to restart Eclipse.

Source Code Checkout

Now you should checkout the Demo Application source code from the repository.

  • From the menu bar, select Window -> Open Perspective -> Other -> SVN Repository Exploring. Select Window -> Show View -> SVN Repository.
  • Right click in the newly opened window, and select New -> Repository Location. Enter  https://svn.sharedrecords.org/sharedrecords/java/client/Demo/trunk/ as the repository URL and click Finish.
  • When prompted, type your username and password, and Eclipse will add the repository to its list. You can explore the repository remotely by clicking through the files in the tree. Please be patient, as it takes some time for Eclipse to populate the browser, especially if you are connecting over a wireless network.
  • To check out a local copy of the source code as a project in the workspace, find the folder you want to work from. If you are only going to build from source, you probably want svn/sra/trunk. If you are actively developing, find svn/sra/branches/personal/your-user-name. Right click on the directory you want to work from, and select Check out. Select the Check out as a project in the workspace radio button, and enter a name for the project in the text field, then click Finish. It may take quite some time to download all of the files.
  • Select Window -> Open Perspective -> Java to switch back to the Java perspective. You should have a new project in your workspace called by whatever name you entered in the previous step, complete with .classpath and .project files. You might need to close the Welcome window first before you are able to see the new project. By default, Eclipse will display the packages in a flat view. To view the source packages as a hierarchical tree, go to Package Explorer window. If your package explorer is not open, go to the menu bar, and select Window -> Show View -> Package Explorer. In the package explorer menu bar, click on the small white downward-facing triangle, then select Layout -> Hierarchical.

Excluding Branches

The sharedrecords/src directory is further divided into trunk/ and branch/ directories. In general the trunk directory contains the latest code and should be used to build the client jars and to deploy the server code. The branch directories are for short term refactoring. It is a good idea to exclude these extraneous branches from the build path.

  • Go to Project -> Properties -> Java Build Path -> Source and make sure that the only folder in the display is [ProjectName]/src/trunk or, if you are working from a branch, [ProjectName]/src/branches/yourbranch.

JDK Troubleshooting

If you see this build error: "Syntax error, parameterized types are only available if source level is 5.0," you need to check that you have JDK v.1.5.0 or higher installed and that Eclipse is set to version 5.0 compliance.

  • To check that you have the right version of the JDK, right click on the top level folder for your project and select Build Path -> Configure Build Path from the context menu. Select the libraries tab in the dialog box and confirm that the JRE System Library attribute is v. 1.5.0 or higher.
  • If you do not have the JDK v.1.5.0 or higher installed, download it from  http://java.sun.com and install it.
  • Right click on the project folder and select BuildPath? -> Configure Build Path. Select the libraries tab and click Add Library -> JRE System Library -> Next. Select the radio button Alternate JRE. If version 1.5 is available in the drop down menu, select it and click Finish. If not, proceed to the next step.
  • Select Installed JREs -> Add. If the text field JRE type is blank, enter Standard VM. Type JRE 5.0, or some other identifier of your choice, in the text field JRE name. Click Browse and navigate to the folder in which you have installed Java. Select the JRE folder and click Okay. Click Okay in the next dialog box as well. Click the checkbox next to the new JRE definition you just created and click Okay. Click Finish. Click Okay.
  • To change the compliance setting, again right click on the project folder and choose Build Path -> Configure Build Path. In the menu on the left, select Java Compiler. Click the check box next to Enable project specific settings, and then select 5.0 from the drop down box labeled Compiler Compliance Level. You will need to rebuild your project.

Installing JUnit

To run the unit tests, you will need to make sure that junit.jar is on your build path. In a standard installation of Eclipse you can accomplish this with the following steps.

  • Go to Project -> Properties -> Java Build Path. Look in the Libraries tab. If the variable JUNIT_HOME has been initialized and contains junit.jar, skip the rest of this step. If not, select Add Variable. Select JUNIT_HOME, click Extend, select junit.jar, and click Okay.

Setting up the datastore and keystore

Finally, set up the data store and register the camera drivers.

  • Either in Windows explorer or at the command line, navigate to your Eclipse workspace, then into the bin/ folder of your project home. Run regsvr32 on mediaTokenSensorComponenent.dll to register this dll with windows.
  • Now navigate into your project home and create a directory called data_store/. Copy [Project_Home]/etc/keystoreinit.bat into data_store/ and run it. You do not need to enter actual data for your name, institution, etc, but you do need to create a password. Remember the password you enter, as you will need this password to test the application.

Running, Testing and Debugging

  • To run the application, first generate an RSA public/private key pair. There is a convenience class, org.sharedrecords.demo.KeyPairGenerator that will create these keys for in the root of the C Drive. The files will be named public.key/private.key. You can move these keys to the root of any drive or external media, such as a USB key. In order to generate these keys using this class, right click on the file org.sharedrecords.demo.KeyPairGenerator and select run as Java Application.
  • Next, ensure that the necessary win32 libraries are in your system path. The files necessary are the four .dll files in the [Project_Home]/lib directory (swt-*-win32-3232.dll). One easy way to ensure this is to copy the files into the C:\WINDOWS\System32 directory. Alternately, you can modify the "Path" system variable to include the [Project_Home]/lib directory.
  • Add runtime information to the Windows registry. Click the Windows Start button and select Run. In the dialog box, enter 'regedit' and click Okay. In the registry editor, expand the tree for HKEY_CURRENT_USER and then right click on Software. Select New -> Key. At the prompt, name the key SharedRecords. You need to create four string values (NOTE, if you have already run the Installer for the demo application, this should already exist):
    • Alias - the Application alias of the demo application. This account name is used to sign records deposited through the demo applicaiton.
    • AutorecordDir - the directory that the demo application will watch to create records from if a new file is dropped into the directory.
    • ClientCacheDir - the directory location to store information for the demo app, including a local keystore for private keys.
    • LocalDataStore - the location of the local data store used to share records.
  • For each of these, right click SharedRecords and select New -> String Value. A new value will appear in the right hand panel. Enter the key name, with capitalization exactly as it appears in this paragraph. Double click on the key name, and in the dialog that appears, enter a value. Alias is the application UID that will identify the demo app to the server. AutorecordDir is the fully qualified path to the autorecord directory. ClientCacheDir is the fully qualified path to the directory in which local client application ocnfiguration data is to be stored. LocalDataStore is the fully qualified path to the local data store, in which encrypted records will be stored.
  • To run the Demo application, within Eclipse, right click on any class belonging to the demo app and select Run As -> Run. In the dialog box that appears, make sure Java Application is selected in the Configuration list, and then click New. Type a descriptive name in the text field Name. Under Main class, click Search, and type "**Demo". Select "Demo - org.sharedrecords.demo" and click OK and then Run. After you have done this once, you can run the application subsequent times by selecting this configuration name from the drop down menu next to the green circle and arrow icon in the Eclipse toolbar.
  • To debug the application, follow the instructions for running the app, but replace Run As -> Run with Debug As -> Debug.
  • To run the unit tests, right-click the class AllTests and select Run As -> JUnit Test. Note that these tests only test the API, and not the GUI demo.

Commiting Source Code

  • In the Package Explorer, right click on the project root folder and select Team -> Commit. Enter a comment, select the resources you want to commit, and click Okay. To only commit one folder or file, right click the branch of the tree you want to commit. The Subclipse plugin should support advanced SVN features like tagging, branching and merging. Consult the appropriate Subclipse documentation.

Building the Demo

First you will need to update the JAR manifest.

  • If you have added library files that the user will need in order to run the program, open the MANIFEST.MF, (found in sharedrecords/etc/) and add the names of the libraries. Pattern match on the format that the manifest file uses already. Make sure to drop those libraries in sharedrecords/lib/ before you commit.

Then, you will need to produce the java archive file.

  • In the package explorer, expand the tab etc/ and rightclick demo.jardesc. Select Create Jar.

If you have changed the package structure for the demo, or added packages or class defintions, you need to edit the jar description.

  • Right click demo.jardesc and select Open Jar Packager. In the dialog that appears, expand the tree in the left hand panel: it should contain all the folders in the project. Select the packages you want to include in your jarfile and make any other configurations. Click Next. If you want your changes to the build process to be saved and used again, check "Save the description of this JAR in the workspace". If you do not want to overwrite the default description, rename the description file. Click Next again. Now configure the manifest file and click Finish.
  • If you modified API files (files in the package org.sharedrecords.core or its subpackages), follow the export instructions in the previous step, exporting the shrc package and its subpackages to sharedrecords/lib/srcapi.jar.
  • If you want to use the ANT buildfile included in /etc, you will need to find the directory where you have installed Ant, and remove ant-junit.jar from ANT_HOME/lib/. Move ant-junit.jar to the directory that contains junit.jar, in order to make the JUnit tests run correctly.

Last Word

After you are done working with the source code, please remember to commit your changes to the repository using the command line, TortoiseSVN, Subclipse or your favorite SVN utility.