X
X

Login

Login if you already have an account

LOGIN

Register

Create a new account. join us!

REGISTER

Support

Need some help? Check out our forum.

FORUM
July 6, 2012 vprakash@miegoapps.com

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.

DownloadDownloadDownloadDownload

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
STRINGJava definition http://www.linfo.org/string.html.
NUMERICAll numeric datatypes, including, for example, int, long, short, float and double.
DATEDate values down to millisecond precision. Stored as milliseconds since Jan 1 1970. (Negative implies a date before Jan 1 1970)
BOOLEANA logical value, either “true” or “false”.
[]Arrays. A single-dimension list of constituents; arrays are always defined as ‘of some datatype,’ including objecttypes (e.g. STRING[] or []).
BYTEARRAYAn array of bytes, usually used as a container for files such as images, video or source-code.
MAPA list of key/value pairs, sometimes called a hashmap or dictionary.
GEOLOCATIONA map (dictionary) which conforms to the W3C Coordinates specification. At a minimum, latitude and longitude must be supplied.
UNVALIDATEDNo validation is done on this member. Datatype is non-determinant to your app’s backend. You can assign a datatype of unvalidated[], as well.
OBJECTTYPEThe name of an object which has previously been defined (e.g. Message, Task or Order). Embeds that object's datastructure as a member.
REFERENCE [/]A pointer to another object (i.e. indirect reference). Incorporated as part of the clientside object model. If the optional / is provided, the reference may only point to objects in the specified collection. See References for more info.
GRABBAG [/]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 / is provided, the grab bag may only contain objects from the specified collection. See GrabBags for more info.

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-configDirectory containing configuration files for your API.
.appName
Hidden file containing your API's name.
application.ffdl
FFDL metadata descriptor that controls your API
context.xml
Descriptor file declaring your API and subdomain names.
fatfractal.xml
Descriptor file declaring other parameters for your API.
ff-scriptsDirectory containing scripts for ServerSide Code.
webappDirectory containing the web application interface to your API.
index.html
HTML file defining the web application interface to your API.

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
sdkDirectory 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
userNameStringUser name, used for login. Must be unique to your application.
firstNameStringFirst name of user.
lastNameStringLast name of user.
emailStringEmail address of user.
activeBooleanWhether the user has been activated. If a user account is not active, that user may not log in.
groupsGrab bagFFUserGroup 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:
[tabs_framed] [tab title="iOS"] FatFractal *ff = [FatFractal main];
FFUser *loggedInUser = ff.loggedInUser;
[/tab] [tab title="Java (Android)"]

FatFractal ff = FatFractal.getMain();
FFUser loggedInUser = ff.getLoggedInUser();
[/tab] [tab title="JS (HTML5)"]
var ff = new FatFractal();
...
var loggedInUser = ff.FFUser(ff.loggedInUser());
[/tab] [/tabs_framed]

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
groupNameStringName of the group.
usersGrab bagFFUser 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
latitudeNumericLatitude in degrees. Required.
longitudeNumericLongitude in degrees. Required.
altitudeNumericAltitude in meters.
accuracyNumericAccuracy of latitude and longitude (95% confidence interval.)
altitudeAccuracyNumericAccuracy of altitude (95% confidence interval.)
headingNumericDirection of movement in degrees. NaN if speed is zero.
speedNumericMagnitude 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:
    [tabs_framed] [tab title="iOS"] @interface NotesUserGroup : FFUserGroup
    @property (strong, nonatomic) NSString *notes;
    @end
    [/tab] [tab title="Java (Android)"]
    public class NotesUserGroup extends FFUserGroup
    {
    private String m_notes;

    public String getNotes() { return m_notes; }
    public void setNotes(String notes) { m_notes = notes; }
    }

    [/tab] [/tabs_framed]
  2. Change the FFDL definition of FFUserGroup:
    CREATE OBJECTTYPE FFUserGroup (groupName STRING, users GRABBAG /FFUser, notes STRING)
  3. Register NotesUserGroup with the FatFractal library:
    [tabs_framed] [tab title="iOS"] [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.
    //
    [/tab] [tab title="Java (Android)"]
    FFObjectMapper.registerClassNameForClazz(NoteUserGroup.class.getName(), "FFUserGroup");
    [/tab] [/tabs_framed]

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
createdAtDate
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.
createdByString
lF0J_bnwLRgrkEI4vSjod7
GUID of the FFUser who created the object.
ffRLString
/Celebrity
The Collection resource that the object lives in
ffUrlURL
/ff/resources/Celebrity/lF0J_bnwLRgrkEI4vSjod7
The location of the resource in question. Appends to the BaseURL.
ffUserCanEditBoolean
true
Whether or not the currently logged-in user has write privileges for this object.
guidString
lF0J_bnwLRgrkEI4vSjod7
Unique to your app's namespace. Identifies a specific object in a particular collection.
objVersionNumeric
19
The number of times an object has been updated.
updatedAtDate
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.
updatedByString
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
ComparisoneqEqual to(guid eq 'abc123')
neNot equal to(userName ne 'steve')
ltLess than(age lt 8)
lteLess than or equal to(age lte 7)
gtGreater than(age gt 20)
gteGreater than or equal to(age gte 21)
betweenBetween(rating between 7 and 10)
String matching / searchcontains_allTextual 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_anyTextual 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_withString 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’)
matchesString 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
BooleanandAND(title eq 'Breaking Bad' and season eq 5)
orOR(guid eq 'abc123' or userName eq 'Steve')
notNegation (NOT)(not (userName matches '[a-z].*'))
NumericplusAddition((length plus width) gt 5)
minusSubtraction(income minus expenses) gt 10000
divDivision(distance div time lt 55)
timesMultiplication((length times width) between 5 and 10)
modModulo division(n mod 2 eq 0)
DatenowCurrent date/time(createdAt lt now)
todayMidnight last night (UTC)(updatedAt gt today)
tomorrowMidnight tonight (UTC)(dueDate between now and tomorrow)
yesterdayMidnight night before last (UTC)(dueDate gt yesterday)
string literalsISO8601 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 Functionsdate_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
BitwisebwandBitwise AND((flags bwand mask) ne 0)
bwiorBitwise OR (inclusive)(((flags bwior 4) bwand mask) ne 0)
bwxorBitwise exclusive OR((flags bwxor mask) eq 0)
Randomrandom(guid)Return a guid from a random object(guid eq random(guid))
GeolocationdistanceReturn 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>[highlight1 variation="yellow"]/ff/resources/collection/guid[/highlight1]

<scheme>://<domain name>.fatfractal.com/<application name>[highlight1 variation="hotpink"]/ff/ext/extName[/highlight1]

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.

[titled_box title=”BaseURL: <scheme>://<domain name>.fatfractal.com/<application name>” variation=”silver”]
Platform Naming Convention
Scope
Usage
Form
Valid URI
domain nameThird-level domainThis subdomain allows you to refer to a set of applications as a logical group. Domains are created in the FatFractal ConsolealphanumRequired
(or localhost if not deploying to cloud)
fatfractalSecond-level domainPart of URL that points to the FatFractal platformsingle valueRequired
comTop-level domainPart of URL that points to the FatFractal platformsingle valueRequired
application nameSpecific app nameA 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
[/titled_box] [titled_box title=”OBJECTS: <BaseURL>/ff/resources/<collection>/<guid>” variation=”yellow”]
PLATFORM NAMING CONVENTION
SCOPE
USAGE
FORM
VALID URI
resourcesTargets an area of your app’s backendDefines the namespace, available to your app’s backend, which refers to objects and valuesvalue is ‘resources’Required value to refer to objects and values
collectionPoints 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
guidRefers to an objectThe 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
ffTargets the FatFractal PlatformThis tag is required.value is ‘ff’required
[/titled_box] [titled_box title=”SERVER EXTENSIONS: <BaseURL>/ff/ext/<extension name>” variation=”hotpink”]
PLATFORM NAMING CONVENTION
SCOPE
USAGE
FORM
VALID URI
extTargets 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 nameThe 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
ffTargets the FatFractal PlatformThis tag is required.value is ‘ff’required
[/titled_box]

Contact