There are currently three different API's that the can be used by a client to access a Shared Records data store. These APIs increase in the level of functionality and decrease in the level of flexibility. Similiar to Windows Explorer building on top of the Win32 API building on top of I/O assembly functions.

The three APIs are accessed by three different classes:

Low level data store API

  • org.sharedrecords.core.storage.DataStore: This is currently the lowest level API available for interacting with a Shared Records data store. DataStore.java itself is abstract and subclassed by org.sharedrecords.core.storage.LocalDataStore and org.sharedrecords.core.storage.RemoteDataStore. LocalDataStore stores directly to a file system while RemoteDataStore passes calls through to the HTTP API. LocalDataStore is currently cross platform compatabile and does not use J2EE methods. RemoteDataStore creates web requests using the apache commons libraries and makes calls to the HTTP REST API (it points to a server location specified in org.sharedrecords.properties by default). The HTTP API that is currently implemented passes the calls and data to a LocalDataStore instance running on the server using Java Sevlets with minimal functionality (there is more information describing it linked from the main page). The current HTTP API methods have a 1-to-1 mapping with the DataStore.java API methods. These classes do not provider any encrypton capabilities or do verification of signatures during record retrieval.

Main Client API

  • org.sharedrecords.client.StorageProviderImpl: This API is an implementation of org.sharedrecords.client.IStorageProvider which is a API that executes multiple calls to a DataStore object in a single method for easier use of the API. It depends heavliy on the encryption utility class, EncryptionUtils and calls to a DataStore object. This class serves as a recommended implementation of how we think the DataStore API should be used. There are calls here such as createRecord that will accept a file, user name, user key, signer name, and signer key and perform the encryption of the record, signature of the record, deposit of the record, and deposit of the signature. We believe this class provides the functionality at a level that is appropriate for most developers. This contains the common use cases that most people will use. This class requires that you set an instance of a DataStore object into it using set_dataStore().
  • NOTE: StorageProviderImpl?'s documentation should link to IStorageProvider, but it current does not. Please see IStorageProvider for java doc comments.

Demo Application API

  • org.sharedrecords.demo.controller.Transaction: This contains the highest level API and in some cases, provides no more functionality than the StorageProviderImpl. The Transaction class has many dependancies to the Java Demo application, most importantly to org.sharedrecords.demo.utils.KeyStoreUtils. KeyStoreUtils is used by the Demo application to manage both its own keys (for signing) and all user keys. In addition, the Transaction class depends heavily on IStorageProvider (just as StorageProviderImpl depends heavily on DataStore). The Transaction class provides more functionality when it comes to depositing and retrieving records. The Transaction class will create a record from file and then add a meta data entry for the record that stores the file extension. When retrieving the record, the Transaction class then knows how to also retrieve its extension, if available from the MetaDataEntry it created. There are several variables that must be configured in order to allow the Transaction class to operate without Demo.java's constructor and initalization code running. The Transaction class depends on many properties in a properties file called org.sharedrecords.properties to determine if it should place deposits locally or remotely, and if it should cache those results. Those properties are described here [Wiki:ConfigurationGuide: here]. The properties are loaded both from the properties file as well as the Windows Registry (these are created during install). If you desire to use the Transaction class without using the GUI of the demo app, the following steps will setup the Demo application's configuration and KeyStoreUtils setup to work without displaying the GUI:
  1. Install the Demo application onto your machine as described here, remember the key store password.
  2. Link to the srcdemo.jar file.
  3. Initialize your Demo environment using the following code (found in DemoTransactionTest.setUp()): 
        demo = new Demo();
    demo.initForNonGuiUse();
    KeyStoreUtils.getInstance().setPassword("password_you_set_during_install".toCharArray());
    KeyStoreUtils.getInstance().initialize();
  4. Deposit a record using the following code (found in DemoTransactionTest.testDeposit()): 
        Record r = Transaction.getInstance().createRecordSignedByApp(null,
	                                new File("c:\\temp.txt"));
    NOTE: at this time, only anonymous deposits are supported when using the Demo application in an non GUI mode. The demo application requires an account's private key in order to make a record deposit, which requires the application to prompt for the user's password in a GUI Modal Dialog. There is currently no bypass for this although it could be implemented by modifying the Transaction class and KeyStoreUtils class.