View on GitHub

Fallen-8

Download this project as a .zip file Download this project as a tar.gz file

Fallen-8 logo

Welcome to Fallen-8.

Fallen-8 is an in-memory graph database implemented in C#. Its focus is to provide raw speed for heavy graph algorithms.

Key featues

Sweet spots

HowTo Clone

Fallen-8 makes use of git submodules, that's why they have to be cloned too.

$ git clone --recursive git@github.com:cosh/fallen-8.git

HowTo Use

var fallen8 = new Fallen8();

//start the built-in services
fallen8.ServiceFactory.StartGraphService();
fallen8.ServiceFactory.StartAdminService();

Service plugins

Service plugins are the easiest way to add use-case specific functionality on top of Fallen-8. There are two standard plugins available:

They are started by default using the StartUp project.

[Fallen-8_Graph_Service:config] URIPattern (n/a, using default): Fallen-8_Graph_Service
[Fallen-8_Graph_Service:config] IPAddress (n/a, using default): 127.0.0.1
[Fallen-8_Graph_Service:config] Port (n/a, using default): 9923
Fallen-8 Graph Service Plugin v1.0.0
   -> Service is started at http://127.0.0.1:9923/Fallen-8_Graph_Service/1.0/REST
[Fallen-8_Admin_Service:config] URIPattern (n/a, using default): Fallen-8_Admin_Service
[Fallen-8_Admin_Service:config] IPAddress (n/a, using default): 127.0.0.1
[Fallen-8_Admin_Service:config] Port (n/a, using default): 9923
Fallen-8 Admin Service Plugin v2.3.0
   -> Service is started at http://127.0.0.1:9923/Fallen-8_Admin_Service/1.0/REST
Enter 'shutdown' to initiate the shutdown of this instance.

The lovely .Net is able to help you using the REST services. Just take a look at the webservice help:

In order to create your own Service plugin four steps need to be taken. The following example code can be found in Examples/ServicePlugin. There is a slightly bigger "benchmark" service which could act as some kind of bluprint service for you located in Examples/Benchmark.

Webservice contract

The webservice contract defines the functions which you would like to add on top of Fallen-8. It's a plain old service contract with one extension: you have to implement the IRESTService interface.

    [ServiceContract (Namespace = "Fallen-8-Training", Name = "Fallen-8 training service")]
    public interface IHelloService : IRESTService
    {
        /// <summary>
        /// Say hello to someone
        /// </summary>
        /// <param name="who">The one you like to say hello to</param>
        /// <returns>Hello to someone</returns>
        [OperationContract (Name = "Hello")]
        [Description ("[F8Training] Hello: Says hello to someone.")]
        [WebGet (UriTemplate = "/hello/{who}", ResponseFormat = WebMessageFormat.Json)]
        String Hello (String who);
    }

Webservice contract implementation

Create a new IHelloService implementation and implement the methods. In this first example don't do anything in the "IRESTService", "IFallen8Serializable" and "IDisposable" implementations.

    public class HelloService : IHelloService
    {
        ...
        #region IHelloService implementation

        public string Hello (string who)
        {
            return "hello " + who;
        }

        #endregion
        ...
    }

The Fallen-8 plugin

The actual Fallen-8 plugin needs to extend the ARESTServicePlugin abstract class. The most important field is the "PLUGIN_NAME". This is the unique name of your plugin. You'll need it later in order to start the plugin. Interesting regions:

public sealed class HelloServicePlugin : ARESTServicePlugin
    {
        public const string PLUGIN_NAME = "Fallen-8_Hello_Service";
        public const string MANUFACTURER = "Henning Rauch";
        public const string PLUGIN_DESCRIPTION = "Fallen-8 Hello Service Plugin";
        public const string VERSION = "1.0.0";
        public const double RESTVERSION = 1.0;

        #region IFallen8Serializable implementation

        public override IRESTService LoadServiceFromSerialization (SerializationReader reader, Fallen8 fallen8)
        {
            return new HelloService ();
        }

        #endregion

        #region IPlugin implementation

        public override IRESTService CreateService (Fallen8 fallen8, IDictionary<string, object> parameter)
        {
            return new HelloService ();
        }

        ...
        #endregion
    }

Start the plugin

This is pretty simple now. Just tell Fallen-8 what you like to have and you'll get it.

IService helloService;
            if (fallen8.ServiceFactory.TryAddService (out helloService, "Fallen-8_Hello_Service", "Hello API", null)) {
                if (helloService.TryStart ()) {
                    Console.WriteLine ("Wohooo.");
                }
            }

After you started the project you'll see this:

[Fallen-8_Hello_Service:config] URIPattern (n/a, using default): Fallen-8_Hello_Service
[Fallen-8_Hello_Service:config] IPAddress (n/a, using default): 127.0.0.1
[Fallen-8_Hello_Service:config] Port (n/a, using default): 9923
Fallen-8 Hello Service Plugin v1.0.0
   -> Service is started at http://127.0.0.1:9923/Fallen-8_Hello_Service/1.0/REST
Wohooo.
Enter 'shutdown' to initiate the shutdown of this instance.

just try it: http://127.0.0.1:9923/Fallen-8_Hello_Service/1.0/REST/hello/world

Benchmarks

There are plenty of benchmarks in the world. This is a puristic one that focusses on the raw traversal speed of Fallen-8. It creates an equally distributed graph with a defined number of vertices and edges. Afterwards you are able to measure the traversals per second for your graph in Fallen-8. In order to start the benchmark, compile the Examples/Benchmark project and start it with Admin-Rights. It uses the service plugin pattern described in the last point and provides two web-services

As always there is a .Net help available: http://127.0.0.1:9923/Fallen-8_Benchmark_Service/1.0/REST/help

Additional information

Graph databases - Henning Rauch

Graphendatenbanken - Henning Rauch (visiting lecture)

Issues on GitHub

Wiki on GitHub

Google Group

MIT-License

Copyright (c) 2012-2015 Henning Rauch

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE