folknology / reactored

Copyright (C) Alan Wood 2008

The starting point for Reactor is the 'reactor' Erlang/OTP application.In order to get reactor up and operational you 
will need to run 'Reactor' as an OTP Application, you can do this in an erlang shell via erl.

Reactor will use Mnesia for storage, thus you can use the usual mnesia dir start up directives to tell it where to store 
you information. Please be aware that the small number of unit tests included are conpletely destructive to your 
storage, thus only run them with a dummy test storage directory, rather than any useful data you may wish to keep ;-)

WARNING -  This isn't really a storage backend, please don't expect it to be one, it is more like a reactive cache. 
Expected usage would have an S3 sink replicating everything incoming, old items would be expected to expire under your 
control. The exception is for small storage projects where mnesia's limits are not considered an issue, if used this way 
you must understand mnesia settings etc.. The other exception is where this is used on distributed 64 bit systems using 
mnesia replication/distribution or even a fragment hack inside attributes.erl but this isn't for the light hearted!

Please forgive the lack of any real documentation provided with this initial release, I know it is unforgiveable really, 
but I needed to place a stake in the ground with Reactor and just get the code up and out there under a proper license.


The Public API calls are found in the actor_server.erl file. These are the calls you need to make from your web 
application/framework. These are made up of identity creation/deletion (reactor participants), a Resource API (you  nedd 
to hook this up to a REST like interface) providing basic CRUD operations, a Listing API for retrieving aggregated 
stored data via search, tagging, profile, domain query and graph. Finally there is an API to manage the built in Access 
control list functionality. This allows fine grained control over items stored within Reactor. Basic primitives for each 
item/actor of retrieve,update,delete and create are provided, it is also possible to extend these primitives, but that 
may just complicate matters further!!

In order to understand how the information flows through Reactor ; First it will enter the actor server and flow in an 
anticlockwise direction through the pattern server, domain server onto the queue. The sink server picks up the actions 
from the queue and passes them to the action server which inturn fires up the required sink adaptor to process the 
actions. The index server is in fact a system wide sink adaptor. The index server also houses many of the utility 
functions for retrieving search or tag based listings from it's indexes. Requests to the actor server are controlled 
authorised automatically by the Identity server. Assuming successful authorisation the request data is stored  (if it's 
a write) or retrieved  via the attribute server. That requests is also patterned matched by the pattern server/domain 
server. see docs/Reactor.pdf for a diagram of the Reactor core.

The core should look after itself under Reactor supervision. Sinks and domains are loaded as they are needed 
dynamically. Your focus in usng Reactor is really to develop a Reactor Domain plugin. These plugins are simple OTP 
applications conforming to a single api call from the domain pattern matcher. To get an idea checkout the example 
'Matcher' in the src/domains/matcher directory , you will find the match api call in the matcher_server.erl file. This 
call gets broken down into some simple matching patters in the 'Internal Functions' section of this file where we break 
the matches into read and write matches calling the actual match implementation file 'matcher.erl' This  provides a 
simple matching pattern of all,read and write which makes organising your pattern matches even simple. The return from 
the match calls have a special format and are placed on the queue for processing. The easiest way to build a reactive 
domain app is to copy the whole matcher directory and rename it (and its contents appropriately for your application, 
don't forget to change the module names etc.. The return is basically a proplist with keys that match the Item record, 
avoid using the internal parts of the item schema like sync,revision,modified,created and uri as these are handled 
automatically. Use xref to refer to any stored item, title for the name of the sink targetd, description is the content 
of the application and is domain specific.

I hope to get some nice examples up in order to help step through the process of building a reactive domain app.

If you have any questions please contact me
Regards
Al