Actions

Defining an Action

You can easily expose actions to be natively invoked via REST calls by marking them as Accessible.
Overloads actions with the same name are acceptable as long as their signature is different. Note: In the OData API, as opposed to Java, the action parameter names are considered and not their type.

@Accessible (jello.security.Accessible)

Marks a public method as accessible action via REST API. This annotation affects only the action calls via REST API while the Java method access scope is determined, as usual, by the Java access modifiers (public/private). @Accessible annotation has no effect on non-public methods and the Jello annotation processor will issue an error upon such cases.

@Traceable (jello.annotation.Traceable)

Marks an action as traceable and keeps a log of action calls

A jello.log.Trace record will be created the first time an action is called via REST API. It will get updated with the last call's date-time for any sequential call.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

package jello.log;
...
public class Trace extends JelloEntity {
   @KeyElement String path; 	// The request path 
   Integer count;		// Hits count (only if 'Traceable.COUNT' was specified)
   Date firstAccess;		// First access on
   Date lastAccess;		// Last access on
   List<Date> accessLog;	// All access date:time (only if 'Traceable.ALL' was specified) 
	...
}

Syntax:

@Traceable[(trace-options-flags)]
trace-options-flags:
   FIRST_AND_LAST // keep only first and last calls (default) 
   ALL		  // keep all calls
   COUNT	  // includes hits count (default)
   USER	          // append loggedin user to the path 
   WITH_PARAMS    // append input params to the path

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

@Accessible @Traceable
public void visitCampaignPage( String referralID ) {...}
	
@Accessible @Traceable(Traceable.ALL|Traceable.COUNT)
public void visitCampaignPage2( String referralID ) {...}
	
@Accessible @Traceable(Traceable.COUNT|Traceable.USER)
public void visitCampaignPage3( String referralID ) {...}
	
@Accessible @Traceable(Traceable.WITH_PARAMS)
public void visitCampaignPage4( String referralID ) {..}
	
@Accessible @Traceable(Traceable.COUNT)
public static void visitCampaignPage5( String referralID ) {...}

@Run (jello.annotation.Run)

Marks the action as a scheduled cron task.

Syntax:
Cron schedules are specified using a simple English-like format.The following are examples of schedules:

@Run("every 1 days")
@Run("every 2 hours")
@Run("every 30 minutes")

Note: Jello currently supports only a subset of GAE cron schedules format.

Action annotated with @Run annotation must be static public with no input parameters.
A scheduled action must be accessible by 'SYSTEM'.

Examples:

@Accessible({Role.SYSTEM. Role.ADMIN})
@Run("every 7 days")
public static void sendWeeklyDigest() {
   ...
} 

Calling action via REST API

Action's parameters are usually passed in a POST request body. Jello Rest API also support passing action's parameters as part of the URL GET request.

Entity-level action (Static)

A static Java function is accessible via REST call as follows:

/jello/data/NS/Entity/Action([parameters])

Instance-level action

/jello/data/NS/Entity(InstanceID)/Action([parameters])

Example:

public class Campaign extends JelloEntity {
   @KeyElement
   String name;
   
   @Accessible
   public void sendNotification(String message) {
      ...
   } 
}

Invoking action with POST request:

//localhost:8888/jello/data/demo/Campaign("Holidays sale")/sendNotification()	

-- POST body --
{ "message" : "Visit our site and buy more stuff..." }

Invoking action with GET request:

//localhost:8888/jello/data/demo/Campaign("Holidays sale")/sendNotification("message" : "Visit our site ...")	

Invoking action with GET request, using URL parameters:

//localhost:8888/jello/data/demo/Campaign("Holidays sale")/sendNotification()?$format=URLPRM&message=Visit us	

Asynchronous actions

By default, Jello executes actions on the server side synchronously. Sometimes, it is desired to execute an action asynchronously, especially if you know this action's execution time might exceed App Engine 60 seconds limit.

When calling an asynchronous action via rest call, the request will return immediately with an empty response body and 202 Accepted response code. The response includes a Location header pointing to a status monitor resource that represents the current state of the asynchronous processing at: /jello/data/jello.async/Task(async-task-id)

Mark an action as an explicit asynchronous Task

Asynchronous execution Request

Asynchronous task API