Background

Recently there has been a significant move to create languages that run on top of the Java Virtual Machine. These languages are usually integrated as a fundamental "Java Scripting Language" - such as JRuby (an implementation of Ruby), Jython (the equivalent of Python ) and Rhino (a JavaScript implementation) or as a fully defined language that hooks into the JVM at a lower level. Examples of these languages would include Clojure (a functional Lisp dialect), Groovy (a scripting language) and Scala (an object-oriented and functional programming language).

Reflex is a procedural language that hooks into the JVM at a lower level. Its syntax is similar to Python (without the indentation) and there are a number of built-in functions and special operators that are semantic short cuts when interacting with Rapture.

This page provides a detailed description of Reflex.

Why Reflex?

The creators of Rapture felt that it was very important to provide a non-compiled way of running programs "in the cloud". The idea was that Rapture application developers could define a lot of their data manipulations in a scripting language and then have Rapture run these "programs" on the servers that make up an installed system. If such a program could be agnostic to the machine (actual server) it was running on such manipulations could be run in a scalable way across all of the servers that make up a Rapture system.

Initially the support for such a scripting language was built using JRuby and Jython - two well established languages that have a well educated developer base. Unfortunately this support ended up being impractical - both from a licensing perspective and from the fact that the scripting environment for these languages was very resource (time and memory) intensive. For these reasons it was decided to create a small language (now called Reflex) to provide the "glue" for the data interactions in Rapture.

Server hosted scripting

The initial use for Reflex was to provide a scripting language that could be run on a server. However the same language could also be used to help setup a Rapture system and hooks were also built in to handle file based io - something that normally would be restricted on a cloud/distributed server environment. In fact a Reflex environment now has a number of "hooks" that can be implemented (or wired) differently depending on the context. In general the environment looks like the logical diagram below.

(INSERT DIAGRAM HERE)

Here we see that Reflex can reach out to a debugger, a Rapture environment (for calling its API), a Scripting environment (for loading other scripts) and an IO sub-system for loading and saving data to a file system.

When running within a Rapture server, the implementations are frozen to protect the environment:

(INSERT DIAGRAM HERE)

Here the debugger and the file/IO subsystems are disabled.

Reflex can also be run on a local desktop, or on a server outside of a Rapture environment. In this case the bindings of the environment are as below:

(INSERT DIAGRAM HERE)

In this case the environment has a Rapture system wired in via a standard HTTP based API - all Rapture commands in Reflex will still work through that API. In a server based environment the security context is set by Rapture (and is based on the ultimate initiator of the Reflex process). In the external approach the user security context is set either by using a Rapture "API key" or by logging in manually through the Reflex runner application.

Installing Reflex

There are three options for using Reflex. The most common use for Reflex is to run scripts from within a Rapture environment - you upload scripts to Rapture and then call them through either Rapture's API call runProgram or through a Rapture workflow or event handling. For testing and debugging it is preferable to install a local environment to play with. This section describes how to do that.

Reflex is bundled into an application called ReflexRunner that can be used to run Reflex scripts. ReflexRunner is a command line java application that is part of the open source release of Rapture. Once downloaded or built it can be run using java as follows:

java -jar [ReflexRunner.jar] 
      -r [RaptureAPIURL] -f [ReflexScript]

Optional parameters are listed below:

-u 'user' - User name to login as
-p 'password' - Password to use
-d - Start debugger

Reflex fundamentals

Reflex is a basic procedural language with a few special operators and built-in functions to make Rapture interactions quicker to write. In this case the meaning of "procedural" is simply that in Reflex you can define functions and invoke those functions. This section describes the fundamental characteristics of the language.

Hello, world

The simplest program in Reflex uses the built-in function println to print out the contents to standard out:

// This is Hello World in Reflex
println('Hello, world');

Running the above program in ReflexRunner will print out the string 'Hello, world' on the console. It introduces two concepts. Line 1 shows how comments are defined in Reflex. Comments are prefixed with a double slash and continue to the end of the line. This is the only comment style in Reflex. Line 2 shows the built-in function println and the fact that strings can be enclosed either in single quotes or double quotes. Finally statements in Reflex are terminated by semi-colons.

Next steps

[Reflex Variables and Types](Reflex Variables and Types)

[Operators](Reflex Operators)

[Exceptions](Reflex Exceptions)

[Special Operators](Reflex Special Operators)

[User Defined Functions](Reflex User Defined Functions)

[Modules](Reflex Modules)

[Functional Aspects](Reflex Functional Aspects)

[Suspension and Coordination](Reflex Suspension)

[Reflex Page Scripting](Reflex Page Scripting)

[Built in Functions](Reflex Builtin Functions)