README.md

   1 # Rhynodge
   2
   3 ## Description
   4
   5 Rhynodge is a tool that lets you periodically execute tasks that depend on certain conditions.
   6
   7 Its concept is quite similar to websites like ifttt (“if this then that”): you evaluate an input condition (e. g. data from a website, Facebook or Twitter posts, incoming emails, existence of a file), and if it evaluates to “yes” you execute a certain action.
   8
   9 ## Configuration
  10
  11 Rhynodge’s configuration uses JSON files (I tried using XML first but apparently polymorphic deserialization is something that is not easily done with XML parsers). The format of a ``Chain`` configuration is pretty straight-forward and can be seen in the example configuration files.
  12
  13 ## Running Rhynodge
  14
  15 Rhynodge uses Maven as build and dependency management tool. Maven can also run Rhynodge:
  16
  17 > $ mvn clean compile exec:java
  18
  19 Rhynodge accepts the following command-line parameters:
  20
  21 - ``--chains <directory>``, ``-c <directory>``: directory to load chain configurations from.
  22 - ``--states <directory>``, ``-s <directory>``: directory to store states in.
  23
  24 Both directories need to be created before running Rhynodge.
  25
  26 Rhynodge also periodically scans the chains directory to find changed or new chain configuration files. New files will be added to the running instance, changed files will be reloaded, and removing files will remove the corresponding job from Rhynodge.
  27
  28 ## Internal Concepts
  29
  30 The core of Rhynodge comprises ``Reaction``s which in turn consist of ``Query``s, ``Filter``s, ``Trigger``s, and ``Action``s.
  31
  32 ### Query
  33
  34 A query is a component that determines the state of a system: it can determine whether a file exists, or retrieves the latest 5 Twitter posts, or loads data from a website.
  35
  36 The result of a ``Query`` is a ``State``.
  37
  38 ### Filter
  39
  40 A filter is an optional component that turns a ``State`` into a different ``State``. It is used to process data and extract more useful information; e. g. a filter could take the raw data from a website and parse its HTML into a DOM tree, or a list of files could be filtered for CD images larger than 400 MiB.
  41
  42 The result of a ``Filter`` is a ``State``, again.
  43
  44 ### Trigger
  45
  46 A trigger decides if, given the current state and the previous state, a noteworthy change has occured. It could calculate the difference between two file lists, or of two Facebook post lists.
  47
  48 The result of a ``Trigger`` is an ``Output``.
  49
  50 ### Watcher
  51
  52 A watcher combines a query, a list of filters, and a trigger into a single unit which can be configured a lot easier than the separate components. For example, you could have a “Twitter” that finds new status updates for a username and that only needs to be configured with that username; the rest of the configuration is contained in the watcher.
  53
  54 A ``Watcher`` does not do any processing but instead offers a ``Query``, a list of ``Filter``s, and a ``Trigger``.
  55
  56 ### Action
  57
  58 If a trigger found a change, the action is then executed. Again, an action can be almost anything: it can send an email, it can execute programs, print documents, initiate phone calls, take a picture from a webcam — anything you can program can be used an an action.