Common Software is the package of services and infrastructure software that integrates the TMT software systems.
See here for a detailed description of the CSW software.
The latest API docs can always be found at http://tmtsoftware.github.io/csw/.
For a list of recent changes, see the CHANGELOG.
| Date | Tag | Docs | Source | Download |
|---|---|---|---|---|
| 2016-12-03 | CSW-0.3-PDR | API | csw-0.3 | Source: tar.gz, zip, Scala API Docs: tar.gz, Java API Docs: tar.gz |
| 2015-11-18 | CSW-0.2-PDR | API | csw-0.2 | Source: tar.gz, zip, API Docs: tar.gz, zip |
The easiest way to build this project is to run the install.sh script (or quick-install.sh, which skips
generating the documentation).
To build manually, run 'sbt' in the top level directory and type one of the following commands:
- compile - compiles the sources
- test - run the tests (Note that not all tests run automatically, due to dependencies on external servers)
- multi-jvm:test - run tests that use multiple JVMs (Switch to individual project first to avoid "address in use" errors or conflicts)
- stage - create the standalone apps and test apps (installed in */target/universal/stage/bin)
- publish-local - publish artifacts to the local ivy repository (~/.ivy2)
- unidoc - generates combined scaladocs for all projects
Classes providing the CSW Java8 APIs can be found in the javacsw subproject, but also in the util subproject, where the Scala and Java APIs for configurations are found.
In many cases you can use the Scala classes directly from Java. In cases where Scala specific features are used, Java API methods are provided or alternative Java interfaces are provided. The Java interfaces use that same name as the Scala versions but start with 'I', while Java API specific classes use thw same names, but start with 'J'. See the API docs and Java test cases for how to use the CSW Java APIs.
The following sbt commands generate packages that can be installed on various systems:
- universal:packageBin - Generates a universal zip file
- universal:packageZipTarball - Generates a universal tgz file
- debian:packageBin - Generates a deb
- rpm:packageBin - Generates an rpm
- universal:packageOsxDmg - Generates a DMG file with the same contents as the universal zip/tgz.
The script ./install.sh creates an install directory (../install) containing start scripts and all of the required dependencies for starting the CSW applications, as well as the generated java and scala documentation. The quick-install.sh script runs a bit faster, but does not generate the documentation.
The Event, Telemetry, and Alarm services assumes that redis-server (at least vers. 3.2.5) is running (http://redis.io/).
(The old event service (event_old) depends on an external Hornetq server running (http://hornetq.jboss.org/)).
Since the csw software uses actors that communicate over the network, the firewall should be disabled.
It is a good idea to allocate enough memory to sbt when compiling or testing: This can
be done by passing the -mem option to sbt: For example: sbt -mem 2048.
Some of the test cases and demos depend on the Event, Telemetry or Alarm services assume that they are running and registered with the Location Service. A script (csw-services.sh) is provided to start the services needed by the tests. Usage: csw-services.sh [start|stop].
Note that the csw-services.sh script requires that the environment variable CSW_INSTALL point to the directory in which the csw software is installed (../install/, relative to this file) and that the redis-server version is at least 3.2.5.
In the current version, it is common for some tests to fail when run together, but pass when run separately. We are working on a solution.
- aas - Authentication and Authorization service (todo...)
- alarms - the Alarm Service (for setting and subscribing to alarms and system health)
- apps - contains some standalone applications
- ccs - the Command and Control Service (for sending configurations to HCDs and Assemblies)
- cs - the Configuration Service (manages configuration files in Git repos)
- dbs - Database Service (todo...)
- event_old - an earlier version of the Event Service, based on HornetQ
- events - provides Event Service, key/value store and publish/subscribe features based on Redis
- examples - contains example projects, including Scala and Java versions of a "Vertical Slice" Assembly/HCD example
- javacsw - provides Java (8) APIs for the CSW classes
- loc - the Location Service (based on Multicast DNS, supports registering and finding Akka and http based services)
- log - contains logging related code and configuration files
- pkg - a packaging layer over the command service that provides Container, Supervisor, HCD and Assembly classes
- support - intended to contain supporting code (todo...)
- ts - implements the CSW Time Service based on Java 8 java.time and Akka
- util - for reusable utility code, including configuration and event classes
The following standalone applications are defined here:
- cs - the config service
The following applications are defined under ../apps:
- asConsole - Alarm Service Console: a command line application for working with alarms
- configServiceAnnex - an http server used to store and retrieve large files, used by the config service
- containerCmd - used to start containers of HCDs or assemblies, based on a given config file (This is not an application, but us used to simplify creating such applications)
- csClient - a command line client to the config service (used in some test scripts)
- sequencer - implements the command line sequencer application, which is a Scala REPL shell
- sysControl - A command line app for setting the log level of running components, sending lifecycle commands, etc.
- trackLocation - a command line app that wraps an external (non csw) application for the purpose of registering it with the location service and unregistering it when it exits
The examples directory contains the following example applications:
- assemblyExample - a simple example assembly that sends messages to the example HCD
- hcdExample - a simple example HCD that generates position events along with an event subscriber that logs them
- vslice - a detailed, end to end, "Vertical Slice" example that demonstrates how to develop and test Assemblies and HCDs in Scala
- vsliceJava - a Java 8 version of the vslice example that demonstrates how to use the CSW software from Java 8
This project uses GitHub Pages for publishing the API documentation.
For CSW-0.2-PDR, the sbt-ghpages plugin was used to generate the scaladoc and publish it (using sbt make-site and ghpages-push-site).
The main page for automatically generting the site is src/site-preprocess/index.html. That page contains pointers to the
API docs and the GitHub sources. Note that the links to the sources are always based on the branch you are working in.
For CSW-0.3-PDR, the gh-pages branch was updated manually, in order to include the Java and Scala API docs. (Using the sbt-ghpages plugin would overwrite the manual version, so don't use that now.)