NoServer Reference


Note:

This is the reference guide with brief overviews of behaviour and (where appropriate) syntax. The detailed developer guides are at Docs


↓ API↓ Command-Line↓ Datatypes↓ Directories↓ Objects↓ FFDL↓ Metadata↓ Queries↓ URIs

API Docs

API • ↓ Command-Line↓ Datatypes↓ Directories↓ Objects↓ FFDL↓ Metadata↓ Queries↓ URIs

FatFractal NoServer supports a variety of clientside and serverside environments.

You can access the following API docs from this page. Clicking on the links below will open a new window.

Download Download Download Download


Command-Line Tools

↑ API • Command-Line • ↓ Datatypes↓ Directories↓ Objects↓ FFDL↓ Metadata↓ Queries↓ URIs


ffef

 

The ffef command is used for controlling your backend application. It is located in the bin directory of your locally installed FatFractal_Runtime. ffef supports the following:
  • Commands for all application types
    • ffef deployFFFabric
      • Deploys the application in the current directory to the FatFractal fabric, i.e. the cloud.
    • ffef deploylocal
      • Deploys the application in the current directory to your locally installed FatFractal runtime
    • ffef update
      • Checks if there are newer releases available to be installed
    • ffef update <release name>
      • Updates your local runtime to the named release
  • Commands for NoServer applications only
    • ffef newapp <application name> <domain>
      • Scaffold a new application with the specified domain. Generally run from within a directory specifically for the application. Scaffolding creates the directory structure and default configuration files for your NoServer application.
    • ffef getFFDL <local application URL>
      • Retrieve the FFDL application definition from the application at the specified URL. Should be run from the application’s root directory.
      • When you run this command, the application’s current application.ffdl file is renamed to application.ffdl.<datetime>, and the application definition retrieved from the provided URL is saved as application.ffdl.



ff-service

 

The ff-service command is used to start and stop a local engine. The command should be run from the root directory of your locally installed runtime (eg ~/FatFractal_Runtime). The executable is located in the bin directory of your install. The forms of the command are:
  • ff-service cl
    • Start the engine in the foreground.
  • ff-service start
    • Start the engine in the background.
  • ff-service stop
    • Stop the engine running in the background.
USAGE NOTE By default, your engine is configured to use ports 8080 and 8443 for http and https respectively. If you wish to use the default ports (80 and 443) then you should
  • edit the conf/config_include.properties file
  • run the ff-service command as a privileged user. (Use sudo on Unix, Run As Administrator on Windows)


Datatypes

↑ API↑ Command-Line • Datatypes • ↓ Directories↓ Objects↓ FFDL↓ Metadata↓ Queries↓ URIs

This table lists the backend datatypes supported by FatFractal. The unvalidated datatype may only be assigned using either the FatFractal Definition Language (FFDL) or JavaScript Serverside (JSSS).

Datatype Description
STRING Java definition http://www.linfo.org/string.html.
NUMERIC All numeric datatypes, including, for example, int, long, short, float and double.
DATE Date values down to millisecond precision. Stored as milliseconds since Jan 1 1970. (Negative implies a date before Jan 1 1970)
BOOLEAN A logical value, either “true” or “false”.
<type>[] Arrays. A single-dimension list of constituents; arrays are always defined as ‘of some datatype,’ including objecttypes (e.g. STRING[] or <objecttype name>[]).
BYTEARRAY An array of bytes, usually used as a container for files such as images, video or source-code.
MAP A list of key/value pairs, sometimes called a hashmap or dictionary.
GEOLOCATION A map (dictionary) which conforms to the W3C Coordinates specification. At a minimum, latitude and longitude must be supplied.
UNVALIDATED No validation is done on this member. Datatype is non-determinant to your app’s backend. You can assign a datatype of unvalidated[], as well.
OBJECTTYPE The name of an object which has previously been defined (e.g. Message, Task or Order). Embeds that object’s datastructure as a member.
REFERENCE [/<collection name>] A pointer to another object (i.e. indirect reference). Incorporated as part of the clientside object model. If the optional /<collection name> is provided, the reference may only point to objects in the specified collection. See Data Modeling.
GRABBAG [/<collection name>] A named set of references to other objects. Not incorporated as part of the clientside object model; clientside SDKs provide methods to add, remove, access, and modify grab bags. If the optional /<collection name> is provided, the grab bag may only contain objects from the specified collection. See Data Modeling.


Directory Layout

↑ API↑ Command-Line↑ Datatypes • Directories • ↓ Objects↓ FFDL↓ Metadata↓ Queries↓ URIs

Scaffolded Application

When you scaffold an application, the following directory structure is created.

ff-config Directory containing configuration files for your application.
.appName
Invisible file containing your application’s name.
application.ffdl
Main configuration file for your application’s backend. See Application Configuration.
context.xml
Descriptor file declaring your application name and domain name.
fatfractal.xml
Descriptor file declaring other parameters for your application.
ff-scripts Directory containing custom code scripts. See Custom Code.
webapp Directory containing the web application interface to your application’s backend.
index.html
HTML file defining the web application interface to your application’s backend.


Installation

When you install FatFractal on your local machine, the following directory structure is created. Depending on your installation options, not all files may be present.

runtime Directory containing files necessary to scaffold and deploy an application and to run a local engine.
archive
bin
Directory containing local engine executables.
ff-service
Executable to run a local engine.
clone
conf
Directory containing configuration files.
.pem
Your credentials for deploying applications to the cloud. Do not distribute your credentials!
config.properties.c
Encrypted engine configuration file.
keystore.js
domain
Root directory for local deployments.
ffnsbin
Directory containing executables for application creation and deployment.
ffef
Executable for application creation and deployment. See the Command Line Reference.
template.*
Template files for application scaffolding.
lib
Library directory for local engine.
logs
Log directory for local engine.
fatfractal.log
Local engine log file.
module
Module directory for local engine.
queue
Queue directory for local engine. WAR files in this directory are periodically detected by a running local engine and deployed.
scripts
Directory containing FatFractal serverside SDKs to aid serverside development
store
sdk Directory containing the FatFractal clientside SDKs.


FF Special Objects

↑ API↑ Command-Line↑ Datatypes↑ Directories • Objects • ↓ FFDL↓ Metadata↓ Queries↓ URIs

The FatFractal Platform supplies a few other built-in objects for particular purposes. Certain members of these special objects, as well as their datatypes, are pre-defined by the FatFractal Platform; in most cases you can add fields and subclass these objects as well.

FFUser

The FFUser object is an object, like any other, except that it has pre-defined members which are useful for managing end-users of your application. For example, FFUser objects have authentication information associated with them. Those members are:

Member Type Description
userName String User name, used for login. Must be unique to your application.
firstName String First name of user.
lastName String Last name of user.
email String Email address of user.
active Boolean Whether the user has been activated. If a user account is not active, that user may not log in.
groups Grab bag FFUserGroup objects representing groups to which this user belongs.

You may use and add to the members of the FFUser object in the same way as you would to any other object in your application; however you may not remove the pre-defined members from the object definition.

The groups member is a grab bag containing all the FFUserGroup objects owned by the FFUser. The groups member starts empty, and is manipulated using methods in the client APIs.

The active member default depends on the value of ActivateUsersOnReg parameter in your application’s application.ffdl file. If ActivateUsersOnReg is true, newly created FFUser objects begin with active set to true.

System User

Every FatFractal application has a special user, with username and guid system. This user has read and write permission to everything in the application, similar to root on *nix systems. In a local deployment, you may login as system (using password system) for convenience in modifying objects in your datastore. Additionally, all serverside custom code is run as the system user.

Logged-In User

The client SDKs provide methods to retrieve the FFUser object of the currently logged-in user:

FatFractal *ff = [FatFractal main];
FFUser *loggedInUser = ff.loggedInUser;
FatFractal ff = FatFractal.getMain();
FFUser loggedInUser = ff.getLoggedInUser();
var ff = new FatFractal();
...
var loggedInUser = ff.FFUser(ff.loggedInUser());

User login and registration is always done via HTTPS for over-the-wire security. User passwords are stored as hashes using the PBKDF2 function, using SHA1-HMAC for its random number generator, and every hash is created using a unique random 128-bit salt per user.

See Managing Users and the API Reference.

FFUserGroup

The FFUserGroup is a system object for managing sets of FFUser objects. One of the primary functions of the FFUserGroup is to provide a simple way to add and remove OAPs to sets of FFUsers; see Permissions.

FFUserGroup has the following members:

Member Type Description
groupName String Name of the group.
users Grab bag FFUser objects representing members of the group.

See Managing Groups and the API Reference.

FFGeoLocation

The FFGeoLocation object encapsulates geolocation information across clients and facilitates geo-queries. This object is used in conjunction with the GEOLOCATION backend datatype.

FFGeoLocation has the following members:

Member Type Description
latitude Numeric Latitude in degrees. Required.
longitude Numeric Longitude in degrees. Required.
altitude Numeric Altitude in meters.
accuracy Numeric Accuracy of latitude and longitude (95% confidence interval.)
altitudeAccuracy Numeric Accuracy of altitude (95% confidence interval.)
heading Numeric Direction of movement in degrees. NaN if speed is zero.
speed Numeric Magnitude of horizontal component of velocity, in meters per second.

See the API Reference.

Subclassing

You may want to extend the functionality of FF Special Objects by subclassing them. Doing so involves three steps:

  1. Subclass the class you would like to extend.
  2. Add any new members you’ve added to the objecttype definition of the original objecttypein your application.ffdl file.
  3. Register your new class with the FatFractal library, so that it maps to your new class instead of the built-in one.


Example

Let’s say we want to subclass FFUserGroup so that it includes a new string member called notes. Here’s how we would do it:

  1. Define a new class, which we will call NotesUserGroup:
    @interface NotesUserGroup : FFUserGroup
    @property (strong, nonatomic) NSString *notes;
    @end
    
    public class NotesUserGroup extends FFUserGroup
    {
        private String m_notes;
    
        public String getNotes() { return m_notes; }
        public void setNotes(String notes) { m_notes = notes; }
    }
    
  2. Change the FFDL definition of FFUserGroup:
    CREATE OBJECTTYPE FFUserGroup (groupName STRING, users GRABBAG /FFUser, notes STRING)
    
  3. Register NotesUserGroup with the FatFractal library:
    [ff registerClass:[NotesUserGroup class] forClazz:@"FFUserGroup"];
    //
    // IMPORTANT: Right now, registerClass:forClazz: will only take effect for the
    // FatFractal object on which you invoke it. This means that if you have multiple
    // 'FatFractal' objects then you would need to invoke registerClass:forClazz:
    // on each one. In the next release this behaviour will be changed so that
    // registerClass:forClazz: will take effect across all instances.
    //
    
    FFObjectMapper.registerClassNameForClazz(NoteUserGroup.class.getName(), "FFUserGroup");
    


FFDL

↑ API↑ Command-Line↑ Datatypes↑ Directories↑ Objects • FFDL • ↓ Metadata↓ Queries↓ URIs


FFDL (FatFractal Definition Language) is a simple DSL which instructs the FatFractal platform as to the configuration of your NoServer application. The application.ffdl file of your NoServer contains the FFDL which is executed upon your application being deployed or redeployed. However you may also execute FFDL commands against a running NoServer application if you are logged in to that application as the system user. Detailed descriptions of each command are provided below, but here’s a quick list:


SET command

SET commands take the general form

SET <parameter> <value>

Options for <parameter> and associated options for <value> are given in the following tables.

Registration parameters

Schema control (aka ‘Learn Mode’) parameters

Push parameters

Other parameters

Security parameters

CORS (Cross-Origin Resource Sharing)


SET_PRIVATE command

As per the SET command below, but when retrieving application metadata via the web, settings which are created using SET_PRIVATE are not visible. Some parameters are always private – these are:

  • AndroidPushAuthToken
  • ApplePushKeystorePassword
  • SystemUserPassword
  • SystemUserEmail



CREATE command

CREATE COLLECTION

The syntax to create a collection is

CREATE [PRIVATE] COLLECTION /<collection name> [OBJECTTYPE <objecttype>[, <objecttype>, ...]]
  • If OBJECTTYPE is provided, then the collection may only contain objects of the listed objecttypes. Otherwise, the collection may contain objects of any objecttype.
  • If the PRIVATE modifier is provided, then
    • Only server-side code can interact with this collection
    • All requests from the web to directly create, retrieve, update or delete any object in a private collection will fail with a 404 not found
    • metadata retrieved normally (i.e. not by the system user requesting text/plain) will not include details of this collection
      • This means that, for example, the collection will not be visible to the data browser.
    • If retrieving objects indirectly then objects from private collections are filtered out of the response – for example
      • via a traversal /Something/(some query)/traversalToPrivateCollection
      • retrieved indirectly by queries using the depthRef or depthGb parameters /Something/(some query)?depthRef=1


CREATE OBJECTTYPE

The syntax to create a new objecttype is

CREATE [PRIVATE] OBJECTTYPE <objecttype name> (<member>[, <member>, ...])

If the PRIVATE modifier is provided, then metadata retrieved normally (i.e. not by the system user requesting text/plain) will not include details of this OBJECTTYPE. This means that, for example, the collection will not be visible to the data browser.

Each <member> is given as follows:

<member name> [ ENCRYPTED ] <backend datatype>

ENCRYPTED applies only to the backend datatype STRING; if provided, the member is stored encrypted on your app’s backend. For the supported backend datatypes, see Backend Datatypes.

CREATE ALIAS

Aliases allow you to set up shorter names for referring to grab bags, as a convenience. The syntax to create an alias is

CREATE ALIAS ON OBJECTTYPE <objecttype name> GRABBAG <grab bag name> AS <alias>


CREATE HANDLER

See also the development guide here.
The syntax to associate a CRUD event or trigger to an event handler is

CREATE HANDLER <handler name> [ PRE | POST | ASYNC ] ON /<collection name> [ Create | Retrieve | Update | Delete | GrabBag_Add | GrabBag_Remove ] AS <script type>:<script text>
The keyword following the handler name specifies when the handler script should execute:
PRE indicates that the handler executes synchronously, before the CRUD event takes place on the data store
POST indicates that the handler is executed synchronously, after the CRUD event takes place on the data store – but before the response is returned to the client
ASYNC indicates that the handler is executed asynchronously, after the CRUD event takes place on the data store.
The keyword following the collection name specifies which events this handler fires for, on this collection:
Create upon creation of a new object in a collection
Retrieve upon retrieval of an object from a collection. NOTE:Retrieve handlers may currently only be used with the POST modifier from the list above
Update upon updating an object in a collection
Delete upon deletion of an object in a collection
GrabBag_Add upon adding an item to a grab bag
GrabBag_Remove upon removing an item from a grab bag

See also the development guide here.

CREATE EXTENSION

A server extension (or API extension) is another method for triggering serverside code, which, in this case executes on HTTP GET requests to a specified URI. The syntax to associate a server extension name to its code is

CREATE EXTENSION /<extension name> [ UNSECURED ] AS <script type>:<script text>

By default, a server extension can only be triggered by a user who is logged in. The optional UNSECURED keyword allows users that are not logged in to execute the extension.

See Custom Code.



DROP command

Removes a collection from your app’s metadata.

DROP COLLECTION

(NOTE:Data is not removed from the collection)

DROP COLLECTION /<collection name>
DROP COLLECTION COMPLETELY

(NOTE:All data is removed the database when you use the ‘COMPLETELY’ modifier)

DROP COLLECTION COMPLETELY /<collection name>


DROP OBJECTTYPE

Removes an object-type from your app’s metadata.

DROP OBJECTTYPE /<object-type name>


PERMIT command

The PERMIT command is used to set default OAPs for individual users and/or groups with the specified permissions on collections. These defaults may be altered in code during runtime using FatFractal’s declarative security. The syntax for the PERMIT command is

PERMIT create:<group>[,<group>,...] read:<group>[,<group>,...] write:<group>[,<group>,...] ON /<collection name>

See Permissions and Managing Users.

SCHEDULE command

The SCHEDULE command is used to schedule execution of serverside code. The syntax of the SCHEDULE command is

SCHEDULE <task name> <schedule> AS <script type>:<script text>

<schedule> is given in cron syntax:

<minute (0-59)> <hour (0-23)> <day of month (1-31)> <month (1-12)> <day of week (0-6)>

Each parameter may also be the character *, indicating all.
See Custom Code.

Metadata

↑ API↑ Command-Line↑ Datatypes↑ Directories↑ Objects↑ FFDL • Metadata • ↓ Queries↓ URIs

Whenever you create an object, the FatFractal Platform returns metadata about that object. The FatFractal Platform provides a built-in datatype, FFMetaData, to encapsulate this metadata. As for all built-in types, each of the FatFractal APIs provides an FFMetaData type appropriate for the API’s platform.

Metadata Item Info Type and Example Comments
createdAt Date
Date
In the format your client expects it to be in. Natively stored on you app’s backend as number. of milliseconds since January 1 1970.
createdBy String
lF0J_bnwLRgrkEI4vSjod7
GUID of the FFUser who created the object.
ffRL String
/Celebrity
The Collection resource that the object lives in
ffUrl URL
/ff/resources/Celebrity/lF0J_bnwLRgrkEI4vSjod7
The location of the resource in question. Appends to the BaseURL.
ffUserCanEdit Boolean
true
Whether or not the currently logged-in user has write privileges for this object.
guid String
lF0J_bnwLRgrkEI4vSjod7
Unique to your app’s namespace. Identifies a specific object in a particular collection.
objVersion Numeric
19
The number of times an object has been updated.
updatedAt Date
Date
In the format your client expects it to be in. Natively stored on you app’s backend as number of milliseconds since January 1 1970.
updatedBy String
lF0J_bnwLRgrkEI4vSjod7
GUID of the FFUser who last modified the object.

For information on how to retrieve the metadata for an object using a specific API, see the API Reference.

Query Language

↑ API↑ Command-Line↑ Datatypes↑ Directories↑ Objects↑ FFDL↑ Metadata • Queries • ↓ URIs

The following table lists the query operators available on the FatFractal Platform. See Queries and Data Modeling.

NOTES:
  • Operations are always performed left to right
  • Parentheses will group operations as you would expect
  • Single quotes are used to define a literal string, rather than double-quotes
  • Comparisons with ‘null’ ARE allowed. For example GET /Foo/(bar eq null)
Class Operator Description Examples
Comparison eq Equal to (guid eq ‘abc123′)
ne Not equal to (userName ne ‘steve’)
lt Less than (age lt 8)
lte Less than or equal to (age lte 7)
gt Greater than (age gt 20)
gte Greater than or equal to (age gte 21)
between Between (rating between 7 and 10)
String matching / search contains_all Textual term search. Will match where ALL of the supplied terms are found in the field being searched. Term search is case-insensitive (messageText contains_all ‘politics US presidential’)
contains_any Textual term search. Will match where ANY of the supplied terms are found in the field being searched. Term search is case-insensitive (messageText contains_any ‘football soccer’)
starts_with String starts with supplied expression.

NB: Case sensitive. Store a field with its data case-normalized if you wish case insensitivity. A future release will allow for case insensitivity

(tag starts_with ‘A’)
matches String matches regular expression (userName matches ‘[a-z].*’)

NOTE: Beware of using the ‘matches’ operator alone on a collection as it will have to scan all objects in that collection. Ideally you would either combine with another predicate, or use the contains_all or contains_any operator if you are looking for textual terms

Boolean and AND (title eq ‘Breaking Bad’ and season eq 5)
or OR (guid eq ‘abc123′ or userName eq ‘Steve’)
not Negation (NOT) (not (userName matches ‘[a-z].*’))
Numeric plus Addition ((length plus width) gt 5)
minus Subtraction (income minus expenses) gt 10000
div Division (distance div time lt 55)
times Multiplication ((length times width) between 5 and 10)
mod Modulo division (n mod 2 eq 0)
Date now Current date/time (createdAt lt now)
today Midnight last night (UTC) (updatedAt gt today)
tomorrow Midnight tonight (UTC) (dueDate between now and tomorrow)
yesterday Midnight night before last (UTC) (dueDate gt yesterday)
string literals ISO8601 format yyyy-mm-ddThh:mm:ss:SSS where TimeZoneOffset is either Z (which means UTC) or +HH:MM or -HH:MM (pubDate gt ’1999-12-31T23:59:59.999Z’)
Date Functions date_add(date, datePart, delta) Add delta to a date
For example one way of getting midnight last night in Pacific Standard Time would be date_add (today, hour, 8) – i.e. 8am today, UTC
(’2000-01-01T00:00:00.000Z’, millisecond, -1)
date_round(date, datePart) Round date to nearest datePart. i.e. If you round to a day, then you will get midnight (UTC) on that date. If you round a month, then you will get midnight on the first of that month, etc. date_round(’2004-01-11T14:15:16.123Z’, month) would evaluate to 2004-01-01T00:00:00.000Z
Date Parts (for use in Date Functions) year
month
day
hour
minute
second
millisecond
A calendar year
A calendar month
A day
An hour
A minute
A second
A millisecond
date_add(now, year, -1)
date_add(now, month, -1)
date_add(now, day, -1)
etc
Bitwise bwand Bitwise AND ((flags bwand mask) ne 0)
bwior Bitwise OR (inclusive) (((flags bwior 4) bwand mask) ne 0)
bwxor Bitwise exclusive OR ((flags bwxor mask) eq 0)
Random random(guid) Return a guid from a random object (guid eq random(guid))
Geolocation distance Return the distance between two GEOLOCATION objects in meters // find objects where the distance from the location to
// lat 45.1 lon -122.2 is <= 10 kilometers
(distance(location, [45.1, -122.2]) lte 10000)


URI Structure

↑ API↑ Command-Line↑ Datatypes↑ Directories↑ Objects↑ FFDL↑ Metadata↑ Queries • URIs

URLs on the FatFractal Platform are extensions of your application’s base URL:

<scheme>://<domain name>.fatfractal.com/<application name>

Or, if you are working locally:

<scheme>://localhost/<application name>

There are two groupings of allowed URLs:

<scheme>://<domain name>.fatfractal.com/<application name>/ff/resources/collection/guid

<scheme>://<domain name>.fatfractal.com/<application name>/ff/ext/extName

For information on how resources are organized on the FatFractal Platform, see Resource Hierarchy. For information on finding objects using queries and traversals, see Queries and Data Modeling, respectively.

BaseURL: <scheme>://<domain name>.fatfractal.com/<application name>
Platform Naming Convention Scope Usage Form Valid URI
domain name Third-level domain This subdomain allows you to refer to a set of applications as a logical group. Domains are created in the FatFractal Console alphanum Required
(or localhost if not deploying to cloud)
fatfractal Second-level domain Part of URL that points to the FatFractal platform single value Required
com Top-level domain Part of URL that points to the FatFractal platform single value Required
application name Specific app name A backend is created for each app, by application name. The BaseURL defines all resources “owned” by an app. Applications are created in the FatFractal Console. unique to a domain
alphanum
Required
OBJECTS: <BaseURL>/ff/resources/<collection>/<guid>
PLATFORM NAMING CONVENTION SCOPE USAGE FORM VALID URI
resources Targets an area of your app’s backend Defines the namespace, available to your app’s backend, which refers to objects and values value is ‘resources’ Required value to refer to objects and values
collection Points to a set of objects A set of objects that is “grouped” into a shared namespace on your app’s backend. Name is unique to the application’s namespace
(alphanum)
required
guid Refers to an object The term guid is always used to refer to a pointer to an object on the FatFractal Platform; may be assigned directly, if not, it is generated for you. Name is unique to the application’s namespace
(alphanum)
required
ff Targets the FatFractal Platform This tag is required. value is ‘ff’ required
SERVER EXTENSIONS: <BaseURL>/ff/ext/<extension name>
PLATFORM NAMING CONVENTION SCOPE USAGE FORM VALID URI
ext Targets an area of your app’s backend Defines the namespace, available to your app’s backend, which refers to serverside API extensions your app has access to. Value is ‘ext’ optional
extension name The name of a server extension The server extension here must have been created and refer to a specific file and function in that file.
See Custom Code for more information.
Unique
(alphanum)
required
ff Targets the FatFractal Platform This tag is required. value is ‘ff’ required