We're using maven 3.0.x:
Get Java6, we've run on both Sun and OpenJDK.
Protoc is required to generate code. Install protoc 2.3.0 and make sure protoc is on the path. Maven will invoke the protobuf compiler.
http://code.google.com/p/protobuf/
Refer to INSTALL.markdown for instructions on installing the broker and database.
IntelliJ is recommened because of its solid scala support and great maven integration.
http://www.jetbrains.com/idea/
To import the maven project:
- File > New Project
- Import project from external model
- Select maven, click next
- Select the directory containing your base pom, check "import maven project automatically", click next
The core reef project is structured as a number of sub-maven projects that build on each other to provide the desired functionality.
The projects are listed in order they are built by maven (which is a good indication of dependencies)
- cfg-templates : Default configuration files are kept here and copied to the main directory by maven so every developer can edit the configurations for deployment and testing without accidently committing changes.
- schema/proto : Contains the protobuf definitions for the Reef data types. Note that a key protobuf file is actually located at api/src/main/proto/ServiceEnvelopes.proto.
- schema/xml : Contains xsd (xml-schema-definition) files for both the dnp3 protocol driver and the xml loader implementation
These projects form the core of what an application trying to integrate with Reef will need to use. They are generally licensed as Apache2 (but check each project and files to be sure).
- scala-base : A synthetic project used as a parent by all of the scala projects so they don't all have to include the scala compiler and library settings.
- dependencies : A maven project to collect up all of the dependencies used in the reef project into one easier to manage combined jar/OSGI bundle.
- xml : Maven project that uses the JAXB maven plugin to build xml data binding objects for all of the xml files.
- util : Contains utiltity functions used throughout the code base, most important items are the classes in the reactor package related to actors and object lifecycle and the Logging trait. Also in this project are the configuration loading classes, timing classes, conversion functions and thread safe collections.
- proto : A mixed scala+java project that uses a maven plugin to generate the java protobuf classes from the reef types in schema/proto, ReefServicesList that defines what protobuf type should be sent on each exchange and two scala files generated by make_optional_scala.rb that make using protobuf objects simpler.
- api : Defines the low-level REST Reef client api but doesn't provide an implementation of the core classes. This project is also mixed scala+java because it includes the ServiceEnvelopes protobuf object.
- amqp : Concrete implementation of a Reef client that connects to a qpid broker. A pure scala project but it also includes a set of wrappers around the scala client for use in java code.
- api-request : High level api for interacting with the Reef system, contains simple implementations that expose a large percentage of the functionality available, more effecient calls can be hand constructed to avoid unnecessary roundtrips and client-side filtering. The test suite shows examples of how to use the XxxxXxxxService classes from scala and will output the sent and recieved protos in a maven generated web site format as a form of live documentation of the api. The tests are designed to be run against a running Reef node with the samples/integration/config.xml configuration file loaded. This is the "highest-level" project that a client application needs to import.
- integration : Java only project that provides examples of how to use the reef client from java. Also assumes it is running against a live reef node loaded with samples/integration/config.xml. The tests in this project and api-request are usually run together as the integration test. This project is only of intrest to client developers as an example of java code using reef clients.
These projects form the core of the reef server components. They are generally licensed as AGPLv3.
- metrics : A small scala project that contains classes that provide the tools to easily instrument important classes with timing, performance and counters. Provides the metrics data through a static object currently but we envision it becoming an OSGi service.
- persistence-api : Contains some common database connection code and the squeryl ORM library we use on the service side. It provides hooks to search the classpath for persistence libraries suitable to talk a type of database.
- persistence-postgresql : Contains an implementation of the persistence-api Connector class that connects to a postgresql database.
- measurementstore-api : Defines the capabilites and interface for the high volume MeasurementStore implementations. Contains a very simple in-memory implementation of a MeasurementStore that a suite of abstract tests are written against. Projects providing an implementation of MeasurementStore need to run those same tests.
- measurementstore-squeryl : MeasurementStore implementation written using squeryl to store measurements in a database. Not suited for large scale deployments but suitable for smaller deployments and testing.
- protocol-api : Defines the requrirements for a Protocol Adapter used to communicate with a field device using standard utility or SCADA protocols.
- core : Large project that contains most of the server side code. This includes the main Services, the sql definitions measurement processor componetns, xml-configuration loading code. This project contains the bulk of the classes in reef and will probably be split up in the near future. It doesn't contain the "entry points" necessary to run most of the components, those are generally written using OSGI and spring.
Though nearly all of the projects are compiled into OSGi "bundles" most of them dont explictly interact with the OSGI runtime. Most of the component entry points are implemented using OSGi to allow us to take advantage of the lifecycle and package managment in OSGi.
- services : Provides an entry point for all of the Service handling objects.
- processing : Provides an entry point to startup a set of measurement processors (one for each endpoint) under a single "process".
- fep : An entry point that uses the OSGi "service watching" system to look for packages being added and removed that implement the Protocol interface. Starts a seperate "application" for each protocol in the system.
- protocol-benchmark : A simple implementation of Protocol that randomly simulates measurements and responds to controls. Also provides some 'backdoor' karaf functions to alter the simulator charteristics.
- protocol-dnp3 : Implements Protocol using java wrappers around gec's open source c++ dnp3 stack.
We distribute Reef as a rebranded karaf OSGi container.
- assembly : Repackages and rebrands an Apache Karaf distribution with Reef software and configuration. Contains the key file: reef-feature.xml that defines which of the above bundles need to be included to make the empty karaf shell a fully fleshed out Reef node. Also includes a few sample xml-configuration files including the configuration we run our integration tests against. Also includes updated configuration files that adjust logging and maven settings.
- branding : Implements some karaf specific classes to override the default branding and print the swanky REEF logo at the top of the shell.
- admin-shell : Contains a shell accessible commands that require direct in-memory access to the running Reef node. This includes maintenance functionality to read metrics counters and reset/clear the database schema.
- proto-shell : A potentially standalone application implemented using karaf shell (gogo) to expose many of the reef api-request services as command line operations to allow quick prototyping of new user facing functionality.