Skip to content

HOWTOs

Jump to bottom
Julien Gedeon edited this page Nov 8, 2018 · 16 revisions

Framework Extension

How to create a new context class

(This process still requires some work to do, we plan to simplify this in future versions of the framework.)

Adding a new context type to the framework is a process of the following steps.

  1. Add and implement the new class in the package vstore.framework.context.types:

    • Your context class should inherit from the base class VContextType.
    • The name of your context class should be appended as a type for the generic:
      • Example: public class MyContextType extends VContextType<MyContextType> { ... }
    • Give your new context class the desired attributes.
    • The following abstract methods must be implemented:
      • The constructor MyContextType(JSONObject): Used for creating a new object of your context type from a given json object.
      • JSONObject getJson(): Used for retrieving a JSON representation of your new context type
      • boolean matches(MyContextType other): Used for checking, if your context matches another given context of the same type

  2. Add your new context type to the ContextDescription class in the package vstore.framework.context:

    • Add it as a private member.
    • Add the necessary initializations in the constructors.
    • Add getter and setter for your context type.
    • Add a void clear[MyContextType]Context() method which sets the private member to null.
    • Add a boolean has[MyContextType]Context() method, which returns true if your context type is set in the ContextDescription
    • Add it to the getJson() function of the ContextDescription class.

  3. Proceed similarly for the RuleContextDescription class, if you want to be able to use your context in the decision rules

  4. Finally, define the desired behavior when using the context during the matching procedure (class Matching in the package vstore.framework.matching):

    • Add a method private boolean checkConditions_[yourConditionName](VStoreRule r, VStoreFile f) { ... }
      • Must return true, if the rule should be kept in the result set
      • Mus return false, if the rule should be deleted from the result set, because your context conditions are not met.
    • Add your condition to the conjunction in the method boolean eliminateRuleByContext().

  5. That's it! Now you can pass a context description and rules to the framework which use your context type.

App Development

Compiling the Framework

The project provided in this repository uses the Gradle buildsystem.

Compile as a library

To compile the framework as a library for an Android project, simply put the vstore-framework directory into the root directory of the application project. Then, add the framework as a module dependency to the app's build.gradlefile:

dependencies {
    implementation project(":vstore-framework")
}

Compile as a runnable jar

To compile the framework as a runnable jar (e.g. because you want to use it from Python applications via py4j), we included a build target in the framework's build.gradle.

To run this, simply execute the command gradle fatJar. The resulting file is called vstore-framework-all-deps-x.y.z.jar and can be found in the directory build/libs/.

To run it, execute the command java -jar vstore-framework-all-deps-x.y.z.jar.

Getting Started

Initialization

First, we need to provide a base level directory to the framework, where it has full read and write access.

VStore.initialize(<path>);

This command initializes the framework instance and the framework can now be used.

Creating a configuration

Next, there is the possibility to download a configuration file from a defined location. This configuration can contain the following information:

  • A pre-defined set of storage nodes and information about them (location, network speed, type)
  • A set of matching rules, with context and detail scores

The following comand tells the framework to download this file:

ConfigManager confMgr = VStore.getInstance().getConfigManager();
confMgr.download(<URL_TO_File>, <true> or <false>);

The second parameter determines, if the download of the configuration file should block (true) or if it should continue in the background (false).

Managing context and rules

To actually use the framework for file storage, we need to provide some context information. Furthermore, more rules can be added in addition to the rules that are already contained in the configuration file we have downloaded in the last step.

To provide the framework with new context information or new rules, the following methods can be used:

VStore vstore = VStore.getInstance();
vstore.provideContext(<ContextDescription>);
vstore.provideRules(<RuleDescription>);

For the structure of a ContextDescription instance, you can look at the documentation of vstore.framework.context.ContextDescription .

Persisting context information

The provided context information does not persist by default, when the current framework instance is destroyed. This means, the next time the framework is initialized, it will start without any context. If you want the information to be persistent, you need to call the following method and set the parameter to true. If you set the parameter to false, the persistent context will be deleted.

vstore.persistContext(<true> or <false>);

The information will be kept until you update it with the provideContext method or until you clear it using

vstore.clearCurrentContext();

You can also chain these commands by doing the following:

vstore.clearContext()
      .provideContext(<ContextDescription>)
      .persistContext();

This makes things a bit easier.

Additionally, there is the possibility to do the same thing using the ContextManager:

ContextManager ctxMgr = ContextManager.get();
ctxMgr.provideContext(<ContextDescription>);
ctxMgr.persistContext(<true> or <false>);
ctxMgr.clearCurrentContext();
ctxMgr.getCurrentContext();

Handling matching-rules

For manually adding and deleting matching rules, you can use the Rule Manager.

RuleManager ruleMgr = RuleManager.get();
ruleMgr.getRules();
ruleMgr.storeNewRule(<VStoreRule>);
ruleMgr.deleteRule(<RuleId>);
ruleMgr.updateRule(<VStoreRule>);
ruleMgr.clearRules();

Storage of a file (.store())

To store a file, the framework needs

  • a path to the file
  • a flag which determines if the file should be stored for public access or only for private access
  • an identifier of the source device.

Then you need to call vstore.store(); with these parameters.

Internally, the framework will perform the following actions:

  • Derive the MIME type of the data
  • Copy the file into the local framework folder
  • Compute a hash for the file (currently MD5)
  • Check if the same file was uploaded previously
  • Perform the matching algorithm to find a target node for the file
  • Upload the file in the background.

If any of these steps fails, the method will throw a StoreException. Possible error codes can be found in the enum vstore.framework.error.ErrorCode.

Keeping track of the upload state

Since the framework uses the GreenRobot EventBus (Pub/Sub paradigm) for providing information to the application, you can subscribe to the following events to keep track of the upload state:

UploadBeginEvent - Published once the upload to a storage node starts
UploadStateEvent - Published regularly during the upload, containing the progress in percent.
SingleUploadDoneEvent - Published once the upload to the storage node has finished.
UploadFailedEvent - Published when an upload attempt failed.
UploadFailedPermanentlyEvent - Published, when the upload failed permanently (after 3 attempts).

Retrieving a file (.get())

To retrieve a file, the method getFile() of the VStore class should be used. Please pass it the file identifier and the target output directory as parameters.

The progress of the download will then be published in different events:

Keeping track of the download state

DownloadedFileReadyEvent (sticky) - Published when a requested download is ready.
DownloadFailedEvent (sticky) - Published if the download for a file failed.
DownloadProgressEvent (sticky) - This event gets published regularly during a file download. 
DownloadStartEvent - Published when a download for a file starts.

Using the Framework from Python

Since the framework is written in Java, we use py4j to access the framework functionality from Python. For more details, see the example python_bindings.py

Clone this wiki locally